# Chat Iframe

> Embed a full-size chat inside a page or section of your website, like a help center or a support tab in your app.

Chat Iframe puts a full conversation inside your own page, instead of floating over it. Use it where the chat is the content: a help center, a contact page, a docs page, or a **Support** tab in your app. Visitors see a wide message column, their past conversations, and a large message box at the bottom.

**Where to find it:** open your agent and go to **Playground**. Under **Preview channel**, choose **Chat Iframe**, then select **Publish → Chat Iframe**.

## How it works

Like the [website widget](https://hourzero.dev/docs/integrations/website-widget), Chat Iframe doesn't need an outside account, so there's nothing to connect. You list the websites that may show it, publish, and paste a standard `<iframe>` tag where the chat should appear.

1. **Style**: Set the welcome message, prompts, and theme in the Playground.
2. **Allow**: List the websites that may show the chat.
3. **Publish**: Make your saved draft live for visitors.
4. **Add the code**: Paste the iframe into the page or component.

Chat Iframe is a channel of its own. It has its own look, allowed websites, capabilities, and live version, so publishing it never changes Chat Bubble or Center Stage. You can use all three on the same website.

Chat Iframe is included on every plan, including Free.

## Chat Iframe or website widget?

| | Chat Bubble and Center Stage | Chat Iframe |
| --- | --- | --- |
| Where it appears | Over every page that loads the script | Inside the space you place it in |
| Code | One script in your site-wide footer | One iframe on each page that shows the chat |
| Allowed websites | Domains, with optional page paths and excluded pages | Domains only |
| Website actions and website forms | Yes | No |

Pick Chat Iframe when the chat should be part of the page layout. Pick the [website widget](https://hourzero.dev/docs/integrations/website-widget) when the chat should follow visitors around your site, or when your actions need to run on your website. See [What needs the website widget](#what-needs-the-website-widget).

## Style the chat

1. Open **Playground** and choose **Chat Iframe** under **Preview channel**.
2. On the **Display** tab, set the **Display name**, **Welcome message**, and **Suggested prompts**, and pick a theme. The welcome message is the large heading visitors see before they write.
3. On the **Overview** tab, choose whether visitors may send files (**File uploads**) and speak their questions (**Voice transcription**).
4. On the **Capabilities** tab, turn on the actions, skills, and MCP servers this channel may use.
5. Select **Save draft**.
6. Select **Preview** to open the chat on a clean page in a new tab.

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

## Allow your website

Allowed domains are the websites that may show the chat. On any other website, the browser refuses to show it, which stops other people from copying your code onto their own sites and using your credits.

1. In the Playground, select **Publish → Chat Iframe**. The **Embed Chat Iframe** dialog opens.
2. Under **Allowed domains**, type one website address per line, without `https://` and without a page path.
3. Wait for **Saved to draft** to appear under the box.

| You type | The chat can appear on |
| --- | --- |
| `acme.com` | Every page of `acme.com` |
| `www.acme.com` | Every page of `www.acme.com` |
| `*.acme.com` | Every subdomain, like `help.acme.com` and `app.acme.com`, but not `acme.com` itself |

Chat Iframe doesn't accept page paths like `acme.com/help`, and it has no **Excluded pages**. The chat appears exactly where you paste the code, so you choose the pages by where you put it.

You can add up to 50 lines. If the list is empty, you can't publish the channel.

> [!IMPORTANT]
> Changes to allowed domains are saved to your draft. They only reach the live chat when you publish Chat Iframe 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 chat

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 → Chat Iframe**.
4. Select **Publish saved draft**. The next time you publish, the button says **Publish latest draft**. A message confirms the channel is published.

## Add the code to your website

1. In the **Embed Chat Iframe** dialog, under **Install the iframe**, select **Copy code**.
2. Paste the code into the page or component where the chat should appear. Most website builders have a block for this, often called embed, custom HTML, or code.
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.

```html
<iframe
  src="https://hourzero.dev/embed/acme-support/chat-iframe"
  title="Chat with our assistant"
  style="width:100%;height:640px;border:0"
  allow="microphone"
></iframe>
```

The chat fills the width of the space you put it in. Change `height` to fit your page: messages scroll inside the chat, and the message box stays at the bottom. Keep `allow="microphone"` so visitors can speak their questions when **Voice transcription** is on. You can reword the `title`, which screen readers announce.

### In a React app

```tsx
export function SupportChat() {
  return (
    <div className="h-[640px] w-full overflow-hidden rounded-2xl border">
      <iframe
        src="https://hourzero.dev/embed/acme-support/chat-iframe"
        title="Chat with our assistant"
        className="h-full w-full border-0"
        allow="microphone"
      />
    </div>
  );
}
```

When the iframe's height is `100%`, give the element around it a fixed height, like the `640px` above. Use your own CSS to make it shorter on small screens.

## What visitors can do

- Chat with your agent, which uses this channel's published instructions, knowledge, and capabilities.
- Start a new chat, or open **Chat history** to go back to an earlier one.
- Attach files and speak their questions, if you turned those on.
- Use [widgets](https://hourzero.dev/docs/ai-agent-management/widgets), [forms](https://hourzero.dev/docs/ai-agent-management/actions/custom-form), and [buttons](https://hourzero.dev/docs/ai-agent-management/actions/custom-button) from your actions, and reach your team through [human handoff](https://hourzero.dev/docs/ai-agent-management/actions/human-escalation).

Your plan's limits apply as on any channel. For example, widgets and the Helpdesk need a plan that includes them. Chats on your live website are real conversations, so they use credits.

### What needs the website widget

The iframe is a separate page inside yours. It can't run your website's code or use your visitor's login on your site, so these only work in [Chat Bubble or Center Stage](https://hourzero.dev/docs/integrations/website-widget):

- [Website actions](https://hourzero.dev/docs/ai-agent-management/actions/custom-action#run-actions-on-your-website), which use **Website API request** or **Website JavaScript handler**.
- [Website forms](https://hourzero.dev/docs/ai-agent-management/actions/custom-form#let-your-website-supply-the-form), where your website supplies the form's fields.

Turn those off for Chat Iframe on the **Capabilities** tab. Actions that run on Hourzero's servers, such as server API requests and [MCP servers](https://hourzero.dev/docs/ai-agent-management/mcp), work as usual.

## Test it for real

1. Open the page with the iframe at one of the allowed addresses. A private browser window helps you see what a new visitor sees.
2. Ask a real question, for example "Do you ship to Canada?".
3. In Hourzero, open **Activity → Conversations** and select **Visitors**. Your test chat appears there.

## Update the chat 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 → Chat Iframe → Publish latest draft**. Visitors get the new version the next time they load the page.

To take the chat offline, turn off **Agent replies** on the **Overview** tab, save, and publish. The space on your page stays empty until you publish with replies on again, so you may want to remove the iframe from your page too.

## Troubleshooting

### The chat doesn't appear, or the space is empty

Work through these in order:

- **Is the address allowed?** The page's address must match a line in **Allowed domains**. `acme.com` doesn't cover `www.acme.com`.
- **Did you publish after changing the domains?** Domain changes stay in your draft until you publish.
- **Are replies turned on?** Check **Agent replies** on the **Overview** tab, then publish.
- **Does the iframe have a height?** If it uses `height: 100%`, the element around it needs a height too.
- **Do your site's security settings allow it?** Some websites only allow embedded frames from approved addresses. Your developer needs to allow the Hourzero address (for example `hourzero.dev`) under `frame-src`.

### Visitors can't use the microphone

Check that the iframe code still has `allow="microphone"`, that **Voice transcription** is on, and that the visitor allowed the microphone in their browser.

### An action doesn't run

Website actions and website forms only run in Chat Bubble or Center Stage. See [What needs the website widget](#what-needs-the-website-widget).

## Next steps

- [Playground](https://hourzero.dev/docs/ai-agent-management/playground): Style the chat and test answers before visitors see them.
- [Website widget](https://hourzero.dev/docs/integrations/website-widget): Add a chat bubble or a chat bar that stays on every page.
- [Publishing and version history](https://hourzero.dev/docs/ai-agent-management/deployments): See what's live on each channel and roll back if needed.
- [Conversations](https://hourzero.dev/docs/ai-agent-management/conversations): Read every chat visitors have with your agent.