Website widgets

LeadTruffle also provides browser-embedded web clients (chat widgets). These JavaScript APIs are separate from the REST API and are available after each widget script loads.

Install your widget

1. Copy the installation snippet for your company from the widget setup in your LeadTruffle dashboard.
2. Paste the snippet before the closing </body> tag on each page where the widget should appear, or use your website builder's equivalent footer-code setting.
3. Publish the website change, open the page, and confirm the widget appears. Keep your REST API key out of the embed code.

The snippet loads and initializes the widget. The methods below are for additional customization after its script has loaded.

Choose the right browser API

Standard Chat Widget (window.LTWidget)

Methods:

• initialize({ companyId, initialMessage? })
• open({ initialMessage? })
• setAttribution({ gclid?, utm_source?, utm_medium?, utm_campaign?, utm_term?, utm_content?, ... })
• destroy()

Example:

if (window.LTWidget && typeof window.LTWidget.initialize === 'function') {
  window.LTWidget.initialize({
    companyId: 'YOUR_COMPANY_UUID',
    initialMessage: 'Hi! How can we help today?',
  })
}

if (window.LTWidget && typeof window.LTWidget.open === 'function') {
  window.LTWidget.open({
    initialMessage: 'Need help with pricing or scheduling?',
  })
}

if (window.LTWidget && typeof window.LTWidget.setAttribution === 'function') {
  window.LTWidget.setAttribution({
    gclid: 'GOOGLE_CLICK_ID',
    utm_source: 'google',
    utm_medium: 'cpc',
    utm_campaign: 'spring-service',
  })
}

Franchise Widget (window.FranchiseLeadtruffle)

Methods:

• initialize({ agencyId, initialMessage? })
• open({ initialMessage? })
• setAttribution({ gclid?, utm_source?, utm_medium?, utm_campaign?, utm_term?, utm_content?, ... })
• destroy()

Popup Widget (window.TPOPWidget)

Methods:

• initialize({ companyId })
• show()
• reset()
• setAttribution({ gclid?, utm_source?, utm_medium?, utm_campaign?, utm_term?, utm_content?, ... })
• destroy()

Other Web Clients

• window.LTWebchat: initialize({ companyId, initialMessage? }), prefillLead({ name?, email?, phone?, metadata? }), setAttribution({ gclid?, utm_source?, utm_medium?, utm_campaign?, utm_term?, utm_content?, ... }), open({ initialMessage? }), destroy()
• window.TJSFormWidget: initialize({ companyId, targetElement? }), setAttribution({ gclid?, utm_source?, utm_medium?, utm_campaign?, utm_term?, utm_content?, ... }), show(), hide(), destroy()

prefillLead(...) is only available on the webchat widget. It lets you pre-populate the initial lead form and attach custom metadata that will be submitted with that webchat lead. This does not apply to the standard website texting widget, popup widget, franchise widget, or JS form widget.

setAttribution(...) is available on all current JavaScript widget clients. LeadTruffle automatically captures supported URL parameters and falls back to the Google Ads _gcl_aw first-party cookie for gclid when available. Use setAttribution(...) only when your site or tag manager already has attribution values that you want to push into the LeadTruffle widget context. Supported fields include utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid, msclkid, ttclid, snapcid, gbraid, wbraid, gad_source, igshid, gclsrc, and srsltid.

Example:

if (window.LTWebchat && typeof window.LTWebchat.initialize === 'function') {
  window.LTWebchat.initialize({
    companyId: 'YOUR_COMPANY_UUID',
  })
}

if (window.LTWebchat && typeof window.LTWebchat.prefillLead === 'function') {
  window.LTWebchat.prefillLead({
    name: 'Jane Smith',
    email: 'jane@example.com',
    phone: '+15555550123',
    metadata: {
      userId: 'internal-user-123',
      sourceApp: 'tooldesk-next',
    },
  })
}

Browser Compatibility Guidance

Because embeds can run on unknown/older browsers and third-party pages:

• Always check object and method existence before calling (if (window.X && typeof window.X.method === 'function')).
• Wrap manual widget API calls in try/catch to avoid breaking host page JavaScript.
• Call initialize(...) only after the widget script has loaded (for example in the script onload handler).
• Use destroy() before re-initializing with a different companyId/agencyId.