# Website widget

> Add your agent to your website as a chat bubble or a centered chat bar, and choose which websites can show it.

The website widget puts your agent on your own website, so visitors get answers without leaving the page. You set it up once: choose a style, list the websites it may appear on, publish, and paste a small piece of code into your site.

**Where to find it:** open your agent and go to **Playground**. Under **Preview channel**, choose **Chat Bubble** or **Center Stage**, then select **Publish → Website widget**.

![A visitor asking Acme Support to change the delivery address of an order in the website chat](https://hourzero.dev/marketing/app/widget-support-light.webp "A visitor changes the delivery address for an order without leaving Acme's website.")

## How it works

Website channels don't need an outside account, so there's nothing to connect. Instead, you tell Hourzero which websites are allowed to show your widget.

1. **Style**: Pick Chat Bubble or Center Stage and style it in the Playground.
2. **Allow**: List the websites that may show the widget.
3. **Publish**: Make your saved draft live for visitors.
4. **Add the code**: Paste one short script into your website.

You only paste the code once. After that, every change you publish shows up on your website automatically.

## Choose a style

| Style | What visitors see | Can you publish it? |
| --- | --- | --- |
| **Chat Bubble** | A small round button in the corner. Selecting it opens a chat window. | Yes |
| **Center Stage** | A chat bar at the bottom center of the page that expands into a focused conversation. | Yes |
| **Help Page** | A full chat page with conversation history. | Not yet (coming soon) |

**Chat Bubble** is the best choice for most websites. It's always there but never in the way. **Center Stage** suits pages where the chat is the main event, like a help center or a landing page.

You can publish both. Each style has its own look, its own allowed websites, and its own code.

To make the chat part of a page instead, like a help center or a support tab in your app, use [Chat Iframe](https://hourzero.dev/docs/integrations/chat-iframe). It's a separate channel with its own look, allowed websites, and code.

> [!NOTE] Help Page is coming soon
> You can't open, preview, or publish Help Page yet. To put your agent on your site today, use Chat Bubble or Center Stage, or [Chat Iframe](https://hourzero.dev/docs/integrations/chat-iframe) for a full-size chat inside a page.

## Style the widget

1. Open **Playground** and choose **Chat Bubble** or **Center Stage** under **Preview channel**.
2. On the **Display** tab, choose the **Widget language** for the widget's buttons and tooltips, then set the **Display name**, **Welcome message**, colors, and **Suggested prompts**. For Chat Bubble, you can also choose a **Launcher position** (**Bottom right** or **Bottom left**) and a **Launcher icon** (a preset or your own image). You can also turn on a **Landing page**, a start screen with a greeting, link cards, and optional Messages, Help, and News tabs. Paste your blog or docs address and the News and Help tabs fill themselves from it.
3. On the **Overview** tab, choose whether visitors may send files (**File uploads**) and speak their questions (**Voice transcription**).
4. Select **Save draft**.
5. Select **Preview** to open the widget with your current settings in a new tab.

The [Playground guide](https://hourzero.dev/docs/ai-agent-management/playground) explains every style option.

## Allow your website

Allowed domains are the websites that may show your widget. This stops other people from copying your code onto their own sites. You can also limit the widget to certain pages, or hide it on pages like your checkout. If the list is empty, the widget won't appear anywhere.

1. In the Playground, select **Publish → Website widget**. The **Deploy to your website** dialog opens.
2. Under **Allowed domains**, type one website address per line, without `https://`. To limit the widget to certain pages, add the page path after the address. See [Show the widget on certain pages](#show-the-widget-on-certain-pages).
3. Wait for **Saved to draft** to appear under the box.

![The Deploy to your website dialog with acme.com and shop.acme.com allowed, and the embed code below](https://hourzero.dev/marketing/app/playground-publish-light.webp "List your websites under Allowed domains, then copy the code and publish.")

Each line must match the address visitors see in their browser. Here are some examples for Acme:

| You type | The widget appears on |
| --- | --- |
| `acme.com` | `acme.com` only |
| `www.acme.com` | `www.acme.com` only |
| `*.acme.com` | Every subdomain, like `www.acme.com` and `shop.acme.com`, but not `acme.com` itself |
| `https://shop.acme.com:443` | `shop.acme.com` on that exact port (rarely needed) |

So if your site works both with and without `www`, add both lines:

```text
acme.com
*.acme.com
```

You can add up to 50 lines.

### Show the widget on certain pages

An address on its own, like `acme.com`, shows the widget on every page of that website. To show it only on some pages, add the page path after the address:

| You type | The widget appears on |
| --- | --- |
| `acme.com/pricing` | The pricing page only, not pages under it like `acme.com/pricing/teams` |
| `acme.com/help*` | `acme.com/help` and every page that starts with it, like `acme.com/help/returns` |
| `acme.com/help/*` | Pages under `acme.com/help/`, but not `acme.com/help` itself |
| `acme.com/orders/*/track` | The tracking page of every order, like `acme.com/orders/48213/track` |
| `acme.com/orders/*/` | Every order page, like `acme.com/orders/48213`, but not pages under it like `acme.com/orders/48213/track` |
| `acme.com/` | The home page only |

Some things to know:

- Add one line per page or section. For example, `acme.com/pricing` and `acme.com/help*` on two lines show the widget on both.
- If the same website also appears without a path, the widget shows on every page of it.
- Capital letters, a trailing `/`, and anything after `?` or `#` in the visitor's address don't matter. `acme.com/pricing` also covers `acme.com/Pricing/?plan=team`.
- A `*` as the very last character of a line matches everything after it. Anywhere else, it matches one part of the address between two slashes, like an order number or an ID. So `acme.com/orders/*/track` doesn't cover `acme.com/orders/48213/items/track`.
- To match only one changing part at the end of an address, finish the line with a `/` after the `*`: `acme.com/orders/*/` covers `acme.com/orders/48213` but not `acme.com/orders/48213/track`. Without that `/`, `acme.com/orders/*` covers both.
- On websites that change pages without reloading, the widget loads when a visitor reaches a listed page and unloads when they leave it.

Paste the code on every page, as usual. On pages you didn't list, the widget doesn't load at all: there's no chat and no [website actions](#website-actions). The safety lock is still the website address, so only list websites you control.

### Hide the widget on certain pages

Sometimes it's easier to say where the widget should *not* appear, for example on your checkout or sign-in page. Under **Excluded pages**, in the same dialog, type one page per line:

| You type | The widget is hidden on |
| --- | --- |
| `/checkout` | The checkout page of every allowed website, but not pages under it like `/checkout/thanks` |
| `/account*` | `/account` and every page that starts with it, like `/account/billing`, on every allowed website |
| `/orders/*/invoice` | The invoice page of every order, like `/orders/48213/invoice`, on every allowed website |
| `/orders/*/` | Every order page, like `/orders/48213`, but not pages under it like `/orders/48213/invoice` |
| `shop.acme.com/cart` | The cart page of `shop.acme.com` only |
| `admin.acme.com` | Every page of `admin.acme.com`, even if `*.acme.com` is allowed |

Some things to know:

- Excluded pages always win. If `acme.com/help*` is allowed and `/help/internal*` is excluded, the widget shows on `acme.com/help/returns` but not on `acme.com/help/internal/notes`.
- Start a page with `/`. A line like `checkout` is not accepted, because it looks like a website address.
- Paths follow the same rules as allowed pages, including how `*` works. Capital letters, a trailing `/`, and anything after `?` or `#` in the visitor's address don't matter.
- On websites that change pages without reloading, the widget unloads when a visitor reaches an excluded page and comes back when they leave it.
- The widget doesn't load at all on an excluded page, so there's no chat and no [website actions](#website-actions) there.

You can add up to 50 excluded pages.

> [!IMPORTANT]
> Changes to allowed domains and excluded pages are saved to your draft. They only reach your live widget when you publish this channel again.

> [!TIP]
> Testing on your own computer first? Your developer can add the local address they use, for example `http://localhost:3000`, and remove it before launch.

## Publish the widget

1. Make sure your Playground changes are saved with **Save draft**. You can't publish while there are unsaved changes.
2. Check that **Agent replies** is on (**Replies on after publishing**) on the **Overview** tab.
3. Select **Publish → Website widget**.
4. Select **Publish saved draft**. The next time you publish, the button says **Publish latest draft**. A message confirms the channel is published.

Publishing only updates the style you have open. If you use both Chat Bubble and Center Stage, publish each one.

## Add the code to your website

1. In the **Deploy to your website** dialog, under **Install the widget**, select **Copy code**. You'll see **Embed code copied**.
2. Paste the code on your website just before the closing `</body>` tag. Most website builders have a site-wide setting for this, often called custom code, footer code, or code injection. Use the site-wide option, so the widget appears on every page.
3. Save or publish the change on your website.

Your code looks like this. Always copy your own from the dialog, because it contains your agent's ID and the style you chose.

```html
<script
  src="https://hourzero.dev/embed.js"
  data-agent-id="acme-support"
  data-channel="chat-bubble"
  defer
></script>
```

The `data-channel` line decides the style: `chat-bubble` or `center-stage`. To switch a page from one style to the other, copy the code from that style's dialog.

> [!TIP]
> Paste the code once, in your site-wide footer area. If you paste it on every page by hand, it's easy to miss one.

## Test it for real

1. Open your website at one of the allowed addresses. A private browser window helps you see what a new visitor sees.
2. Look for the chat bubble in the corner, or the chat bar at the bottom. It can take a few seconds to appear.
3. Ask a real question, for example "Do you ship to Canada?".
4. In Hourzero, open **Activity → Conversations** and select **Visitors**. Your test chat appears there.

Messages on your live website are real conversations, so they use credits.

## Update the widget later

You don't need to touch your website again. Change the look, instructions, or knowledge in Hourzero, select **Save draft**, and then select **Publish → Website widget → Publish latest draft**. Visitors get the new version the next time they load a page.

To take the widget offline, turn off **Agent replies** on the **Overview** tab, save, and publish. The dialog warns you that publishing will turn off the live widget.

## Recognize signed-in customers

If customers sign in to your website, the widget can know who they are: their chats follow them across devices, the agent stops asking for their email, and actions can act for them. Your server signs a short token for the signed-in user and your page passes it to the widget. See [Identity verification](https://hourzero.dev/docs/integrations/identity-verification).

## Website actions

Some [custom actions](https://hourzero.dev/docs/ai-agent-management/actions/custom-action) can run on your own website, for example looking up order 48213 in the shop the visitor is signed in to. These actions only work in the installed widget on your site, or in [Chat Iframe](https://hourzero.dev/docs/integrations/chat-iframe#website-actions-and-website-forms) installed with its script, not in the Playground or in messaging apps. Ask your developer to follow the custom action guide.

Website actions only run on pages where the widget loads. To keep an action that uses your customers' login, like cancelling a subscription, inside your account area, list only those pages, for example `app.acme.com/account*`. If a visitor leaves those pages, the widget unloads and the action can't run. [Excluded pages](#hide-the-widget-on-certain-pages) work the same way: no action runs there.

> [!WARNING] Page paths don't limit actions that run on Hourzero
> [MCP servers](https://hourzero.dev/docs/ai-agent-management/mcp) and server API requests run on Hourzero's servers with the access you gave them, not in the visitor's browser. Anyone who can chat with this channel could trigger them, whichever page they're on. Only turn on tools that are safe for every visitor of that channel.

## Troubleshooting

### The widget doesn't appear on my site

Work through these in order:

- **Is the address allowed?** The page's address must match a line in **Allowed domains** exactly. `acme.com` doesn't cover `www.acme.com`. If a line has a page path, the widget only appears on that page.
- **Is the page excluded?** Check **Excluded pages**. A line like `/account*` hides the widget on every page that starts with `/account`.
- **Did you publish after changing the domains?** Domain and page changes stay in your draft until you publish.
- **Is the code on that page?** Ask your developer to check that the script is in the page, or paste it again in your site builder's site-wide setting.
- **Are replies turned on?** Check **Agent replies** on the **Overview** tab, then publish.

If the widget can't load within 30 seconds, it removes itself quietly so your page isn't affected. Your developer will see the message "Hourzero: widget unavailable" in the browser's developer console. If the website itself isn't in **Allowed domains**, the message is "Hourzero: this website isn't in the widget's allowed domains." Pages you left out on purpose stay silent.

### It works on one address but not another

Add each address separately. For example, add `acme.com` and `*.acme.com` to cover both `acme.com` and `www.acme.com`. Remember staging or test addresses too.

### It appears on the wrong pages

Check the lines for that website in **Allowed domains**. An address without a path, like `acme.com`, shows the widget on every page, even if other lines list single pages. Remove it to keep only the pages you listed. To keep showing it almost everywhere, add the pages where it shouldn't appear to **Excluded pages** instead. Then publish again.

### My changes don't show up

Select **Save draft**, then publish the style you changed. Chat Bubble and Center Stage are published separately. Then reload your website.

### My site's security settings block the widget

Some websites only allow scripts and embedded frames from approved addresses. Your developer needs to allow the Hourzero address (for example `hourzero.dev`) for scripts, frames, and connections (`script-src`, `frame-src`, and `connect-src`). Publishing again won't fix this; it has to be changed on your website.

## Next steps

- [Playground](https://hourzero.dev/docs/ai-agent-management/playground): Style the widget and test answers before visitors see them.
- [Publishing and version history](https://hourzero.dev/docs/ai-agent-management/deployments): See what's live on each channel and roll back if needed.
- [Custom actions](https://hourzero.dev/docs/ai-agent-management/actions/custom-action): Let the agent look up orders and do tasks on your website.
- [Conversations](https://hourzero.dev/docs/ai-agent-management/conversations): Read every chat visitors have with your agent.
