# Troubleshooting

> Fix the most common problems: a missing chat bubble, wrong answers, changes that aren't live, and channels that don't reply.

Find the problem you're seeing, then work through its checklist from the top. The first items fix most cases, so you rarely need to go far down the list.

Before you start, it helps to know where the problem is. Ask yourself:

1. **Arrived**: Is the customer's message in Activity → Conversations?
2. **Answered**: Did the agent reply, or is there an error in the chat?
3. **Up to date**: Does Deployments show your latest version for that channel?

If the customer's message isn't in **Conversations** at all, the problem is the connection to the channel. If the message is there but the answer is wrong, the problem is the agent's knowledge or instructions.

## The chat bubble doesn't appear on my website

> [!TIP] Most common fix
> The website address isn't in **Allowed domains**, or you changed the domains and didn't publish. The address must match exactly: `acme.com` doesn't cover `www.acme.com`.

1. **Check the allowed websites.** In the Playground, open **Chat Bubble** (or **Center Stage**), select **Publish → Website widget**, and look at **Allowed domains**. Add every address visitors use, for example both `acme.com` and `*.acme.com`. If the list is empty, the widget appears nowhere. If a line includes a page path, like `acme.com/pricing`, the widget only appears on that page. Also check **Excluded pages**: the widget never appears on pages listed there.
2. **Publish again.** Changes to allowed domains and excluded pages stay in your draft until you select **Publish saved draft** or **Publish latest draft**.
3. **Check that replies are on.** On the **Overview** tab, **Agent replies** should say **Replies on after publishing**. If you changed it, save and publish.
4. **Check the code is on the page.** Ask whoever manages your website to confirm the Hourzero script is pasted on every page, ideally in a site-wide footer setting.
5. **Check you published the right style.** The code says `chat-bubble` or `center-stage`. That style must be the one you published.
6. **Ask your developer to check for blocking.** Some websites block scripts from other addresses. In the browser's developer console they'll see "Hourzero: widget unavailable" if the widget couldn't load.

Help Page is coming soon and can't be published yet, so it never appears on a website. See [Website widget](https://hourzero.dev/docs/integrations/website-widget) for the full setup.

## Chat Iframe doesn't appear on my page

> [!TIP] Most common fix
> The website isn't in Chat Iframe's **Allowed domains**, or you changed them and didn't publish. Chat Iframe has its own list, separate from Chat Bubble and Center Stage.

1. **Check the allowed websites.** In the Playground, open **Chat Iframe**, select **Publish → Chat Iframe**, and look at **Allowed domains**. Add every address visitors use, for example both `acme.com` and `www.acme.com`. Chat Iframe takes domains only, without page paths.
2. **Publish again.** Domain changes stay in your draft until you select **Publish saved draft** or **Publish latest draft**.
3. **Check that replies are on.** On the **Overview** tab, **Agent replies** should say **Replies on after publishing**. If you changed it, save and publish.
4. **Check the code and its height.** The code must be on the page. With the script, the page also needs the container it names, by default `<div id="hourzero-chat">`, with a height. With **Iframe only**, if the iframe's height is `100%`, the element around it needs a height too.
5. **Ask your developer to check for blocking.** Websites that limit embedded frames must allow the Hourzero address under `frame-src`.

