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.

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:

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.
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.
Branding — hide the "Powered by Bookbag" footer on eligible plans.

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.

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.

Troubleshooting

What's next

JavaScript embed

Programmatic control, identity verification, and events.

Shopify integration

Ground answers in your catalog and enable order lookups.

Connect more channels

Add email and messaging so the same agent answers everywhere.

Widgets

Render interactive cards and forms inside the chat.

Deploy overview