Set up HelpAlive: four steps, project key and signing secret

Setup & API Key is the page in the HelpAlive dashboard where you install HelpAlive and check that it works. It is the second tab of Settings, at Settings → Setup & API Key. It also holds your project key and your signing secret.

​

Setup at a glance

• Setup has four steps: Add HelpAlive to your app, Train the agent on your product, Test it on your app and Verify your users, which is optional.
• Each step has one line saying what HelpAlive saw, and gets a check by itself once it is done.
• Your project key is public: it goes in the script tag on every page.
• Your signing secret is private. Keep it on your server, like a password.
• With Only allow verified users on, anyone without a valid user token can’t see the agent.

​

Is it working?

The band at the top says how many of the 4 steps are done and what to do next, in one sentence. Once the first three are done, it says your agent is ready for your users. When everything works, Everything is working. shows beside the refresh button. Each step in the list on the left has one line saying what HelpAlive saw: The checks need a real visit: once the tag is live, sign in to your app, click around, and come back to this page. It checks again when you return, so you don’t need to refresh. The sidebar’s Setup checklist counts the same 4 steps, by shorter names: Add HelpAlive, Train the agent, Test it on your app and Verify users. Done steps stay in it with a check.

​

The four steps

The steps are listed on the left, one shown at a time. Each gets a check by itself once it is done.

1. Add HelpAlive to your app: your developer, about 10 minutes. Choose With an AI coding agent, Add it yourself or Google Tag Manager. The first gives a prompt to paste into your coding tool; the second, the tag, identify() and reset(). Under Tell HelpAlive who is signed in, pick B2B: users belong to tenants or B2C: users have no tenant. See Install the script and Identify users.
2. Train the agent on your product: add your docs on Train and publish them. See Train.
3. Test it on your app: “Try the agent in your own app, in your browser only. The Test page shows you how.” The button opens the dashboard’s Test page. The step turns green once a test has run an assist or a chat. This step is locked until a source is published. See Test it on your app.
4. Verify your users: optional, recommended. See Verified users.

​

Your project key

Your project key sits under the steps. It is public: it goes in the script tag on every page, and the code on this page already contains it. Copy copies it. Regenerate makes a new key, so update your script straight away. If your pages used the key in the last week, the dialog warns you first. You can regenerate once an hour.

​

Verified users

Without this step, HelpAlive trusts the user id your page sends. This means that someone who edits the page in their browser could send another person’s id and read that person’s chats. With it, your server signs each id, and once Only allow verified users is on, nobody can pretend to be someone else. Add it before you open the agent to all your users.

​

Your signing secret

Press Create your signing secret. Keep it on your server, like a password. The code samples read it from HELPALIVE_SIGNING_SECRET; the name is up to you. Reveal shows it and Copy copies it. Rotate issues a new secret. Put it on your server; nothing in your code changes. The previous secret keeps working until you rotate again, so nobody is refused while you roll it out. If a secret leaked, rotate once more after your server uses the new one, and the leaked one stops working.

​

Make a user token

Under Make a user token on your server, and pass it to identify(), choose With an AI coding agent or Add it yourself. The code comes in eight server languages. The user token refers to a short signed text your server makes per person. Your page passes it to identify(). The code is on Verify users.

​

Check your setup

After you deploy your signing, sign in to your app and open the agent. Then press refresh under Check your setup: it looks for a verified sign-in in the last 30 minutes. Verified sign-ins, last 7 days shows what share of sign-ins arrived verified, unsigned or failed.

​

Only allow verified users

With this switch on, anyone without a valid user token can’t see the agent, and their activity is not recorded.

• It can be turned on only after a verified sign-in in the last 30 minutes. Recommended means that nearly all sign-ins in the last 7 days arrived verified and none failed.
• Turning it on asks first, and says how many people in the last 7 days would lose the agent.
• Turning it off always works, so you have a way out if signing breaks.

While the switch hides the agent from some people, step 4 says how many, the main reason and the fix, and we email your team. See Verify users.

​

Check it works

The first three steps have a check, and the band says your agent is ready for your users.

​

Troubleshooting

• “Our script reaches your pages but can’t start.” This means that the tag has the wrong project key. Copy it again from this page.
• “Last seen on your pages … Is the tag still there?” This means that the tag was removed, or your pages stopped loading it.
• Step 1 stays on “Waiting for someone to sign in”. This means that identify() isn’t running. Call it after login and on every page load.
• Some users can’t see the agent after you turn on Only allow verified users. This is because their pages send no token, or a token that fails. Step 4 names the main reason and the fix. Turn the switch off while you fix the signing, then turn it on again.
• “Too soon to regenerate.” This is because the project key can be regenerated once an hour.

​

Next