Skip to main content
  1. Assembled
  2. AI agents and Copilot
  3. Chat agent

Chat widget installation

Updated

Plans and permissions:

  • Add-on: AI agents, billed separately
  • Copy the installation script: Admin, Manager, or Team Lead role, or a custom role with Chat agent settings set to Can edit chat agent settings or Can view chat agent settings
  • Activate the chat widget, change its settings, create a JWT secret, or map user data: Admin, Manager, or Team Lead role, or a custom role with Chat agent settings set to Can edit chat agent settings
  • Replace the JWT secret or change verification settings: Admin, Manager, or Team Lead role, or a custom role with Chat agent settings set to Can edit chat agent settings

Use the chat agent’s script tag to add the chat widget to your website or help center. A standard installation is a few lines of HTML. Once the widget is installed and activated, you can also pass details about signed-in customers to the chat, so the chat agent can personalize its answers and keep each customer’s conversations together.

To find the script tag, go to AI support > Chat agent, open the chat agent, and select the Setup tab.

Note: The widget works in modern browsers with JavaScript turned on. Internet Explorer isn’t supported.

Add the chat widget to your website

  1. Go to AI support > Chat agent, and open the chat agent you want.
  2. Select the Setup tab.
  3. Under Installation, with Embed code selected, copy the script tag.
  4. Add the script tag to the HTML <head> of every page where the chat widget should appear. It looks like this:
<script
  src="https://cal.assembledhq.com/static/js/public-chat.js"
  data-company-id="YOUR_COMPANY_ID"
></script>

If you have more than one chat agent, the script tag also includes a data-profile-id for the chat agent you opened.

The Setup tab of a chat agent, with the Installation section showing Embed code and Debug code and the HTML script tag, and the User data authentication section with Manage JWT Secret

The widget stays hidden until you activate it. See Turn the widget on.

To preview the widget on any page before you install it, select Debug code instead, copy the code, and paste it into your browser’s developer console on that page.

For more options, such as opening the widget from your own button, see Chat widget advanced setup. For mobile apps, see Chat SDKs for iOS and Android.

Turn the widget on

The chat widget doesn’t appear on your site until you activate it.

  1. Go to AI support > Chat agent, and open the chat agent.
  2. Select Manage activation to open Activation settings.
  3. Under Chat availability, choose an option:
    • Activate for all visitors: everyone sees the widget.
    • Gradual rollout: the percentage of visitors you set sees the widget. The same visitors keep seeing it over time.
    • Deactivate for all visitors: no one sees the widget.
  4. Select Activate chat, Update activation, or Deactivate.

The Activation settings window opened from Manage activation, showing Current status: Active and the Chat availability options Activate for all visitors, Gradual rollout, and Deactivate for all visitors, with Cancel, Deactivate, and Activate chat buttons

If the widget still doesn’t appear, see The chat widget doesn’t appear or doesn’t show your changes.

Add the chat widget to a Zendesk help center

If your help center runs on Zendesk Guide, add the script tag to your help center theme.

  1. Go to your Zendesk Guide admin, at https://[your Zendesk subdomain].zendesk.com/knowledge.
  2. Select the Customize design icon in the navigation bar.
  3. Select the theme you want to edit, usually your live theme, and select Customize.
  4. Select Edit code, in the bottom right corner of the screen.
  5. Open the document_head.hbs file, and add your script tag.
  6. Select Publish.

The Zendesk theme editor, with an arrow pointing to the Edit code button in the bottom right corner

The Assembled script tag added to document_head.hbs in the Zendesk theme code editor

If you don’t see Edit code, your Zendesk plan may not include theme code editing. Zendesk includes it in Guide Professional and Guide Enterprise. See Editing the code for your live help center theme.

To identify signed-in help center users to the chat, see Chat user authentication in a Zendesk help center.

Identify signed-in users

If customers sign in to your site, you can pass their details to the chat. When you do, you can:

  • See each customer’s conversations in Assembled.
  • Personalize answers based on the customer’s details, for example answering VIP customers differently from customers on a free plan.
  • Keep a customer’s conversations together across visits.

There are two ways to pass user data: with a signed token (JWT), which Assembled verifies, or without one.

User data fields

Field Type Required Description
user_id string Yes The user’s unique identifier
email string No The user’s email address
name string No The user’s display name
metadata Record<string, unknown> No Any other user data, as key-value pairs

Create a signed token

The token’s claims use the user data fields above. The smallest valid set of claims is:

