Embed WebChat

Use this guide to install WebChat on a website you control. Use the script embed when you need signed visitor identity; either embed method works for an anonymous public widget.

Before you embed

Make sure you have an active WebChat channel, a linked bot, the correct allowed origins, and access to your website’s HTML or tag manager.

Create and customize the channel

Create WebChat

Open Channels → WebChat, select Connect WebChat, choose a bot, and save the display name and optional allowed origins.

Customize the UI

Open Settings → Customize Widget. Set the appearance, size, position, branding, chat behavior, and page visibility.

Copy the generated code

Choose the correct WebChat channel, save the UI configuration, and copy its current embed snippet. The generated code already contains the correct public key and hosts.

Choose an embed method

Iframe embed

Use a direct iframe when you want complete control over placement. Iframe mode is available on Starter and above.

<iframe
  src="https://YOUR_WEB_DOMAIN/embed/chat?publicKey=YOUR_PUBLIC_KEY&apiBase=https%3A%2F%2FYOUR_API_DOMAIN&open=true&v=1"
  title="BoundBot AI Agent"
  width="420"
  height="780"
  style="border: 0"
  allow="microphone; autoplay"
></iframe>

Script embed

Use the generated script for the managed floating widget and for authenticated visitors.

<script
  src="https://YOUR_WEB_DOMAIN/embed/widget.js?publicKey=YOUR_PUBLIC_KEY&apiBase=https%3A%2F%2FYOUR_API_DOMAIN&v=1"
  async
></script>

Prefer the exact snippet generated in the dashboard. The placeholders above explain the structure but are not ready to paste unchanged.

Authenticated visitors

Authenticated visitor mode binds a WebChat conversation to a customer identity your server has verified. Use it when the bot should answer private order or account questions.

Enable authenticated visitors

Edit the WebChat channel, select Authenticated visitors, enter an issuer such as https://shop.example.com, and select Generate secret. Copy the secret immediately and store it only in your website server’s environment variables.

Issue a short-lived token

After validating your normal website session, have your server sign an HS256 JWT. Never create this token in browser JavaScript and never pass your website session cookie or ordinary access token to the widget.

Connect login to the widget

Define window.BoundBot before loading the widget script. Return the token from getIdentityToken for an already signed-in visitor and from onAuthenticationRequired after an interactive login.

Required identity claims

Claim	Required	Value
`iss`	Yes	Exact issuer configured on the channel.
`aud`	Yes	Audience shown in the dashboard, such as `boundbot:PUBLIC_KEY`.
`sub`	Yes	Stable customer ID from your application, up to 200 characters.
`iat`	Yes	Token issue time.
`exp`	Yes	Expiry time. Token lifetime cannot exceed 10 minutes; five minutes is recommended.
`email`	No	Verified email, used only as a fallback for older orders without an external customer ID.
`name`	No	Verified customer display name.

Example Next.js route:

import crypto from 'node:crypto';
import jwt from 'jsonwebtoken';

export async function GET() {
  const customer = await requireLoggedInCustomer();

  const token = jwt.sign(
    { sub: customer.id, email: customer.email, name: customer.name },
    process.env.BOUNDBOT_IDENTITY_SECRET!,
    {
      algorithm: 'HS256',
      issuer: 'https://shop.example.com',
      audience: 'boundbot:YOUR_PUBLIC_KEY',
      expiresIn: '5m',
      jwtid: crypto.randomUUID(),
    }
  );

  return Response.json({ token });
}

Return 401 when the website visitor is not logged in.

<script>
  window.BoundBot = {
    getIdentityToken: async function () {
      const response = await fetch('/api/boundbot/identity', {
        credentials: 'include',
      });
      if (!response.ok) return null;
      return (await response.json()).token;
    },

    onAuthenticationRequired: async function () {
      await openYourLoginDialog();
      const response = await fetch('/api/boundbot/identity', {
        credentials: 'include',
      });
      if (!response.ok) return null;
      return (await response.json()).token;
    },
  };
</script>
<script src="YOUR_BOUNDBOT_WIDGET_SCRIPT_URL" async></script>

If login finishes elsewhere on the page, call window.BoundBot.identify(token). On logout, call window.BoundBot.logout() so the open widget no longer has access to the signed-in conversation.

Private order lookup

When creating or importing an order, set externalCustomerId to the same stable value used in the JWT sub claim. BoundBot first matches that field and can fall back to the verified email claim for older records. The private order tool does not accept a customer ID from the model. BoundBot injects the verified conversation identity and applies team and ownership filters before returning a minimal order summary. An anonymous visitor receives an authentication request instead of private order data.

Validate the install

Confirm the widget appears and streams a reply.
Send an image and confirm the bot receives it.
Start a voice call and confirm microphone permission works.
Verify the conversation and voice transcript appear in Inbox.
If origins are restricted, test both an allowed domain and an unlisted domain.
For authenticated mode, retrieve an order owned by the signed sub, then confirm another customer cannot retrieve it by providing its order number.
Log out, ask for an order, and confirm the website login callback runs.

First message before setup finishes: WebChat sends the visitor’s first typed message as soon as the conversation is ready.
Muted conversation: the widget records the visitor’s message but skips the AI reply until your team turns auto reply back on.
Identity upgrade: a visitor can start anonymously, sign in when prompted, and continue after the widget upgrades the conversation securely.

Troubleshooting

Iframe does not load

Copy a fresh snippet and verify the publicKey belongs to an active WebChat channel.
Add the exact parent-page origin, including protocol, when the channel uses an allowlist.

Microphone is unavailable

Preserve the generated iframe permissions, including allow="microphone; autoplay".
Use HTTPS and grant browser and operating-system microphone permission.

Identity token is rejected

Confirm HS256, iss, aud, sub, iat, and exp.
Keep the lifetime at 10 minutes or less.
Confirm the server uses the current secret after a rotation.
Never place the identity token in an iframe or script URL.

Login succeeds but the question is not retried

Return the token from onAuthenticationRequired, or call window.BoundBot.identify(token) after login.

WebChat

Create the channel and manage origins, identity, UI, and voice settings.

WebChat voice

Test voice calls, transcript persistence, and microphone permissions.

Inbox

Verify embedded conversations and take over manually when needed.

Plans and limits

Check iframe mode, origin controls, key rotation, and other plan gates.

Embedding and integrations

Before you embed

Create and customize the channel

Choose an embed method

Iframe embed

Script embed

Authenticated visitors

Required identity claims

Private order lookup

Validate the install

Current widget behavior

Troubleshooting

WebChat

WebChat voice

Inbox

Plans and limits

​Before you embed

​Create and customize the channel

​Choose an embed method

​Iframe embed

​Script embed

​Authenticated visitors

​Required identity claims

​Connect the login callback

​Private order lookup

​Validate the install

​Current widget behavior

​Troubleshooting

​Related pages

WebChat

WebChat voice

Inbox

Plans and limits

Before you embed

Create and customize the channel

Choose an embed method

Iframe embed

Script embed

Authenticated visitors

Required identity claims

Connect the login callback

Private order lookup

Validate the install

Current widget behavior

Troubleshooting

Related pages