Programmatic installation

For more control over initialization and configuration, you can create and manage the chat widget programmatically. Make sure to include programatic configuration in the script tag so that the chat widget does not open automatically:

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

Next, initialize the chat widget in javascript when you’d like to see the widget appear by invoking the async init function like so:

// Initialize the chat widget separately
await window.assembled.init();

Configuration options

The chat widget can be configured with the following options:

Widget control

Showing or hiding the launcher button

The launcher button is the entry point that users can click to start a conversation.

// Open the launcher button
window.assembled.showLauncher();

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

Opening and closing the chat widget

The widget contains the complete chat interface where users can type messages and view responses.

// Open the chat widget (will also show the launcher)
window.assembled.open();

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

Adjusting position of the chat widget

The widget supports programmatic positioning of the launcher through the setPosition method, which allows you to anchor the chat widget to a corner with customer margins.

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
});

Note: The provided position is validated against the viewport and will default to the original position of the launcher if the provided position is outside of the viewport. The function will return true if the position was successfully applied and false if the position is invalid or out of bounds.

Dragging control

Enable or disable the ability for users to drag the launcher around the screen:

// Enable dragging
window.assembled.setDraggable(true);

// Disable dragging
window.assembled.setDraggable(false);

Note: When dragging is enabled, users can click and drag the launcher to reposition it. The position is automatically saved and restored on subsequent page loads.

Debug mode

Control debug logging to help with development and troubleshooting:

// Enable debug logging
window.assembled.setDebug(true);

// Disable debug logging
window.assembled.setDebug(false);

Debug messages are prefixed with [Assembled] and logged to the browser console.

Checking loading status

Determine if the chat widget has finished loading and is ready for interaction:

const isReady = window.assembled.isReady();

Integration with Single Page Applications (SPAs)

Use the teardown function to prevent memory leaks and degraded performance in your SPA.

// Cleanup and remove the entire chat widget
window.assembled.teardown();

Activation management

The chat widget supports two modes of activation control:

1. Server-Controlled Activation: By default, Assembled manages the activation state of the chat widget based on your settings in the Assembled dashboard.
2. Client-Side Override: You can override the server activation state by setting the activated option during initialization:

const chat = window.assembled.createAssembledChat({
  companyId: 'YOUR_COMPANY_ID',
  activated: true // Force activation regardless of server settings
});

Style customization

While we recommend using the default styles configured in your Assembled dashboard, you can override them for specific pages:

const chat = createAssembledChat({
  companyId: 'YOUR_COMPANY_ID',
  buttonColor: '#FF0000',                      // Custom button color (hex)
  launcherSize: 'large',                       // Custom launcher size
  iconSrc: 'https://your-domain.com/icon.png', // Custom launcher icon
  openChatText: 'Need help?',                  // Custom open text
  closeChatText: 'Close support',              // Custom close text
  enableGradient: true,                        // Enable gradient effect
  launcherZIndex: 99999                        // Control stacking order
});

Embedded Display Mode

Embedded mode allows you to place the chat widget directly inside a container element on your page, giving you full control over where the chat appears within your layout.

Manual Script Tag Configuration

You can configure embedded mode directly in the script tag:

<!-- Add a container element in your HTML -->
<div id="chat-container"></div>

<!-- Add the script with embedded mode attributes -->
<script
  src="https://cal.assembledhq.com/static/js/public-chat.js"
  data-company-id="YOUR_COMPANY_ID"
  data-profile-id="YOUR_PROFILE_ID"
  data-display-mode="embedded"
  data-embedded-container="#chat-container"
></script>

Configuration via Chat Settings

You can also configure embedded mode through the Chat Settings UI:

• Navigate to Chat Settings → Theme tab
• Under Display mode, select "Embedded"
• In the Container selector field, enter a CSS selector (e.g., #chat-container or .chat-wrapper)
• Save your settings

Important Notes:

• The container element must exist in the DOM before the script loads
• The container selector must be unique on the page
• The embedded widget will fill its container; ensure the container has appropriate dimensions

Event handling

The chat widget dispatches custom events that you can listen for to track user interactions and widget behavior. All events are dispatched through a unified assembledevent event with detailed payload information.

Listening to events

To listen for chat widget events, add an event listener for assembledevent:

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

You can also track specific events by checking the event type:

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

switch (event_type) {
    case 'load':
      console.log('Chat widget loaded');
      window.assembled.isReady() // true if widget is ready
      break;
    case 'error':
      console.error('Chat widget failed to load:', payload);
      break;
    case 'open':
      console.log('Chat widget opened');
      break;
    case 'message_sent':
      console.log('User sent a message:', payload.message);
      break;
    case 'handoff_triggered':
      console.log('Conversation triggered the handoff form, type:', payload.escalation_type);
      break;
    case 'handoff_submitted':
      console.log('Handoff submitted, type:', payload.escalation_type);
      break;
  }
});

Available event types

Below is a list of the available event types, along with their payloads and corresponding Typescript types:

Escalation Type

The escalation_type field, available on handoff_triggered and handoff_submitted indicates the destination of the handoff.

• live_chat
• case
• form_link
• none

Note: The escalation_type reflects the actual escalation path taken at runtime, which may differ from the configured default if business hours fallback is enabled.

Mobile responsiveness

The chat widget automatically adjusts its layout for mobile devices (screens <= 480px width). On mobile:

• The widget expands to full screen
• The launcher position adjusts automatically
• Touch interactions are optimized for mobile use

Error handling

The chat widget includes built-in error handling and logging. Common errors will be logged to the console with the prefix [Assembled]. We recommend monitoring these logs during implementation and testing.

Best practices

1. Initialization: Always initialize the chat widget after the DOM is loaded
2. Authentication: Implement user authentication early in your page lifecycle
3. Cleanup: Call teardown() when removing the widget from the page
4. Mobile: Test thoroughly on mobile devices
5. Error Handling: Monitor console logs during implementation