Skip to main content

​
Feature Overview

  • Launch your existing agent as an embeddable web widget with zero additional hosting.
  • Switch agencies on the fly by updating the widget in the dashboard — no code redeploy needed.
  • Personalize every deployment with optional additionalInstructions that shape the assistant’s behavior per site.
Widget preview

​
Prerequisites

  • Deployed Agency in the Agencii dashboard.

​
Quick Start

1

Create a new widget

  1. In the Agencii dashboard, open Deploy → Widgets and create a new widget.
  2. Configure the widget’s name, description, position and conversation starters.
  3. Customize the widget’s appearance by choosing a theme mode, logo, and color scheme.
  4. Select the agency and any selectable agents.
  5. Configure advanced settings such as Allowed Domains and auto-open behavior as needed.
  6. Save changes.
  7. Test your widget!
2

Embed the widget

  1. In the Agencii dashboard, open Deploy → Widgets and find the widget you created.
  2. Click the three-dot menu on the right side of the widget row and select Embed. Embed widget
  3. Copy the embedding script.
  4. Paste the script into your website’s HTML file (or adjust the script to your needs).
  5. Load the page and confirm the widget works as expected.
3

Share the widget

  1. In the Agencii dashboard, open Deploy → Widgets and find the widget you created.
  2. Click the Share button on the right side of the widget row.
  3. This opens a new window with the widget embedded on a blank page. Live widget embedded on a landing page
You can embed several widgets on the same page by using the embedding script multiple times with different widgetIds and chatContainer selectors.
If you are prototyping locally, temporarily add http://localhost:3000 (or your dev origin) to the widget’s allowed domains list if you are using the Allowed Domains feature.

​
Widget Controls

You can control the widget from your site/app by dispatching a CustomEvent named “widget-control” on window with a detail payload. The widget listens for this event and performs the requested action. Event name: widget-control Payload shape: 
interface WidgetControlEventDetail {
  /** Command name */
  type: 'open-widget' | 'send-message-to-widget';
  /** Command-specific payload */
  data: boolean | string;
  /** Target widget instance */
  widgetId: string; // e.g., 'WIDGET_123'
}
Dispatch pattern: 
window.dispatchEvent(
  new CustomEvent<WidgetControlEventDetail>('widget-control', {
    detail: { type, data, widgetId },
  })
);
✅ The widget must be initialized on the page. Replace WIDGET_ID with the identifier provided in your widget embed script.

​
Commands

​
Open or close the widget

Opens or closes the widget UI. Type: open-widget Data: boolean — true to open, false to close. Example — open: 
window.dispatchEvent(
  new CustomEvent('widget-control', {
    detail: {
      type: 'open-widget',
      data: true, // open
      widgetId: WIDGET_ID,
    },
  })
);
Example — close: 
window.dispatchEvent(
  new CustomEvent('widget-control', {
    detail: {
      type: 'open-widget',
      data: false, // close
      widgetId: WIDGET_ID,
    },
  })
);

​
Typical use cases

  • Bind to a “Chat” / “Support” button to open the widget.
  • Close the widget after a route change or when a modal shows.

​
Send a message to the widget

Programmatically sends a text message into the widget (e.g., seed a greeting or pass context). This event does not open the widget automatically, so dispatch an open-widget event first. Type: send-message-to-widget Data: string — the message body. Example: 
window.dispatchEvent(
  new CustomEvent('widget-control', {
    detail: {
      type: 'send-message-to-widget',
      data: 'Hi',
      widgetId: WIDGET_ID,
    },
  })
);

​
Multiple Widgets on One Page

If you embed multiple widget instances, dispatch events with the specific widgetId you want to control. The widget code should internally ignore events addressed to other IDs. 
const SALES_WIDGET = 'WIDGET_SALES';
const SUPPORT_WIDGET = 'WIDGET_SUPPORT';

// Open Support, keep Sales unchanged
window.dispatchEvent(new CustomEvent('widget-control', {
  detail: { type: 'open-widget', data: true, widgetId: SUPPORT_WIDGET },
}));