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.

The Identity verification section with the hidden identity secret, Show and Rotate buttons, and the Require verification switch — Install and security tab, Identity verification

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: "[email protected]",
  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_id comes with a valid user_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.