Web Widget API

Quick Start #

Add this snippet to any HTML page to embed the widget. Replace YOUR_WIDGET_ID with the ID from your dashboard.

<!-- 1. Paste before </body> -->
<iframe
  src="https://boostedchat.com/widget?id=YOUR_WIDGET_ID&mode=contained"
  style="width:100%;height:600px;border:none;border-radius:24px;"
  allow="clipboard-write"
></iframe>

<!-- 2. (Optional) Customise after the iframe -->
<script>
  const frame = document.querySelector('iframe[src*="boostedchat"]');
  frame.addEventListener('load', () => {
    const BC = frame.contentWindow.BoostedChat;
    BC.style('--wg-primary', '#e11d48');
    BC.setTheme('dark');
    BC.on('message:send', (d) => console.log('User sent:', d));
  });
</script>

Embed Code #

The widget is served as an iframe. You control size, mode, and border-radius directly via URL params and inline styles.

URL Parameters

Sizes

Integrated Mode (Auto-Resize)

When using mode=integrated, add this script after the iframe so it grows with content:

<script>
window.addEventListener('message', function(e) {
  if (e.data && e.data.type === 'boostedchat-widget-resize') {
    var iframe = document.querySelector('iframe[src*="boostedchat.com/widget"]');
    if (iframe) iframe.style.height = e.data.height + 'px';
  }
});
</script>

CSS Custom Properties #

Every visual aspect of the widget is driven by CSS custom properties on :root. Override them from outside the iframe via the JS API, or from inside via a <style> tag. All variables begin with --wg-.

JavaScript API #

Access the API via iframe.contentWindow.BoostedChat. All methods are available after the iframe's load event.

Core Methods

Event Methods

Style API #

Control every visual aspect of the widget at runtime. Set CSS variables, inject custom CSS, toggle themes, and manage body classes.

// Single
BC.style('--wg-primary', '#e11d48');

// Batch
BC.style({
  '--wg-primary': '#e11d48',
  '--wg-radius': '8px',
  '--wg-font-size': '14px'
});

const id = BC.addCSS(`.wg-msg-content { font-style: italic; }`);
// later: BC.removeCSS(id);

Events #

Listen with BC.on(event, callback). All callbacks receive a data object.

Action Events

UI Events

Style Events

Event Data Examples

BC.on('message:send', (data) => {
  console.log(data.message);       // "I want to book for 2 adults"
  console.log(data.actionParams);   // { travelers: "2 Adults" }
});

BC.on('style:change', (data) => {
  console.log(data.property, data.value);  // "--wg-primary" "#e11d48"
});

BC.on('chip:click', (data) => {
  console.log(data.action);  // { label: "Pick Date", type: "date", ... }
});

Action Chips #

Action chips appear inside the chat input area. When a user clicks one, a popover opens with your configured UI (date picker, counter, dropdown, etc.). The selected value is sent as a hidden parameter alongside the next message.

Built-in Action Types

Custom Action Example

// Register a custom color picker action
BC.registerAction('colorPicker', {
  render: function(container, action) {
    container.innerHTML = '<input type="color" id="my-color">';
  },
  onConfirm: function(setParam, close, action) {
    const color = document.getElementById('my-color').value;
    setParam('selectedColor', color);
    close();
  }
});

Themes & Dark Mode #

The widget ships with light and dark themes. Dark mode activates when body.theme-dark is present. Toggle it with the API:

BC.setTheme('dark');   // switch to dark
BC.setTheme('light');  // switch to light
BC.getTheme();         // → 'dark' or 'light'

Dark Mode Overrides

When dark mode is active, these variables are automatically adjusted:

CSS Selectors #

When you need more control than CSS variables provide, target these selectors via addCSS(). They are inside the widget iframe.

Keyframe Animations

Recipes #

Copy-paste examples for common customisations.

Match Your Brand

const BC = iframe.contentWindow.BoostedChat;

BC.style({
  '--wg-primary'        : '#e11d48',
  '--wg-accent'         : '#e11d48',
  '--wg-user-bubble-bg' : '#e11d48',
  '--wg-send-btn-bg'    : '#e11d48',
  '--wg-glow-color'     : '#e11d48',
  '--wg-font'           : "'Inter', sans-serif",
  '--wg-radius'         : '12px',
  '--wg-msg-radius'     : '12px',
});

Auto Dark Mode

iframe.addEventListener('load', () => {
  const BC = iframe.contentWindow.BoostedChat;
  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)');

  BC.setTheme(prefersDark.matches ? 'dark' : 'light');

  prefersDark.addEventListener('change', (e) => {
    BC.setTheme(e.matches ? 'dark' : 'light');
  });
});

Minimal Flat Style

BC.style({
  '--wg-radius'         : '0px',
  '--wg-msg-radius'     : '4px',
  '--wg-glow-opacity'   : '0',
  '--wg-input-shadow'   : 'none',
  '--wg-input-border'   : '#d1d5db',
  '--wg-popover-shadow' : 'none',
});

Slow, Cinematic Animations

BC.style({
  '--wg-anim-message-duration' : '1.2s',
  '--wg-anim-message-distance' : '24px',
  '--wg-anim-message-easing'   : 'cubic-bezier(0.22, 1, 0.36, 1)',
  '--wg-transition-fast'       : '0.3s ease',
  '--wg-transition-normal'     : '0.5s ease',
  '--wg-glow-speed'            : '12s',
});

Log All Events (Debug)

const events = [
  'message:send', 'message:added', 'chip:click',
  'popover:open', 'popover:close',
  'typing:show', 'typing:hide',
  'input:focus', 'input:blur', 'input:change',
  'style:change', 'theme:change'
];

events.forEach(ev =>
  BC.on(ev, (d) => console.log(`[BC] ${ev}`, d))
);