Chat Iframe

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, 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. 1StyleSet the welcome message, prompts, and theme in the Playground.
2. 2AllowList the websites that may show the chat.
3. 3PublishMake your saved draft live for visitors.
4. 4Add the codePaste 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?

Pick Chat Iframe when the chat should be part of the page layout. Pick the 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.

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

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.

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.

<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

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, forms, and buttons from your actions, and reach your team through human handoff.

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:

• Website actions, which use Website API request or Website JavaScript handler.
• Website forms, 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, 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.

Next steps