{
  "user_id": "CURRENT_USER_ID"
}
  1. Go to AI support > Chat agent, open the chat agent, and select the Setup tab.
  2. Under User data authentication, select Manage JWT Secret, then Create JWT secret, and copy the secret. It’s shown only once.
  3. On your server, create a token signed with this secret.
  4. Send the token to your web page.

Important: Keep the secret on your server. Never add it to code that runs in the browser.

For example, in Node.js:

const jwt = require('jsonwebtoken');
const secret = 'YOUR_JWT_SECRET'; // From the Setup tab in Assembled


const token = jwt.sign(
  {
    user_id: 'user_123',
    email: 'user@example.com',
    name: 'Jane Doe',
    metadata: {
      plan: 'premium',
      company: 'Example Inc'
    }
  },
  secret,
);

Authenticate the user

On your web page, pass the token to the widget:

await window.assembled.authenticateUser('YOUR_JWT_TOKEN');

To accept only user data that comes from a signed token, select Only accept user data that has been securely verified through a signed token under User data authentication. For a full example on a Zendesk help center, see Chat user authentication in a Zendesk help center.

Pass user data without a token

You can also pass user data without signing it, with setUserData. Assembled can’t verify this data, so visitors could change it.

await window.assembled.setUserData({
  user_id: "usr_1234",
  name: 'Jane Doe',
  metadata: {
    plan: 'enterprise'
  }
});

Map user data to smart fields

To use user data in the chat agent’s answers and workflows, map it to smart fields.

  1. Go to Configure > Smart fields, and create the smart fields you want to fill, if they don’t exist yet. See Smart fields.
  2. Go to AI support > Chat agent, open the chat agent, and select the Setup tab.
  3. Under User data mapping, enter the attribute’s JSON path and choose the Smart field to fill. Select Add variable to add more rows.
  4. Select Save changes.

The User data mapping section on a chat agent’s Setup tab, with JSON path and Smart field columns and an Add variable button

If users still appear anonymous, see Signed-in users aren’t identified correctly.

Troubleshooting

The chat widget doesn’t appear or doesn’t show your changes

After you install the chat agent, the chat widget may not appear on your website, help center, or app, or it may not show changes you’ve made, such as a new launcher position or color. Most of the time, this comes from the widget’s activation settings, the script tag, or caching, and you can fix it yourself.

Most of these checks use your browser’s developer tools: open the page where the widget should appear, then open the developer tools.

Cause How to tell What to do
The chat agent isn’t activated In AI support > Chat agent, the chat agent’s status next to its name is Inactive, or Gradual rollout and you aren’t in the percentage of visitors who see it. Select Manage activation and choose Activate for all visitors. See Turn the widget on.
The script tag is missing or has the wrong ID In the page source, or on the Elements tab, the public-chat.js script tag is missing, or its data-company-id or data-profile-id doesn’t match the script on the chat agent’s Setup tab. Copy the script tag again from the Setup tab, and add it to every page where the widget should appear.
The script didn’t load On the Network tab, public-chat.js doesn’t load when you reload the page, or the Console tab shows messages that start with [Assembled]. The widget can also send an error event. Fix the error shown in the console. Add data-debug="true" to the script tag to see more detail.
Your code called the widget before it loaded The console shows an error such as Cannot read properties of undefined (reading 'setPosition'). Wait for the load event, or check window.assembled.isReady(), before your code calls the widget.
The page hides the widget The script tag includes data-disable-auto-init or data-disable-launcher, your code calls hideLauncher(), or Disable launcher is on in the chat agent’s Themes tab. With data-disable-auto-init, call window.assembled.init(). With the launcher disabled, open the widget from your own button with window.assembled.open(). See Chat widget advanced setup.
The embedded container isn’t set up You use embedded mode, and the container isn’t in the page when the script loads, its selector doesn’t match exactly one element, or it has no height. See Embedded chat widget.
The chat isn’t set up in your mobile app When you open the chat in your iOS or Android app, it doesn’t load or show. Check the chat SDK’s setup. See Is the chat set up in your mobile app?
Your changes aren’t live yet You see the widget, but not your latest settings. Clear your browser cache, or open the page in a private window, and check again. Select Save changes in Assembled, and if you changed your site’s theme or template, such as in Shopify or Zendesk Guide, publish it. Then clear your browser cache and reload the page.
Another setting overrides yours The launcher or styling on the page doesn’t match the chat agent’s Themes tab. Script tag attributes and JavaScript calls such as setPosition() override the Themes tab on their page. Remove the override, or make them agree. See Chat launcher position.
Your site’s CSS conflicts with the widget The widget appears, but its layout or size looks wrong. Check your site’s CSS for rules that affect the widget or its container. Change the rules that affect the widget or its container.

