Live Chat SDK

Identity validation

When you call setUser from the browser, anyone who reads your JavaScript can claim to be any of your customers. Identity validation closes that hole by requiring a signature only your server can produce.

How it works

Each web widget inbox carries a private secret — the HMAC token — that lives only on the server side. To prove a visitor really is the user you say they are, you sign their identifier with that token using HMAC-SHA256 and pass the result alongside the user data.

  1. Your backend reads the HMAC token from the dashboard once and stores it as a secret.
  2. When you render a page for a logged-in user, your backend computes identifier_hash = HMAC-SHA256(identifier, hmacToken).
  3. The hash is injected into the page and passed to $hellouOne.setUser.
  4. HellouOne re-computes the hash on its end and only accepts the identity if it matches.
Only the identifier is signed

The signature covers the identifier string and nothing else. Name, email, phone, avatar URL and other user fields travel alongside it but are not part of the hash — treat the identifier as the canonical “who is this” field. Email and phone count as verified only with identity_fields_hash (below).

Change for existing sites: a site that sends only identifier_hash no longer has AI agent connectors see that email as verified until it adds identity_fields_hash. An email or phone number that another contact already holds never merges the visitor into that contact, signed or not.

Once a contact has been verified, its email and phone number are locked: the first values signed with a valid identity_fields_hash are kept, and a later setUser call cannot change them, signed or not. A field that was still empty takes the first signed value. To correct a verified email or phone, edit the contact in the dashboard.

1. Find your HMAC token

In the dashboard, open Inboxes → (your web widget) → Configuration. The HMAC token is shown beneath the embed snippet. Copy it into a secret store on your backend — never commit it to a public repo and never expose it to the browser.

2. Compute the hash on the server

Below are minimal examples in a few common languages. In every case, the input is the user’s identifier as a string and the key is the HMAC token.

Node.js

const crypto = require('crypto');

const identifierHash = crypto
  .createHmac('sha256', process.env.HELLOUONE_HMAC_TOKEN)
  .update(String(user.id))
  .digest('hex');

Ruby

require 'openssl'

identifier_hash = OpenSSL::HMAC.hexdigest(
  'sha256',
  ENV.fetch('HELLOUONE_HMAC_TOKEN'),
  user.id.to_s
)

Python

import hmac, hashlib, os

identifier_hash = hmac.new(
    os.environ['HELLOUONE_HMAC_TOKEN'].encode(),
    str(user.id).encode(),
    hashlib.sha256
).hexdigest()

PHP

$identifierHash = hash_hmac(
  'sha256',
  (string) $user->id,
  getenv('HELLOUONE_HMAC_TOKEN')
);

3. Pass the hash to the browser

Render the hash into the page along with the rest of the user payload, then hand it to $hellouOne.setUser after the SDK is ready.

<script>
  window.addEventListener('hellouone:ready', function () {
    window.$hellouOne.setUser('42', {
      name: 'Ada Lovelace',
      email: 'ada@example.com',
      avatar_url: 'https://example.com/ada.png',
      phone_number: '+15551234567',
      identifier_hash: '<%= identifier_hash %>'
    });
  });
</script>
Stringify the identifier

The hash on the server must be computed against the string form of the identifier. If you sign 42 as an integer in one place and pass "42" as a string elsewhere, the digests will not match and the call will be rejected.

Signing email and phone with identity_fields_hash

identifier_hash proves only the identifier. The email and phone number sent beside it are stored as the visitor’s own, unverified word: they never merge the visitor into another contact that already holds that email or phone, and AI agent connectors do not use them to look the customer up.

To have them count as verified, also send identity_fields_hash: the hex HMAC-SHA256, with the same HMAC token, of the identifier, the email and the phone number joined by newline characters. Use an empty string for a field you do not send, and sign the exact values you pass to setUser. When the hash is valid, the email and phone number count as verified and connectors use them as identity. Signed or not, an email or phone number that another contact already holds never merges the visitor into that contact: the value is dropped. Sign only an email or phone number your site has confirmed belongs to the user.

Node.js

const identityFieldsHash = crypto
  .createHmac('sha256', process.env.HELLOUONE_HMAC_TOKEN)
  .update([String(user.id), user.email || '', user.phone || ''].join('\n'))
  .digest('hex');

Ruby

identity_fields_hash = OpenSSL::HMAC.hexdigest(
  'sha256',
  ENV.fetch('HELLOUONE_HMAC_TOKEN'),
  [user.id, user.email, user.phone].map(&:to_s).join("\n")
)

Python

identity_fields_hash = hmac.new(
    os.environ['HELLOUONE_HMAC_TOKEN'].encode(),
    '\n'.join([str(user.id), user.email or '', user.phone or '']).encode(),
    hashlib.sha256
).hexdigest()

PHP

$identityFieldsHash = hash_hmac(
  'sha256',
  implode("\n", [(string) $user->id, $user->email ?? '', $user->phone ?? '']),
  getenv('HELLOUONE_HMAC_TOKEN')
);

Pass it next to identifier_hash. The parameter is optional.

window.$hellouOne.setUser('42', {
  email: 'ada@example.com',
  phone_number: '+15551234567',
  identifier_hash: '<%= identifier_hash %>',
  identity_fields_hash: '<%= identity_fields_hash %>'
});
Exact values, in this order

Sign the identifier, then the email, then the phone number, separated by one newline each, with the very strings the browser sends (same case, same spacing). If the hash is present but does not match, setUser is rejected with 401 HMAC failed: Invalid Identity Fields Hash Provided; the public inbox API contacts endpoints answer 401 with the same {"error": "HMAC failed: Invalid Identity Fields Hash Provided"} body.

Mandatory vs. optional mode

Each web widget can be configured in one of two modes:

Rotating the token

If the HMAC token leaks (e.g. it ended up in a client bundle by mistake), rotate it from the dashboard. Every previously-issued hash becomes invalid immediately, so re-deploy your backend with the new secret as part of the same change — otherwise live sessions will start failing.