Troubleshooting

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. 1ArrivedIs the customer's message in Activity → Conversations?
2. 2AnsweredDid the agent reply, or is there an error in the chat?
3. 3Up to dateDoes 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

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.
2. Publish again. Changes to allowed domains 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.

The Help Page can't be published, so it never appears on a website. See Website widget for the full setup.

The agent gives wrong or made-up answers

1. See what the agent looked up. Open the chat in Activity → Conversations. Boxes like Knowledge retrieval or Action show what the agent searched 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."

The Suggestions page lists questions customers asked that your sources didn't cover. A benchmark lets you retest a set of questions after each fix.

My changes aren't live

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.

See Publishing and version history.

The agent stopped replying everywhere

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.

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

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 and 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.
• Twilio: in Twilio, the number's incoming message webhook must point to the Hourzero address and use HTTP POST.

Each integration guide 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.

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.

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.

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.

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

Next steps