The bubble never appears.

Open the console. If you see "[Bookbag] data-agent-id required", the data-agent-id attribute is missing or empty. Confirm the agent id is correct and the agent is not archived.

It works locally but not in production.

Check that your Content Security Policy allows loading the script from app.bookbag.ai and framing app.bookbag.ai (the chat runs in an iframe).

Can I open or close the widget from my own code?

See Event listeners for the client-side patterns around the embedded widget.

JavaScript embed

Add the Bookbag chat widget to any website with a single script tag. Configure color and position with data attributes, and learn how the loader and iframe work.

View as Markdown

The fastest way to put a Bookbag agent in front of customers is the embed script. It injects a chat bubble in the corner of your page; clicking it opens the agent in a sandboxed iframe. No build step, no API key.

Looking for the no-code path?

The dashboard generates this exact snippet for you under Deploy. See Website widget for the click-through setup.

Install

Paste the script anywhere before the closing </body> tag, replacing YOUR_AGENT_ID with your agent's id:

index.html

<script
  src="https://app.bookbag.ai/widget/embed"
  data-agent-id="YOUR_AGENT_ID"
  defer
></script>

check

Reload the page — a chat bubble appears in the corner and answers from your agent's knowledge.

Configuration attributes

The loader reads optional data- attributes off its own <script> tag:

Attribute	Required	Default	Description
data-agent-id	Yes	—	The numeric id of the agent to load. Without it the loader logs an error and does nothing.
data-color	No	#3b82f6	The accent color of the launcher bubble (any CSS color).
data-position	No	right	`right` or `left` — which corner the bubble sits in.

index.html

<script
  src="https://app.bookbag.ai/widget/embed"
  data-agent-id="123"
  data-color="#0f766e"
  data-position="left"
  defer
></script>

Brand colors and welcome text

Most of the agent's appearance — avatar, welcome message, suggested prompts, and whether the "Powered by Bookbag" badge shows — is set in the dashboard and served from the agent's public config, not from the embed tag.

How it works

1
The loader runs
The script at /widget/embed is a tiny loader. It finds its own tag, reads the data attributes, and creates a launcher button and a hidden iframe.
2
The iframe holds the chat UI
The iframe points at /widget/frame?agentId=.... Running the chat in an iframe isolates its styles and scripts from your page.
3
Clicking toggles the panel
The launcher button shows and hides the iframe. The chat UI inside talks to the public chat runtime to stream answers.

Because the chat lives in an iframe, it will not inherit or pollute your site's CSS. The launcher uses a very high z-index so it stays clickable above page content.

Frameworks

In single-page apps, add the script once at the app shell level (e.g. in the document head/body template) rather than inside a component that mounts and unmounts. In Next.js, use the next/script component with the afterInteractive strategy and pass the data attributes through.

Troubleshooting

Website widget setup

The dashboard walkthrough and appearance settings.

Event listeners

React to the widget in the browser.

Identity verification

Personalize chat for logged-in users.

Developer overview

REST API integration