Troubleshooting at a glance
- Settings → Setup & API Key checks your install again when you return. The first step without a check points to the cause.
data-debugon the HelpAlive tag logs what HelpAlive does, and why it refused a call, to the browser console.- The agent appears only for identified users, and only once it is switched on in Controls with a published source.
reset()belongs in your logout code, apart fromidentify().- Your project key is public, so you can include it when you email support. Never send your signing secret.
Prerequisites
- Access to your app in a browser with developer tools.
- Access to Settings → Setup & API Key in the dashboard.
How to find the cause
1
Read the setup steps
Use your app, then come back to Settings → Setup & API Key; it checks again when you return. The first step without a check points to the cause. Each step has one line saying what HelpAlive saw.
2
Turn on console logs
Add HelpAlive then logs what it does, and why it refused a call, to the browser console. Some lines are at the verbose level, so show all levels in the console. Remove
data-debug to the HelpAlive tag while you test:data-debug before you ship.3
Find your failure below
Match what you see to one of the entries below, in order.
Why does nothing start?
Nothing starts when the HelpAlive tag has nodata-api-key.
What you see: step Add HelpAlive to your app still says “Not on your pages yet.”, and the console shows nothing, even with data-debug.
Fix: add data-api-key="YOUR_PROJECT_KEY" to the tag, with the key from Settings → Setup & API Key. If you regenerated the key, put the new one in the tag, because the old one stops working shortly after.
Why is the script blocked?
The script is blocked when your Content Security Policy lacks our sources or your nonce, or when an ad blocker or privacy extension blocks it. What you see: step Add HelpAlive to your app still says “Not on your pages yet.” The console shows an error naminghelpalive.js, Content Security Policy or a blocked request.
Fix: add our sources to your policy, and put your nonce on our tag if your policy uses one. See Content Security Policy. Ad blockers and privacy extensions can also block the script: test in a private window with extensions off.
Why does setup stay on Waiting for someone to sign in?
Setup stays there whenidentify() is never called. The agent never appears either, because it appears only for identified users.
What you see: step Add HelpAlive to your app says “On your pages. Waiting for someone to sign in to your app.” No chat button appears.
Fix: call identify() after login and on every page load while the user is signed in, with the four queue lines above it. See Identify users.
Why is identify() refused?
identify() is refused when userId is empty, or when userId or tenantId isn’t text or a number of up to 255 characters.
What you see: the same as above, although your code calls identify(). With data-debug, the console says why.
Fix: pass userId and tenantId as text or a number, up to 255 characters each. Don’t pass an empty userId. With a user token, keep the ids in it under 200 characters. Other fields of the wrong type are left out without stopping the call.
What if reset() runs straight after identify()?
Runningreset() straight after identify() forgets the user at once, which is why the chat button doesn’t appear, or doesn’t stay.
What you see: the chat button doesn’t appear, or doesn’t stay, although your code calls identify().
Fix: move reset() into your logout code, apart from identify().
What if the agent is off, or has no published docs?
Your users don’t see the agent until it is switched on in Controls, and it can’t be switched on until a source is published on Train. What you see: step 1 has a check, but Train the agent on your product doesn’t, or your users don’t see the agent. No chat button appears. Fix: publish at least one source on Train, then switch the agent on in Controls. Check that Who gets it includes the user you test with.Why does the agent appear only after a short wait?
What you see: you switched the agent on, or changed Who gets it, but a page that was already open doesn’t show the change. A user who already had your app open sees the change within a minute or a few page loads. Switching the agent off takes effect the same way. A browser that has never loaded the agent’s settings gets them at once. Fix: wait a minute, then load a couple of pages.Why are requests refused once Only allow verified users is on?
Only allow verified users means that HelpAlive refuses every request without a valid user token. What you see: the chat button appears, but asking something shows “Your session needs a refresh. Reload the page to keep chatting.” Users without a token also stop showing in Reports and Audience. Fix: send a token from every page that callsidentify(), or turn the switch off while you fix it. See Verify users.
What if your account has no subscription?
The agent shows only during your free trial or while you are subscribed. What you see: everything is set up, but the chat button never appears. Fix: subscribe on Settings → Billing and usage.Why does the agent stop offering assists?
The agent stops offering assists because a usage limit was reached: your plan’s, or one you set per user, tenant or organization on Controls. Users are never told about a limit. What you see: the agent answers in words and no longer offers to do tasks. Later it may say “Chat isn’t available right now. Please try again later.” Fix: see Limits and usage.Check it works
When the first three steps on Settings → Setup & API Key have a check, Everything is working. shows at the top. Sign in to your app as a user who gets the agent, open the chat button, and ask a question your docs answer.Still stuck?
Email support@helpalive.com. To help us answer quickly, include:- the address of a page where the problem happens, and the browser you used;
- which steps on Settings → Setup & API Key have a check, and what step 1’s line says;
- what the browser console shows with
data-debugon the tag.
Next
Install the script
Every rule of the install.
Controls
Switch the agent on and choose who gets it.
Content Security Policy
The sources to allow.