Is the chat set up in your mobile app?

The chat SDK in your iOS or Android app might not be set up correctly. To fix it, check the setup:

  • Call initialize() before open().
  • Check that companyId is your company ID and isn’t blank. See Find your company ID.
  • On iOS, check that the device runs iOS 13.0 or later.
  • On Android, check that the layout that holds the chat has a width and height, and that the chat’s WebView was added to it.
  • Set debug to true, and check your app’s logs for errors.

For setup steps, see Chat SDKs for iOS and Android.

If the widget still doesn’t appear or show your changes, chat with our team and include the URL of the page where the widget should appear (or your app and its version), the name of the chat agent, any [Assembled] messages from the browser console or your app’s logs, a screenshot of what you see, and what you’ve already tried.

Signed-in users aren’t identified correctly

When you pass signed-in users’ details to the chat widget, conversations in Assembled should show who the user is. If users appear anonymous, if authentication stops partway through a conversation or for everyone at once, or if their details are ignored, something in the token setup needs fixing. For how authentication is set up, see Identify signed-in users, and for Zendesk help centers, Chat user authentication in a Zendesk help center.

The widget identifies a user from a JSON Web Token (JWT) that your server signs with the JWT secret from Assembled. Assembled checks the token with every message, and ignores tokens it can’t verify.

Most of these checks use your browser’s developer tools: sign in to your site, open the page with the chat, and open the developer tools. To see [Assembled] messages on the Console tab, first add data-debug="true" to the chat widget’s script tag, and remove it when you’re done.

Cause How to tell What to do
The token request is blocked by CORS On the Console tab, there’s a CORS error for your token endpoint. Set Access-Control-Allow-Origin to your help center’s exact address, not *, and Access-Control-Allow-Credentials: true. See Allow your help center to call the endpoint.
Your login cookie doesn’t reach your server On the Network tab, the request to your token endpoint returns 401 while you’re signed in, which means your server didn’t see a signed-in user. A 200 means a token was returned. Host your help center on your own domain, or set your login cookie with SameSite=None and Secure. Some browsers block cross-site cookies anyway.
The token is invalid The token request returns 200, but users still appear anonymous. Decode the token with a JWT tool, and check whether it uses HS256 and includes user_id. Sign the token with HS256 using your current secret, and include user_id.
The widget wasn’t loaded when the token was passed On the Console tab, there’s an error such as Cannot read properties of undefined (reading 'authenticateUser'). Check the other [Assembled] messages there too. Load the widget’s script tag before your authentication script, without async or defer.
The token expired Authentication stops partway through a conversation. Use a longer expiration, such as several hours, or call authenticateUser() with a new token before the old one expires.
The JWT secret was replaced Authentication stopped working for all users at once. When someone generates a new JWT secret in Assembled, the old one stops working, so tokens your server signs with it are rejected. Update your server to sign tokens with the new secret. To replace the secret yourself, see How do I replace the JWT secret?
Unsigned user data is ignored Details you pass with setUserData() don’t appear. On the chat agent’s Setup tab, under User data authentication, Only accept user data that has been securely verified through a signed token is selected. Pass the details in a signed token, or turn the setting off.
Your site doesn’t clear the chat session on sign-out After a sign-out on a shared browser, the next person sees the previous person’s conversations. Call teardown({ clearSession: true }) on sign-out. See Log users out or switch users.

How do I replace the JWT secret?

Important: A new secret stops the old one from working right away, so every token your server signs with the old secret is rejected. Make sure you can update and deploy your server quickly before you continue.

  1. Go to AI support > Chat agent, open the chat agent, and select the Setup tab.
  2. Under User data authentication, select Manage JWT Secret, then Continue.
  3. Select Replace JWT Secret.
  4. Select Copy to clipboard, and store the secret securely. You can’t see it again after you close the window.
  5. Update your server to sign tokens with the new secret.

If signed-in users still aren’t identified correctly, chat with our team and include the page where the chat is installed, a conversation where the user appeared anonymous and when it happened, the status code of the token request, any CORS or [Assembled] messages from the console, whether Only accept user data that has been securely verified through a signed token is on, and what you’ve already tried.

Related articles

Still have questions?