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

Chat widget advanced setup

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

Use the script tag options and the window.assembled JavaScript API to control the chat widget from your own code: when it loads, where it sits, how it looks on a particular page, and what happens when users log out. You can also listen for widget events, for example to track handoffs in your analytics.

This article is for developers. For the standard installation, see Chat widget installation.

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

How the script tag and settings work together

  • Settings you make on the chat agent’s settings pages apply everywhere the widget is installed.
  • Script tag attributes override those settings on the pages where you add them.
  • JavaScript API calls change the widget while the page is open, and override both.
  • Messages in the browser console from the widget start with [Assembled].

How the widget behaves on mobile

On screens 480 pixels wide or narrower, the widget opens full screen and adjusts the launcher’s position automatically. Test your installation on mobile devices. For native apps, see Chat SDKs for iOS and Android.

Initialize the widget yourself

By default, the widget initializes as soon as the script loads. To decide when it appears, add data-disable-auto-init="true" to the script tag:

<script
  src="https://cal.assembledhq.com/static/js/public-chat.js"
  data-company-id="YOUR_COMPANY_ID"
  data-disable-auto-init="true"
></script>

Then call the async init function when you want the widget to appear:

await window.assembled.init();

Initialize the widget after the page’s DOM has loaded.

Override activation

By default, the activation settings on the chat agent control whether the widget appears. See Turn the widget on. To decide on a page yourself, add data-activated to the script tag:

<script
  src="https://cal.assembledhq.com/static/js/public-chat.js"
  data-company-id="YOUR_COMPANY_ID"
  data-activated="true"
></script>

Important: On pages with data-activated, the activation settings in Assembled no longer have any effect.

Override styles on a page

We recommend setting styles on the chat agent’s Themes tab. To use different styles on a particular page, add attributes to that page’s script tag:

<script
  src="https://cal.assembledhq.com/static/js/public-chat.js"
  data-company-id="YOUR_COMPANY_ID"
  data-button-color="#FF0000"
  data-launcher-size="large"
  data-icon-src="https://your-domain.com/icon.png"
  data-open-chat-text="Need help?"
  data-close-chat-text="Close support"
  data-enable-gradient="true"
></script>

For every supported attribute, see Script tag options.

Embed the widget in your page

To place the chat inside an element on your page instead of a floating window, use the embedded display mode. See Embedded chat widget.

Control the widget with JavaScript

Show or hide the launcher

The launcher is the button users select to open the chat.

// Show the launcher
window.assembled.showLauncher();


// Hide the launcher
window.assembled.hideLauncher();

Open or close the widget

// Open the widget (this also shows the launcher)
window.assembled.open();


// Close the widget
window.assembled.close();

Move the launcher

Use setPosition to anchor the launcher to a corner, with offsets in pixels from the edges:

window.assembled.setPosition({
  anchor: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
  offsetX: 25, // px from horizontal edge
  offsetY: 25 // px from vertical edge
});

setPosition returns true if it moved the launcher. It returns false, and the launcher stays where it was, if the widget hasn’t finished initializing or the position would be outside the viewport. For other ways to set the position, see Chat launcher position.

Let users drag the launcher

// Let users drag the launcher
window.assembled.setDraggable(true);


// Stop users from dragging the launcher
window.assembled.setDraggable(false);

Turn debug logging on or off

window.assembled.setDebug(true);
window.assembled.setDebug(false);

Check whether the widget is ready

const isReady = window.assembled.isReady();

Remove the widget from a single-page app

When you remove the widget from a page in a single-page app, call teardown to avoid memory leaks and slowdowns:

window.assembled.teardown();

If your app logs users out without reloading the page, see Log users out or switch users.

Listen for widget events

The widget sends an assembledevent event on window for each thing that happens, with the details in event.detail.

Add an event listener

window.addEventListener('assembledevent', (event) => {
  const { event_type, payload } = event.detail;
  console.log('Event type:', event_type);
  console.log('Event payload:', payload);
});

To act on specific events, check the event type:

window.addEventListener('assembledevent', (event) => {
  const { event_type, payload } = event.detail;


  switch (event_type) {
    case 'load':
      console.log('Chat widget loaded');
      break;
    case 'error':
      console.error('Chat widget failed to load');
      break;
    case 'open':
      console.log('Chat widget opened');
      break;
    case 'message_sent':
      console.log('User sent a message:', payload.content);
      break;
    case 'handoff_triggered':
      console.log('Handoff started, type:', payload.escalation_type);
      break;
    case 'handoff_submitted':
      console.log('Handoff form submitted, type:', payload.escalation_type);
      break;
  }
});

Event types