See [Chat Iframe](https://hourzero.dev/docs/integrations/chat-iframe#troubleshooting) for more.

## The agent gives wrong or made-up answers

> [!TIP] Most common fix
> The answer isn't in your data sources, or you added it but didn't retrain and publish. Add the missing information, select **Retrain agent**, then publish the channel.

1. **See what the agent looked up.** Open the chat in **Activity → Conversations**. Lines like **Knowledge** or **Action** show what the agent read and what it got back. Select one to expand it.
2. **Check the information exists.** On **Build → Data Sources**, open the source and select **View parsed content**. Make sure the right facts are there, and that Hourzero read the file or page correctly.
3. **Look for conflicts.** If your return window is 30 days in one source and 14 days in another, the agent may pick either. Keep one version of each fact.
4. **Retrain.** If the banner says **Source changes are ready to train**, select **Retrain agent** and wait for **Training complete**.
5. **Publish.** Live channels keep using what they had at the last publish, even after training.
6. **Use Q&A for exact wording.** Prices, policies, and promises work best as Q&A pairs.
7. **Tighten the instructions.** On **Build → Instructions**, tell the agent what to do when it doesn't know, for example: "If the answer isn't in your knowledge, say so and offer to connect the customer with our team."

![Activity → Conversations with a jacket return open, showing the Look up order and Create return action boxes](https://hourzero.dev/marketing/app/conversations-light.webp "Expand the boxes in a chat to see exactly what the agent looked up before it answered.")

The [Suggestions](https://hourzero.dev/docs/ai-agent-management/suggestions) page lists questions customers asked that your sources didn't cover. A [benchmark](https://hourzero.dev/docs/ai-agent-management/benchmarks) lets you retest a set of questions after each fix.

## My changes aren't live

> [!TIP] Most common fix
> You saved but didn't publish, or you published a different channel. Each channel is published on its own.

1. **Save.** In the Playground, the bottom of the settings panel should say **Draft saved. Publish this channel to apply your changes.** If it says **Unsaved draft changes**, select **Save draft**.
2. **Retrain if you changed knowledge.** Training is needed after any change to data sources.
3. **Publish every channel you want to update.** Pick the channel under **Preview channel**, select **Publish**, and choose it. Publishing Chat Bubble doesn't update Center Stage, WhatsApp, or any other channel.
4. **Check shared instructions.** If a channel has **Use shared instructions** turned off, it ignores the **Instructions** page. Edit that channel's own instructions on the **Overview** tab.
5. **Check what's live.** Open **Deployments**. The row with **In production** for that channel is what customers get. Its **Created** time should match when you published.
6. **Reload.** On your website, reload the page. In messaging apps, send a new message.

![The Deployments page with one In production version per channel and older versions you can promote](https://hourzero.dev/marketing/app/deployments-light.webp "Each channel has one version marked In production. That's the version customers get.")

See [Publishing and version history](https://hourzero.dev/docs/ai-agent-management/deployments).

## The agent stopped replying everywhere

> [!TIP] Most common fix
> The workspace ran out of credits, or the agent hit its weekly limit. Check **Usage** first.

1. **Check workspace credits.** Open **Usage** in the workspace sidebar, or look at the **Credits** meter at the bottom of the sidebar. At zero, every agent stops replying. Upgrade in **Workspace Settings → Plans** or wait for the monthly reset.
2. **Check the agent's weekly limit.** Open the agent's **Settings**. If **Weekly credit spend limit** is on and used up, the agent waits until Monday 00:00 UTC. Raise the limit if you need to.
3. **Look for an error message.** In the Playground or website chat you may see "This workspace has run out of available credits…" or "This agent has reached its weekly credit spend limit." Messaging apps don't show these messages. The customer gets no reply.

See [Usage and credits](https://hourzero.dev/docs/workspace-management/usage).

## The agent stopped replying to one customer

1. **Check whether the chat is paused.** Open it in **Activity → Conversations**. If the button says **Resume AI**, a teammate or a Helpdesk ticket paused the agent. Select **Resume AI** when it's OK for the agent to answer again.
2. **Check the Paused view.** Select **Paused** at the top of the chat list to see every chat waiting for a person.
3. **Check the message limit.** If the customer sent many messages quickly, on your website or in a messaging app, **Limit messages per visitor** in the agent's **Settings → Security** may be holding them back for a short time.

## WhatsApp, Slack, or another app isn't replying

> [!TIP] Most common fix
> The channel is connected but not published, or **Agent replies** is off. Open the channel in the Playground, check **Agent replies**, select **Save draft**, then **Publish**.

1. **Check the connection.** Open **Channels**. The app should show **Connected**, or **Live** for WhatsApp. If it says **Not connected**, connect it again. Only owners and admins can connect apps.
2. **Check which agent answers.** On the connected account, select **Reply settings** and make sure this agent is assigned to that number, Page, account, or Slack channel. If the switch says **Currently assigned to** another agent, change it there first.
3. **Publish the channel.** In the Playground, pick the channel, make sure **Agent replies** is on, select **Save draft**, then **Publish**.
4. **Check credits and paused chats.** See [The agent stopped replying everywhere](#the-agent-stopped-replying-everywhere) and [The agent stopped replying to one customer](#the-agent-stopped-replying-to-one-customer).
5. **Send a fresh test message** from a real account, the way a customer would. Then look for it under **Visitors** in **Activity → Conversations**.

App-specific checks:

- **Slack:** the app must be in the channel. Type `/invite @Hourzero` there, then @mention it.
- **Discord:** @mention the bot in a server channel it can see and post in. It doesn't answer private messages.
- **Telegram:** in groups, mention the bot by its username.
- **WhatsApp:** the agent replies to messages customers send. It can't message customers first.
- **Messenger and Instagram:** make sure the right Facebook Page or Instagram account is connected and assigned.

Each [integration guide](https://hourzero.dev/docs/integrations) has a troubleshooting section for its app.

## A form, button, or action doesn't show up

1. **Check the channel allows it.** In the Playground, open the **Capabilities** tab for that channel. The action's switch should say **Enabled**.
2. **Check the channel type.** Forms and buttons only appear in your website chat. WhatsApp, Slack, and other messaging apps only get text replies.
3. **Check the description.** On **Build → Actions**, select **Configure** and read **When should the agent use it?**. The customer's question has to match what you describe.
4. **Turn on the Helpdesk for Human escalation.** Human escalation shows **Helpdesk disabled** until **Enable Helpdesk** is on.
5. **Save and publish.** Select **Save draft**, test in the preview, then publish the channel.

See [Actions overview](https://hourzero.dev/docs/ai-agent-management/actions/overview).

## A file or web page won't add as a data source

1. **Read the reason.** A source with **Failed** shows why under its name.
2. **Check the file type.** Hourzero accepts PDF, Word, Excel (`.xlsx`), PowerPoint (`.pptx`), CSV, plain text, and Markdown.
3. **Check the size.** The largest file depends on your plan, from 5 MB on Free to 100 MB on Enterprise. You can add up to 10 files at a time.
4. **For web pages,** check that the page loads in your browser.
5. **Very long files** are cut off after 400,000 characters. Split them into smaller files.

See [Data sources](https://hourzero.dev/docs/ai-agent-management/data-sources).

## Topics or Sentiment are empty

1. **Widen the filters.** Choose **All time** and **All channels**.
2. **Check you have real conversations.** Playground tests aren't analyzed.
3. **Give it time.** Conversations are analyzed after they've been quiet for 30 minutes, in groups of 25. Results usually appear within 24 hours.

See [Analytics](https://hourzero.dev/docs/ai-agent-management/analytics).

## I can't invite a teammate

1. **Check the workspace.** Personal workspaces can't have other members. Create a team workspace and invite people there.
2. **Check your role.** Only owners and admins can invite.
3. **Check your plan's member limit.** Pending invitations count toward it. Select **Revoke invitation** on one you no longer need, or upgrade.
4. **Check the email address.** The invited person must accept with the exact email address you invited, within 48 hours. Select **Resend invitation** if it expired.

See [Members and invitations](https://hourzero.dev/docs/workspace-management/members).

## I can't sign in

1. **Forgot your password?** Select **Forgot password?** on the sign-in page.
2. **Asked to verify your email?** Enter the code from the email Hourzero sent you, or request a new one.
3. **No access to your authenticator app?** Select **Use a backup code** on the **Two-factor authentication** page.
4. **Your company uses SSO?** Select **Sign in with SSO** and enter your work email. If it says SSO isn't available, contact your IT team.

See [Account settings and 2FA](https://hourzero.dev/docs/security/account) and [Single sign-on](https://hourzero.dev/docs/security/single-sign-on).

## Still stuck? What to send us

Include these details so we can help quickly:

- the workspace and agent name, for example "Acme / Acme Support";
- the channel, for example WhatsApp or Chat Bubble;
- whether it happened in the Playground or with a real customer;
- the date and time, with your time zone;
- what you expected and what happened instead;
- the exact error message, or a screenshot.

> [!WARNING]
> Never share passwords, backup codes, API keys, or tokens from apps like Slack or Telegram, even with support.

## Next steps

- [Frequently asked questions](https://hourzero.dev/docs/help-and-support/faq): Quick answers about saving, publishing, credits, and more.
- [Conversations](https://hourzero.dev/docs/ai-agent-management/conversations): Read chats and see what the agent did behind the scenes.
- [Publishing and version history](https://hourzero.dev/docs/ai-agent-management/deployments): Check what's live on each channel and roll back.
