# 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.

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.

```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`. |

```html
<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.

```html
<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.

```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](/docs/integrations/shopify) and [Shopify actions](/docs/skills/shopify).

## Install on other platforms

#### WordPress

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.

#### Webflow

Go to Project Settings → Custom Code and paste the snippet into the **Footer Code** field, then publish.

#### Squarespace

Go to Settings → Advanced → Code Injection and paste the snippet into the **Footer** field.

#### Plain HTML

Paste the snippet before `</body>` in your page template. If your site uses a shared layout or include, add it once there so it loads on every page.

## 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.

### Popup messages (floating proactive bubbles)

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).

## Troubleshooting

**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 `</body>` 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](/docs/developers/javascript-embed).

## What's next

- [JavaScript embed](/docs/developers/javascript-embed) — Programmatic control, identity verification, and events.
- [Shopify integration](/docs/integrations/shopify) — Ground answers in your catalog and enable order lookups.
- [Connect more channels](/docs/deploy/overview) — Add email and messaging so the same agent answers everywhere.
- [Widgets](/docs/widgets/overview) — Render interactive cards and forms inside the chat.