Web Experiences Snippet and JS API

The Web Experiences snippet accepts configuration options that let your page pass what it already knows about a visitor – identity, language, and Salesforce record identifiers – straight into the widget. This article covers the options available in window.ChiliChat.config and how each one behaves.

Most options apply to every flow type served by the snippet: Chat, Scheduling, Offer, and Announcement. The triggers option applies to Chat flows only.

Table of Contents

• The install snippet
• Configuration options
• Passing visitor data with lead
• Setting the language with locale
• Linking Salesforce records
• Adding fields to the calendar event
• Forcing a meeting type
• Triggering a Chat flow from a page element
• Callbacks and events
• Limitations

The install snippet

Copy your install snippet from Web Experience Flows > Embed. It looks like this:

<script>
  window.ChiliChat = {
    config: {
      workspaceId: 'your-workspace-id',
      tenantId: 'your-tenant-id',
      chatUrl: 'https://your-tenant.chilipiper.com/chat/widget/',
      eventsHandler: (event) => {},
    },
  }
</script>
<script type="module" crossorigin="anonymous" src="https://your-tenant.chilipiper.com/chat/embed/assets/index.js"></script>

Every option in this article is added inside the same config object. For the full deployment walkthrough, including the Google Tag Manager version of the snippet, see Customizing and Deploying Chat - Bot Settings.

Configuration options

Passing visitor data with lead

The lead option accepts key-value pairs describing the visitor. Use it when the page already knows who someone is – from a login, a form submission, or values your marketing automation stored earlier.

<script>
  window.ChiliChat = {
    config: {
      workspaceId: 'your-workspace-id',
      tenantId: 'your-tenant-id',
      chatUrl: 'https://your-tenant.chilipiper.com/chat/widget/',
      lead: {
        email: 'jane@acme.com',
        firstname: 'Jane',
        lastname: 'Doe',
        company: 'Acme Corp',
      },
    },
  }
</script>

Naming the keys

Each key must match a data field in your Chili Piper account. There are two ways to name a key:

• Use the data field's Smart Parameter, set in Command Center > Data Fields under Additional Settings. In the example above, email, firstname, lastname, and company are Smart Parameters;
• Use the data field's reference name for a default field that has no Smart Parameter configured, for example PersonEmail, PersonFirstName, PersonLastName.

Smart Parameters are the recommended approach, because the name stays readable in your page code and you control it. A data field can carry more than one, so the same field can accept several key names.

See Setting up Smart Parameters for Chat for how to configure one.

Note: Match the Smart Parameter exactly as you configured it, including capitalization.

⚠️ Warning: Every key must match a configured Smart Parameter or a data field reference. If a single key does not match, none of the values in lead are used — the widget behaves as though no lead object was passed. Check each key before deploying, and add a Smart Parameter for any field that does not have one.

What happens to the values

Values passed in lead are available to the flow from the moment it loads:

• Trigger conditions evaluate against them, so a flow can be selected on a value your page supplies. Conditions must target the Person object – a first-time anonymous visitor has no Lead or Contact record for a Lead: or Contact: condition to read;
• Routing rules evaluate against them in the same way;
• Salesforce matching and record creation use them, so the Lead or Contact is found or created with those values;
• Send Data Field steps do not ask again. A field that already has a value from lead is not shown in the form, so a visitor you already know is not asked for their email a second time.

Setting the language with locale

By default the widget follows the visitor's browser language. Pass locale to set it from your page instead – useful when your site already knows the visitor's language preference.

locale: 'fr-FR'

Pass a full locale code – language and region, as in fr-FR or pt-BR. Underscores are accepted, so fr_FR works as well as fr-FR.

A language code on its own, such as fr, also sets the language, but Chili Piper picks the regional variant for you and it is not always the one you would expect – es gives Latin American Spanish and zh gives Hong Kong Chinese. Pass the full code when the regional variant matters.

The supported codes are:

ar-AR, cs-CZ, da-DK, de-DE, el-GR, en-GB, en-US, es-ES, es-LA, fr-CA, fr-FR, he-IL, hu-HU, id-ID, it-IT, ja-JP, ko-KR, nb-NO, nl-NL, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sv-SE, th-TH, tr-TR, vi-VN, zh-CN, zh-HK, zh-TW.

The language must also be enabled for your flow. See How do I set up Multi-Language Chat? for how to translate a flow.

Linking Salesforce records

Four options connect the visitor and the meeting they book to specific Salesforce records. Use them when your page already knows which record applies – an in-app session, a customer portal, or a page reached from a campaign link.

accountId: '001am00001yKh8zAAC',
opportunityId: '006am00000ABcdEFGH',
campaignId: '701am000009XyZaAAA',
status: 'Responded',

When more than one of these is present, the Event is related to the first match in this order: Case, then Opportunity, then Campaign. This overrides the Create Event related-to setting configured for the workspace. An accountId is never used to relate the Event – it identifies the Account for routing and record creation.

Note: These options take Salesforce record IDs, not names. Your page needs the ID available to pass it.

Adding fields to the calendar event

The event option writes extra field values onto the calendar Event record created when a meeting is booked. Use it to carry page or session context into the Event for reporting.

event: {
  Description: 'Booked from the in-app upgrade banner',
}

Each key must be a field that exists on the Event object in your CRM.

Forcing a meeting type

Pass meetingTypeId to book a specific meeting type instead of the one the flow would select.

meetingTypeId: 'your-meeting-type-id'

If the ID does not match a meeting type in your account, the widget shows an error rather than a calendar.

Triggering a Chat flow from a page element

Custom Triggers in your bot settings opens a specific Chat flow when a visitor clicks an element on your page. The triggers option does the same thing from your snippet, which is useful when the element IDs live in your codebase rather than in an admin's hands.

triggers: [
  { elementId: 'book-a-demo-button', journeyId: 'your-journey-id' },
]

The element ID is accepted with or without a leading #.

Note: This option opens Chat flows. Scheduling, Offer, and Announcement flows are shown according to their own trigger conditions and cannot be opened from a page element.

Callbacks and events

eventsHandler receives every event the widget emits. The three named callbacks are a shortcut to the events most pages act on:

onSuccess: (event) => {
  console.log('Meeting booked', event)
},
onError: (type, event) => {
  console.log('Widget error', type, event)
},

For the full list of events and the browser messaging alternative, see Capturing Javascript Messaging in Browser.

Limitations

• A key in lead that does not match a configured Smart Parameter or a data field reference causes every value in lead to be discarded, not just that one. There is no error message;
• Values passed in lead do not resolve in dynamic tags inside chat messages. To greet a visitor by a value your page supplies, collect that value in the flow with a Send Data Field step;
• Chat Logs list the fields a visitor filled in. A field supplied by lead is not listed, including where it caused a Send Data Field step to be skipped. Confirm those values on the CRM record;
• accountId, opportunityId, caseId, campaignId, and status apply to Salesforce only. There is no HubSpot equivalent in the snippet;
• All options are read once, when the snippet initializes. Changing window.ChiliChat.config after the page has loaded has no effect.