Chat Identity Verification
Identity verification proves that a signed-in user is who your website says they are. It stops anyone from reading another person's conversations by putting that person's user ID in the messenger snippet. Use it whenever you pass user_id or email to the messenger.
How it works
- HelpGuides gives your messenger a secret key.
- When a user loads your page, your server signs their user ID with that key and passes the signature to the messenger as
user_hash. - HelpGuides checks the signature. Only a verified user ID is linked to that user's past conversations, and only a verified user can use actions set to Only for signed-in customers.
Without a valid user_hash, the name and email are still shown to your team, marked Unverified. They're never used to look up anyone's earlier conversations.
Find your secret
Go to Inbox, then Messenger settings, then the Install & security tab. Under Identity verification, click Show next to Identity secret. Keep this secret on your server. Never put it in browser code.
Compute the user_hash on your server
The hash is an HMAC-SHA256 of the user's ID, using your secret, written as lowercase hex. If you don't pass a user ID, sign the email instead. A signed email is verified, but it doesn't link the visitor's conversations across devices, and it isn't enough for signed-in actions, which need a verified user ID.
| Language | Code |
|---|---|
| Node.js | crypto.createHmac('sha256', SECRET).update(user.id).digest('hex') |
| C# | Convert.ToHexString(new HMACSHA256(Encoding.UTF8.GetBytes(SECRET)).ComputeHash(Encoding.UTF8.GetBytes(user.Id))).ToLowerInvariant() |
| PHP | hash_hmac('sha256', $user->id, $SECRET) |
| Python | hmac.new(SECRET.encode(), user.id.encode(), hashlib.sha256).hexdigest() |
Then pass it in the snippet alongside the user's details:
window.HelpGuidesChatSettings = {
app_id: "YOUR_APP_ID",
user_id: "12345",
email: "jane@example.com",
name: "Jane Doe",
user_hash: "HASH_FROM_YOUR_SERVER"
};Require verification
Once every page that passes user details also passes a user_hash, switch on Require verification. The messenger then refuses any user ID or email without a valid hash.
Rotating the secret
Click Rotate to create a new secret. Every hash made with the old secret stops working immediately, so update your server at the same time.
Actions for signed-in customers
An action with Only for signed-in customers, and send their user ID turned on lets the AI look up the customer's own account, for example "what plan am I on?". Identity verification is what makes these safe:
- The action is offered to the AI only when the visitor's
user_idcomes with a validuser_hash. Anonymous and unverified visitors never get it. - The action receives the verified user ID, sent under the name set in Send the user ID as. HelpGuides fills it in; the AI never sees it and can't supply one, so a visitor can't get the AI to look up someone else's account.
See Chat Actions for setting them up.
Visitors who sign in partway through
If someone chats anonymously and then signs in with a verified user ID, their earlier conversations move to their verified account automatically.
When a user signs out
Call HelpGuidesChat('shutdown') when a user signs out of your site. Until you do, the browser stays verified as that user. The next person on that browser could see their conversations, and signed-in actions would still look up the previous user's account.
See also Installing the Chat Messenger on Your Website and Chat Messenger JavaScript API.