The bubble doesn't appear

Open your browser console. A missing data-agent-id logs an error from the loader. Also confirm the snippet is before and that the current domain is on your allowed-domains list (if you set one).

It works locally but not in production

Add your production domain (and www variant) to the allowed-domains list. The widget refuses to initialize on domains that aren't allow-listed once a list exists.

Styling changes don't show up

Dashboard style settings apply on the next reload. Hard-refresh the page. Note that data-color on the script tag is an initial hint; the dashboard color takes effect once the agent config loads.

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

Yes — see the JavaScript embed and event-listener guides for programmatic control. Start at JavaScript embed.

Website widget

Add the Bookbag chat widget to any website with a single script tag. Includes the embed snippet, Shopify and platform install guidance, styling, and domain controls.

View as Markdown

The website widget is a floating chat bubble that opens an agent-powered conversation in the corner of your site. It's the fastest way to deploy — a single <script> tag, no build step, and it works on any website or platform that lets you add HTML.

Where to find it

Open your agent → Settings → Connect. The Connect area has three sections: Embed (the snippets below), Share (a direct hosted-chat link), and Integrations (per-agent connectors). The snippets there already have your agent ID filled in.

Install the embed snippet

Copy this snippet and paste it just before the closing </body> tag of your site. Replace YOUR_AGENT_ID with the ID shown on the Embed tab.

index.html

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

check

Reload your site — a chat bubble appears in the corner and answers from your agent's knowledge. The defer attribute keeps it from blocking your page load.

Your agent ID is an opaque key

The data-agent-id value the dashboard gives you is an unguessable key like bk_… (not a guessable number), so your widget can't be discovered by counting IDs. Always copy the exact snippet from the Embed tab. (Older numeric IDs still work, so existing installs keep running.)

Optional attributes

The loader reads a few optional data- attributes so you can tweak appearance without touching the dashboard:

Attribute	Default	What it does
`data-agent-id`	— (required)	Which agent answers in the widget.
`data-color`	`#3b82f6`	Hex color of the chat bubble and header.
`data-position`	`right`	Corner to dock to: `right` or `left`.

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

Embed inline instead of a bubble

Want the chat to live in the page — on a Contact or Support page — rather than as a floating bubble? Use the iframe snippet from the Embed section. It drops the full chat into wherever you place it.

<iframe
  src="https://app.bookbag.ai/widget/frame?agentId=YOUR_AGENT_ID"
  title="Support chat"
  width="100%"
  style="height: 100%; min-height: 700px"
  frameborder="0"
></iframe>

Or just share a link

The Share section gives you a direct hosted-chat URL (the same /widget/frame page) you can send to anyone — no website or embedding required. It reflects the agent's current theme and welcome message.

Install on Shopify

Shopify themes let you edit the layout that wraps every storefront page, so the widget appears site-wide once you add the snippet there.

1
Open the theme code editor
In your Shopify admin, go to Online Store → Themes → ⋯ → Edit code on your active theme.
2
Open theme.liquid
Under Layout, open theme.liquid — this template wraps every page of your store.
3
Paste before </body>
Scroll to the bottom and paste the Bookbag snippet immediately before the closing </body> tag.
4
Save
Save the file and visit your storefront. The chat bubble appears on every page.

layout/theme.liquid

  <!-- ... your theme markup ... -->
  <script
    src="https://app.bookbag.ai/widget/embed"
    data-agent-id="YOUR_AGENT_ID"
    defer
  ></script>
</body>
</html>

Want order lookups too?

Connect Shopify as a data source and enable Shopify actions so the agent can answer order-status and tracking questions. See Shopify integration and Shopify actions.

Install on other platforms

Add the snippet to your theme's footer.php before </body>, or use a plugin that injects scripts site-wide (for example, a "header & footer scripts" plugin) and paste the snippet into the footer field.

Style and content

The Chat Interface settings control how the widget looks and what it says, without editing code — with a live preview that updates as you type:

