If you’re looking for more customizability and configuration of the chat widget, especially programmatically, Assembled provides extensive customized control.

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 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

const isReady = window.assembled.isReady();

Event Handling

The chat widget dispatches custom events that you can listen for, including `assembledload`, `assembledopen`, and `assembledclose`:

window.addEventListener('assembledload', () => { 
  console.log('Chat widget loaded and ready');
});

window.addEventListener('assembledopen', () => {
  console.log('Chat widget was opened by the user');
});

window.addEventListener('assembledclose', () => { 
  console.log('Chat widget was closed by the user');
});

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

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