Skip to main content
Use this guide when you want to install the BoundBot WebChat experience on a website you control.

​
Before you embed

Make sure you already have:
  • a WebChat channel
  • a linked bot
  • the correct allowed origins
  • the website where you want to install the widget

​
Step 1: Create a WebChat channel

  1. Open Channels -> WebChat.
  2. Click Connect WebChat.
  3. Select a bot.
  4. Add a display name and optional allowed origins.
  5. Save the channel.

​
Step 2: Customize the widget

  1. Open Settings -> Customize Widget or Chat Experience -> Customize.
  2. Choose the WebChat channel.
  3. Set the theme, title, height, position, colors, border radius, and starter suggestions.
  4. Save the configuration. The current customization flow can also generate a production iframe snippet for you.

​
Step 3: Choose an embed method

​
Iframe embed

Use an iframe when you want a direct, predictable installation. This option is intended for tiers that include iframe embed support. 
<iframe
  allow="microphone"
  style="height: 780px; width: 420px; border: none; display: flex; visibility: visible; position: fixed; right: 0; bottom: 0;"
  title="BoundBot AI Agent"
  src="https://YOUR_WEB_DOMAIN/embed/chat?publicKey=YOUR_PUBLIC_KEY&apiBase=https%3A%2F%2FYOUR_API_DOMAIN&theme=dark&title=BoundBot%20AI%20Agent&position=right&v=1"
></iframe>

​
Script embed

Use the script when you want a simpler install path managed by the widget runtime. This is the safest default if you want the standard widget install flow. 
<script
  src="https://YOUR_WEB_DOMAIN/embed/widget.js?publicKey=YOUR_PUBLIC_KEY&apiBase=https%3A%2F%2FYOUR_API_DOMAIN&v=1"
  async
></script>

​
Validate the install

  • Load the site and confirm the widget appears.
  • Send a test message and confirm the bot replies.
  • Open Inbox and verify the conversation was recorded.
  • Confirm the origin is allowed if you restricted the channel.

​
Current widget behavior

  • First message before the conversation is ready: users can type from the starter screen before the widget finishes creating the conversation. BoundBot sends that first message automatically once the session is ready, so the opening question is not lost.
  • Muted conversations: if the conversation is muted for human handoff, WebChat skips the AI reply until auto reply is turned back on. This is the same mute state used by the Stop Auto Reply action.
The current customization page focuses on live preview, saved UI settings, and production iframe code generation. The actual install still depends on your WebChat public key and the embed patterns shown here.

​
Troubleshooting

Iframe does not load
  • Check the /embed/chat host.
  • Check the publicKey.
  • Check NEXT_PUBLIC_WEB_BASE_URL and NEXT_PUBLIC_API_BASE_URL.
Origin not allowed
  • Add the exact origin to the channel configuration, including protocol.
No streaming reply
  • Make sure the API streaming route is reachable.
  • If you use a reverse proxy, confirm it does not buffer server-sent events.
WebChat is the easiest place to test a new bot before you roll it out to social or team messaging channels.

WebChat

Create the channel, set allowed origins, and manage the public key before you embed.

Playground

Test the same live WebChat pipeline before you install it on a production site.

Quickstart

Follow the fastest route from signup to a working website chat bot.

WordPress plugin

Use the plugin when you would rather not paste embed code manually.