Skip to main content
Use this guide when you want to embed the BoundBot WebChat experience inside a browser extension—for example in a sidebar, popup, or dedicated extension page.

​
What the extension supports

  • a Chrome side panel that opens from the extension action button
  • one saved WebChat public key at a time
  • chat inside a hosted BoundBot iframe
  • optional current-page context that sends the active tab URL, title, and visible page text with each new message
This page covers the shipped Chrome extension in apps/chrome-extension. It does not document a custom Firefox add-on, popup build, or generic extension embed recipe.

​
Before you start

  • Chrome or another Chromium browser with side panel support
  • a WebChat channel
  • a linked bot
  • the public key for that channel
  • the extension installed from the Chrome Web Store or loaded unpacked from apps/chrome-extension
The Channels → WebChat screen is where you configure the channel that will serve your extension. You’ll create or select a channel, then manage its public key and allowed origins so only your extension’s origin can load the widget.

​
Step 1: Create or choose a WebChat channel

  1. Open Channels -> WebChat.
  2. Click Connect WebChat if you need a new channel.
  3. Select the bot that should answer in the extension.
  4. Save the channel and copy its public key.
The current Chrome extension connects with the WebChat public key. You do not need to add a chrome-extension://... origin for this flow.

​
Step 2: Install the extension

  1. Install the extension from the Chrome Web Store, or open chrome://extensions if you are testing from source.
  2. If you are loading from source, enable Developer mode and click Load unpacked.
  3. Select the apps/chrome-extension folder.
  4. Click the extension action button to open the side panel.

​
Step 3: Connect the public key

  1. Open the side panel.
  2. Paste the WebChat public key into the input.
  3. Click Connect.
  4. The extension validates the key and loads chat in the panel.
  5. To switch channels later, open Settings in the panel and click Disconnect, then connect with a different key.

​
Step 4: Use current page context

Turn on Use current page when you want BoundBot to answer using the page you are viewing.
  • When enabled, the extension sends the active tab URL, page title, and visible page text with each new message.
  • The extension reads page context only when you send a message and the toggle is on.
  • If Chrome blocks page-content access, the extension falls back to whatever tab metadata is available.

​
Step 5: Customize what carries into the extension

  1. Open Settings -> Customize Widget.
  2. Choose the WebChat channel you use for the extension.
  3. Set the theme, title, height, position, colors, border radius, and starter suggestions so the widget fits your sidebar or popup layout.
  4. Save the configuration.
Extension sidebars and popups often have limited width and height. Use the Customize Widget screen to pick a theme, dimensions, and position that fit your layout so the chat feels native to the extension.

​
Step 3: Choose an embed method

​
Iframe embed

Use an iframe when the widget runs inside an extension page that can host a frame (e.g. a sidebar panel, popup, or options page). Your manifest must allow the embed host in content_security_policy and any required frame or script sources. 
<iframe
  allow="microphone"
  style="height: 780px; width: 420px; border: none; display: flex; visibility: visible;"
  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 your extension serves an HTML page (e.g. a popup or options page) and you want the widget runtime to manage the chat UI. Ensure your manifest grants the necessary permissions and that your Content Security Policy allows loading the script from the BoundBot embed domain. 
<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

  • Open the extension side panel and confirm the chat loads.
  • Send a test message and confirm the bot replies.
  • Open Inbox and verify the conversation was recorded.
  • Turn on Use current page and ask a page-specific question to confirm active-tab context is included.
After sending a test message from your extension, open the BoundBot Inbox to confirm the thread was created and that agent replies are delivered in real time. This confirms the end-to-end path from extension widget to your bot and back.
The current extension forces a light, full-panel chat view. Website-style launcher settings such as theme, height, position, and border radius do not carry over one-to-one inside the side panel.

​
Troubleshooting

Invalid public key
  • Copy the current public key again from Channels -> WebChat.
  • If you rotated the key, disconnect the extension and reconnect with the new key.
Side panel opens but chat stays blank
  • Confirm you can reach https://www.boundbot.com and https://api.boundbot.com from the browser.
  • If you loaded the extension unpacked, reload it after local code changes.
No streaming reply
  • Ensure https://api.boundbot.com is reachable from the extension context.
  • If you use a reverse proxy, confirm it does not buffer server-sent events.
Use current page does not include page text
  • Chrome blocks content extraction on some protected pages such as chrome:// pages, extension pages, and other restricted surfaces.
  • In those cases the extension may send only the tab URL and title, or no page context at all.

WebChat

Create the channel, manage the public key, and connect the bot that answers in the extension.

Team settings

Open widget customization from team settings and manage the rest of your workspace configuration.

Playground

Test the same live WebChat pipeline before you reconnect the extension to a different channel.

Inbox

Review the conversations the extension creates and follow up from the shared inbox.