Event type When it’s sent Payload
load The widget has loaded and is ready. None
error The widget failed to load. None
open The widget was opened. None
close The widget was closed. None
message_sent The user sent a message. { conversation_id?: string; content: string; created_at: number; role: string }
message_received A message arrived from the AI agent or a support team member. { conversation_id?: string; content: string; created_at: number; role: string }
handoff_triggered The conversation started a handoff, and the handoff form appeared. { conversation_id?: string; escalation_type?: string }
handoff_submitted The user submitted the handoff form. { conversation_id?: string; escalation_type?: string; escalation_request?: { email: string; name?: string; description?: string; additional_fields?: Record<string, string>; selected_case_tagging_option_id?: string | null; chosen_escalation_type?: 'live_chat' | 'case' } }
handoff_completed The user was connected to a support team member. Sent for Live agent handoffs only. { conversation_id?: string; escalation_type?: 'live_chat'; platform_id?: string; platform?: string }, where platform_id is the messaging conversation’s ID
case_created A case was created in your help desk, for Live agent and Email ticket handoffs. { conversation_id?: string; escalation_type?: string; platform_id?: string; platform?: string }, where platform_id is the ticket or case ID
csat_submitted The user submitted the closing survey. { rating: number; rating_option_id?: string; question_responses?: Array<{ question_id: string; text_response?: string; selected_option_id?: string }>; additional_feedback?: string }

Escalation types

escalation_type says where the handoff goes:

  • live_chat: the user is being connected to a support team member.
  • case: an email ticket or case is being created.
  • form_link: the user is being sent to an external support form.
  • awaiting_user_choice: the user is choosing between a Live agent handoff and an email ticket.
  • none: no handoff method is set up.

Note: escalation_type is the path the conversation actually took. It can differ from the chat agent’s handoff method, for example when a Live agent handoff happens outside business hours and falls back to another method.

Log users out or switch users

If people sign in to your site, end their chat session when they log out or switch accounts. Otherwise, the next person on the same browser can see the previous person’s conversations.

  1. When a user logs out or switches accounts, tear down the widget and clear its session:

    await window.assembled.teardown({ clearSession: true });

    Wait for this call to finish before you show the widget again. It finishes when the session has ended, or after 2 seconds at most.

  2. If logging out loads a new page, you’re done: the widget on the next page starts a fresh session.

  3. If the page stays open, initialize the same widget again for the next person, and authenticate them if they’re signed in:

    await window.assembled.init();


// If the next person is signed in:
await window.assembled.authenticateUser(nextUserJwt);

Keep using window.assembled, and don’t add a second script tag. To create the token for authenticateUser(), or to pass user data with setUserData(), see Identify signed-in users.

Mistakes to avoid

  • Calling authenticateUser() or setUserData() for the next person without tearing down first. This doesn’t start a new session, so the next person can still see the previous person’s conversations.
  • Calling teardown() without { clearSession: true } on logout. This removes the widget but keeps the session.

window.assembled.clearSession() ends the session without removing the widget. On logout, use teardown({ clearSession: true }) instead, because an open widget keeps showing the conversation it already loaded.

Allow the session request in your Content Security Policy

Clearing the session sends a request from your page to https://cal.assembledhq.com. If your site sets a Content Security Policy with a connect-src directive, add that origin:

Content-Security-Policy: connect-src 'self' https://cal.assembledhq.com;

If the request is blocked, the widget is still removed, but the session stays active, and the next person on that browser can see the previous person’s conversations.

Script tag options

Option Type Description
data-company-id string Required. Your Assembled company ID.
data-profile-id string The chat agent to load, if you have more than one.
data-disable-auto-init boolean Stops the widget from initializing when the script loads. Call window.assembled.init() to show it.
data-disable-close-button boolean Hides the close button (X) in the chat header.
data-activated boolean Overrides the activation settings in Assembled for this page. See Override activation.
data-display-mode string widget, modal, or embedded. See Embedded chat widget.
data-embedded-container string In embedded mode, the CSS selector of the element to place the chat in, such as #chat-container.
data-button-color string The launcher button’s color.
data-disable-launcher boolean Hides the launcher. Use it when your own button or link opens the widget.
data-disable-header boolean Hides the chat header. Use it with the embedded display mode.
data-launcher-size string The launcher’s size: small, medium, or large.
data-launcher-position string The launcher’s corner: bottom-right, bottom-left, top-right, or top-left.
data-launcher-offset-x number The launcher’s horizontal distance from the edge, in pixels. The default is 10.
data-launcher-offset-y number The launcher’s vertical distance from the edge, in pixels. The default is 10.
data-icon-src string The URL of a custom launcher icon.
data-open-chat-text string The text on the launcher when the widget is closed.
data-close-chat-text string The text on the launcher when the widget is open.
data-launcher-text-visibility string When the launcher text shows: hover or always.
data-enable-gradient boolean Shows the launcher button’s color as a gradient.
data-enable-dragging boolean Lets users drag the launcher to another position.
data-attachment-icon-variant string The file attachment icon in the message box: paperclip (default), plus, or image.
data-input-border-radius string The corner radius of the message box, such as 6px.
data-message-border-radius string The corner radius of message bubbles, such as 6px.
data-theme string The widget’s color theme: light, dark, or system.
data-language string A language code, such as es or fr, for the widget’s interface text.
data-debug boolean Logs debugging messages to the browser console. Remove it before going live.

Options without a stated default use the value from the chat agent’s settings in Assembled.

Best practices

  • Authenticate users early in the page’s lifecycle.
  • Watch the browser console for [Assembled] messages while you implement and test, and turn on data-debug to see more of them.

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

Related articles

Still have questions?