# 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 → **Deploy** → the **Chat widget** card → **Manage** → **Embed**. The snippet there already has 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.

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

## 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/actions/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 **Manage** view on the Chat widget card controls how the widget looks and what it says, without editing code:

- **Color** — accent color for the bubble and header (overrides `data-color`).
- **Welcome message** — the greeting shown when the widget opens.
- **Suggested prompts** — example questions customers can tap to start.
- **Position** — dock to the left or right corner.
- **Branding** — hide the "Powered by Bookbag" footer on eligible plans.

> **INFO:** Dashboard settings are read from the agent's public configuration at load time, so changes apply on the next page reload — 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

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