Troubleshooting Chat

Common chat problems and how to fix them. When the messenger has a problem it stays invisible rather than breaking your page, so start with your browser's developer console and look for a [HelpGuides Messenger] message.

The chat button doesn't appear

If there's no message at all, check the snippet is on the page, and before </body>. See Installing the Chat Messenger on Your Website.

I don't see Inbox in my project

Chat isn't turned on for your account yet. Contact HelpGuides support.

The AI always says it couldn't find an answer

• Make sure the relevant articles are published. The AI never uses drafts.
• Check the project is ticked under Knowledge sources, and that its description matches the questions people ask.
• Use the unanswered questions list in Chat Reports to see what's missing, then write those articles.
• Try the question on the Test tab in Messenger settings to see what the AI searched for and which articles it found. See Testing the Chat AI.

The AI answers from the wrong project

Each AI answer in the inbox shows Answered from …, and the Test tab shows the sources searched, with the primary one marked. Make each knowledge source's description more specific about what it covers and when to use it, so the right project is chosen as the primary source. See Chat Knowledge Sources.

The AI doesn't use an action

• Make sure the action is switched on and complete. An action marked Incomplete: the AI can't use it yet is missing its name, its description or an https URL.
• The AI decides from When should the AI use it, and what does it return? Say plainly what the action answers and when to call it.
• An action set to Only for signed-in customers, and send their user ID is offered only to visitors your site has verified with identity verification. Anonymous and unverified visitors never get it, and neither does the Test tab. See Chat Identity Verification.
• An action with a required Website attribute parameter is offered only when your site passed that attribute at boot. Check the attribute's key matches, and that it's in attributes on the pages where the question is asked.
• Use Run test to call the endpoint with sample values and see exactly what the AI would be given. See Chat Actions.

A proactive message doesn't appear, or appears on the wrong site

• A pattern that's only a path, such as / or /pricing/, matches on every site the messenger is installed on. To limit it to one site, start it with the host, for example app.example.com/.
• The first matching message in the list wins. Move site-specific messages above general ones.
• Check the message is switched On and that you clicked Save settings.
• A visitor who has the messenger open or is mid-conversation never gets one, and depending on How often, they may already have seen it.
• See Chat Proactive Messages.

The Help tab doesn't appear in the messenger

Check Show help articles in the messenger is on, on the General tab of Messenger settings. The tab shows the project chosen in Help articles from; if that project is set as an internal knowledge source (Link to articles off), it's never shown and the tab disappears. See Chat Knowledge Sources.

The Help tab shows the wrong docs

The Help tab shows and searches one project, chosen in Help articles from on the General tab of Messenger settings. It's this messenger's own project unless you pick another from your account. Choose the right one and click Save settings. This doesn't change what the AI answers from, which is still all your knowledge sources. A project set as an internal knowledge source (Link to articles off) is never shown.

Everyone on the team shows as offline

Visitors see a teammate as online only while that person has the inbox open and is set to Available. After 15 minutes with no mouse, keyboard or touch in any inbox tab, the inbox switches its owner to Away automatically. Moving the mouse or pressing a key in an inbox tab makes them Available again. See Using the Chat Inbox.

A visitor shows as online for hours

In Visitors online, a visitor shows a grey dot and idle after 5 minutes without mouse, keyboard, scroll or touch on the page, and drops out of the list after 30 minutes idle. Any activity brings them back. Visitors still on a page that was loaded before this was introduced don't report activity until they reload it, so they can stay in the list longer. See Using the Chat Inbox.

Nobody on the team was told about a conversation

• Check the conversation's team, shown in the inbox details panel, has a Slack channel or email addresses. Use the Test buttons in Notifications.
• For Slack, make sure Slack is connected in your project's Settings. For a private channel, invite the HelpGuides app to it.
• "Alert when a visitor writes to the team" is skipped while a teammate is Available in the inbox, if Only when nobody is online is on.

Test says the email was sent, but it never arrives

If Test in Notifications says Test email sent, the email left HelpGuides. When it still doesn't arrive, the receiving address is usually refusing or holding it. Shared addresses such as support@ or sales@ are often groups or filtered mailboxes that only accept mail from people in your organisation or your contacts.

• Add noreply@helpguides.io, the address chat emails come from, as a contact or allowed sender for that mailbox or group.
• Check the group's pending messages, or your mail system's quarantine, for mail from noreply@helpguides.io.
• To confirm everything else works, add your own address to the team, click Test, and check it arrives.

Slack alerts for a conversation aren't in one thread

• Conversations whose alerts started before threading was introduced keep posting their alerts as separate messages.
• Moving a conversation to another team starts a new thread in that team's channel.
• "Needs a person" and "left their details" alerts are posted in the thread and also shown in the channel, so they can appear in both places. See Chat Notifications and Teams.

Phone notifications don't arrive

• On iPhone you need iOS 16.4 or later, and the inbox must be added to your home screen from Safari. Open it from the home screen icon and sign in there; it keeps its own sign-in, separate from Safari.
• In the installed inbox, open the phone panel, tap Turn on notifications, and allow them when asked. Check they're still allowed in your phone's settings.
• Each phone chooses its own alerts (Every new chat, Needs a person, Replies). Check the right ones are on for that phone.
• Focus or Do Not Disturb can silence them. Available/Away doesn't affect phone alerts.
• See Using the Chat Inbox on Your Phone.

A visitor can't send files

• Check Let visitors send files and images is on, on the Install & security tab of Messenger settings. Your team can always send files.
• Each file can be up to 10 MB, with up to 5 per message. A visitor can upload up to 30 files an hour.
• Images can be PNG, JPEG, GIF or WebP. Other files can be PDF, TXT, CSV, LOG, Word, Excel, PowerPoint or ZIP. HTML, SVG and programs are refused.
• See Sending Files and Images in Chat.

A visitor never received our reply by email

Follow-up emails are only sent if the visitor gave an email, and hadn't already read the reply in the messenger. If the visitor had left your website, the email goes out about a minute after your reply; if they were still there, after the wait in Wait before emailing (3 minutes by default). Emails come from noreply@helpguides.io, so an address that only accepts known senders may refuse them. See Chat Notifications and Teams.

A visitor lost their conversation when moving to another subdomain

Browsers keep chat sessions separate for each domain. Set Share visitors across subdomains of in Messenger settings. See Installing the Chat Messenger on Your Website.

Messages only appear after refreshing

Live updates may be blocked by a firewall or proxy. The messenger falls back to checking for new messages every few seconds, so conversations still work, just with a short delay.

Can visitors see internal notes or AI summaries?

No. Internal notes, the AI summary written when a conversation is handed to your team, the actions the AI called, and articles from internal knowledge sources are shown only in the inbox. Visitors never receive them.

Still stuck? Start from HelpGuides Chat Overview, or contact HelpGuides support.