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.
- Your backend reads the HMAC token from the dashboard once and stores it as a secret.
- When you render a page for a logged-in user, your backend computes
identifier_hash = HMAC-SHA256(identifier, hmacToken). - The hash is injected into the page and passed to
$hellouOne.setUser. - HellouOne re-computes the hash on its end and only accepts the identity if it matches.
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>
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 %>'
});
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:
- Optional —
setUserworks with or withoutidentifier_hash. When the hash is present and matches, the resulting contact is marked verified. - Mandatory —
setUseris rejected unlessidentifier_hashis present and matches. Use this when you have signed-in users and want to guarantee impersonation isn’t possible from the browser.
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.