Display name — the name shown in the chat header (falls back to the agent's name if left blank).
Color — accent color for the bubble and header (overrides data-color).
Theme — light or dark.
Profile picture — an avatar shown in the chat header.
Welcome message — the greeting shown when the widget opens.
Popup messages — proactive chat bubbles that float above the launcher to pull visitors in (see below).
Suggested prompts — example questions, rendered as tappable chips that send on click.
Message placeholder — the input's placeholder text.
Position — dock the bubble to the left or right corner.
Auto-open — open the chat automatically after N seconds (once per session; 0 = never).
Show after — delay the launcher bubble's appearance by N seconds (0 = as soon as it loads).
In-chat features — toggle thumbs-up/down feedback, the copy button, regenerate, voice dictation (mic), file attachments (image / PDF), voice mode (a real-time spoken conversation), keeping suggestions after the first reply, and remembering the conversation on reload. Each has a "?" with a plain-English explanation.
Dismissable notice — a short bar shown above the input (e.g. a privacy-policy or terms line). It stays until the visitor closes it with the ✕ or sends their first message, and the dismissal is remembered for the session.
Branding / custom footer — the "Powered by Bookbag" badge below the input. On a paid plan you can remove it or replace it with your own footer text. Both the notice and footer support links — paste a full https://… URL or write [label](https://url) (e.g. a privacy-policy link).

Privacy-policy notice & footer

To show something like "By chatting you agree to our privacy policy" with a clickable link, put it in the Dismissable notice (top, auto-dismisses after the first message) or the Custom footer (always visible, paid plans). Use [privacy policy](https://example.com/privacy) for the link — only full http(s):// URLs are linked.

Branding removal is a paid feature

On the free plan the "Powered by Bookbag" footer cannot be removed — the setting is ignored even if toggled, so the badge always appears in the live widget. Upgrade to a paid plan to remove it or set your own footer text.

File attachments (image / PDF)

With file attachments on, a paperclip appears in the chat input so visitors can attach images or PDFs to a message — handy for "here's a screenshot of the error" or "here's my receipt." Images are read by vision-capable models; each attachment costs 1 extra message credit, up to 5 per message. Attachments are disabled automatically on HIPAA workspaces.

Voice mode vs. dictation

Voice dictation adds a mic that turns speech into text in the input (the visitor still reads replies). Voice mode is a full spoken conversation — the visitor talks and the agent talks back in real time (OpenAI Realtime; needs an OpenAI key and uses the realtime model + voice from the agent's Voice tab).

Noise cancellation

If the voice agent gets interrupted by background noise, tune it under Settings → Noise cancellation: browser noise suppression + echo cancellation (on by default, free), an input-sensitivity slider (how loud before it listens), a pause-before-responding slider, an allow-interruptions toggle, and an optional Aggressive noise reduction mode (off by default) that mutes the mic between the caller's words.

info

The live preview updates instantly as you edit; your changes go live on the widget once you click Save. Settings are read from the agent's public configuration at load time, so there's no need to re-copy the snippet.

Pull visitors into a conversation before they click. A couple of seconds after the page loads, a small stack of chat-style message bubbles floats up above the launcher — e.g. "👋 Need a hand?" then "I can check an order or start a return." Clicking a bubble opens the chat; clicking the ✕ dismisses them.

Set one message per line in Popup messages (up to four). Leave it blank to show nothing.
By default the popup shows once per visitor session — once someone opens or dismisses it, it stays hidden until they come back.
Toggle Show on every page load to display it on every page instead (useful for marketing pages and funnels).
Toggle Show on exit intent to surface it when the visitor moves to leave the tab, instead of on a timer.

Where to set the popup

Open your agent → Settings → Chat interface → Launcher bubble (the same controls also appear on the Deploy tab). Set the Popup messages and the “Show on every page load” / “Show on exit intent” toggles there, with a live preview.

Restrict to your domains

To keep your widget from being embedded on sites you don't control, set an allowed domains list in the widget settings. The widget only initializes when it's loaded from a domain on the list.

Add every domain you use

Include staging and www variants. If the list is set and the current domain isn't on it, the widget won't load.

Performance & placement

The widget is built to be a good citizen on your store — it won't slow your page or get in the way of buying.

Lazy, non-blocking load — the chat app is only fetched when a visitor opens the widget, and otherwise warmed during browser idle. It never competes with your page's initial render, so it doesn't hurt PageSpeed or Core Web Vitals.
Double-install safe — if the loader ends up on the page twice (for example a theme snippet plus an app block), only one widget mounts. You won't get two chats splitting a visitor's messages.
Launcher offsets — nudge the bubble so it clears a sticky add-to-cart bar. Set a bottom and side gap for desktop, and a separate mobile bottom gap that lifts the launcher only on phones.

Where to set placement

Open your agent → Settings → Chat interface → Launcher bubble. Set Bottom gap, Side gap, and Mobile bottom gap (leave the mobile value blank to match desktop).