Widget SDK

The chat widget exposes a small browser API for mounting and removing the embedded widget. Use it to attach the widget to a bot and, when your site already knows the visitor, pass a signed visitor identity at mount time.

For a baseline embed (no SDK calls), see Embed the Widget. This page is the API reference for the bundled FluentBotChatWidget global.

Loading the script

HTML

<script
  type="module"
  src="https://cdn.jsdelivr.net/gh/fluent-docai/chat-widget@latest/chat-widget.js"
></script>
<script type="module">
  FluentBotChatWidget.injectWidget("YOUR_BOT_ID");
</script>

The first script loads the widget bundle and attaches FluentBotChatWidget to window. The second script mounts the widget for your bot.

injectWidget(botId, options?)

Mounts the widget. Call it once per page.

JavaScript

FluentBotChatWidget.injectWidget("019dd3d4-4b7e-71eb-9561-5cf790a5da57", {
  visitor: {
    email: "alice@example.com",
    name: "Alice",
    data: {
      plan: "enterprise",
      org: "acme",
    },
    signature: "<HMAC-SHA256 signature>",
  },
});

Options

Option	Type	Notes
visitor.name	string	Visitor display name.
visitor.email	string	Visitor email; persisted to the chat.
visitor.data	object	Optional key-value data attached to the verified identity. Visible in the Live Chat.
visitor.signature	string	HMAC signature for Identity Verification. Required if your team has identity verification enabled.

botId is required. options is optional. If you don’t pass visitor, the chat starts as an anonymous visitor session.

injectWidget(...) does not return a widget instance. The only supported option today is visitor.

Visitor signature payload

When Identity Verification is enabled, sign the exact JSON payload that the widget sends:

JavaScript

const visitor = {
  name: "Alice",
  email: "alice@example.com",
  data: {
    plan: "enterprise",
    org: "acme",
  },
};

const payloadToSign = JSON.stringify({
  name: visitor.name,
  email: visitor.email,
  data: visitor.data ?? null,
});

Compute HMAC-SHA256(payloadToSign, team_secret) on your server and pass the hex digest as visitor.signature. See Identity Verification for language-specific examples.

destroyWidget()

Removes the active widget instance from the page and disconnects its live chat subscriptions.

JavaScript

FluentBotChatWidget.destroyWidget();

Single Page Apps (SPA)

If your site is a SPA and you navigate without full page reloads, mount the widget once at app startup, not on every route change. The widget persists across navigations.

If the visitor identity is not known immediately, wait until your app has resolved the logged-in visitor before calling injectWidget(...). The current SDK reads visitor identity only when the widget mounts.

Identity Verification

Authenticated sites should pass a signed visitor object so the bot can trust the email is real (preventing visitor impersonation). See Identity Verification for the signing recipe.

Shadow DOM

The widget renders inside a Shadow DOM, which means:

• Your site’s CSS won’t leak in (good — the widget always looks consistent).
• Your CSS can’t customize the widget (use the Appearance settings instead).
• You can’t query widget internals from the host page DOM.

Multiple bots on one page

Not supported. Choose one bot before mounting and call injectWidget(...) once for that page. To switch bots, call FluentBotChatWidget.destroyWidget() first, then mount the next bot.

Removing the widget

Call FluentBotChatWidget.destroyWidget() to remove it cleanly. It cancels active subscriptions, closes WebSocket connections, and removes the DOM node. Call this on logout or when navigating to a page that shouldn’t show the widget.

Troubleshooting

• FluentBotChatWidget is not defined — first script tag didn’t load before the second. Make sure both <script type="module"> tags are present and the loader script comes first.
• Visitor identity isn’t sticking — pass visitor in injectWidget options before the widget mounts.
• Multiple widgets stacking — you called injectWidget more than once. Either mount once per page or call FluentBotChatWidget.destroyWidget() before mounting again.

What’s next

• Embed the Widget — baseline embed without SDK calls.
• Identity Verification — sign visitor identity.
• Widget Settings — visual customization in the dashboard.