Support Portal provides an HMAC-based identity validation mechanism that cryptographically verifies the identity of visitors interacting with the live chat widget. When enabled, this feature ensures that a visitor claiming to be a particular user has been authenticated by your backend systems — preventing impersonation, session hijacking, and unauthorized access to conversation history.
Operational objective
In any deployment where the live chat widget serves authenticated users — logged-in customers on a telecom self-service portal, citizens accessing a government digital service, employees using an internal operations dashboard — there is a risk that a malicious actor could forge a visitor identity and gain access to another user's conversation history or personal data. Identity validation eliminates this risk by requiring a server-generated cryptographic signature before the platform accepts a visitor's claimed identity.
This is particularly critical in regulated environments. A government portal handling citizen inquiries about tax records or permit applications must guarantee that conversation history is only accessible to the authenticated individual. A telecom operator exposing account details through live chat — billing information, service plans, device IMEI numbers — must prevent one subscriber from impersonating another. HMAC-based identity validation provides this guarantee at the protocol level, without relying on client-side trust alone.
How HMAC verification works
The verification process follows a challenge-response pattern involving three parties: your backend server, the visitor's browser, and the Support Portal platform.
Your server generates a signature. When an authenticated user loads a page containing the live chat widget, your backend computes an HMAC-SHA256 hash of the user's unique identifier (typically their email address) using a secret token that only your server and the Support Portal platform share.
The browser passes the signature to the widget. Your frontend code provides the user's identifier and the computed HMAC hash to the widget SDK via the window.$chatwoot.setUser method. The widget transmits both values to the platform.
The platform independently verifies the signature. Support Portal computes the same HMAC-SHA256 hash using its copy of the shared secret and the identifier received from the widget. If the hash matches the one provided by the browser, the visitor's identity is confirmed. If it does not match, the identity claim is rejected — the visitor is treated as unverified, and no prior conversation history is exposed.
Because the shared secret never leaves the server side, a client cannot forge a valid signature. Even if an attacker intercepts the identifier and hash for one user, they cannot generate a valid hash for a different user without access to the secret token.
Retrieving the HMAC token
Each website inbox has its own unique HMAC token. To retrieve it, navigate to Settings > Inboxes, select the relevant website inbox, and open the Configuration tab. The identity validation section displays the token used for HMAC generation.
Copy this token and store it securely in your backend configuration — environment variables or a secrets manager are appropriate storage mechanisms. This token must never be exposed in client-side code, embedded in JavaScript bundles, or committed to version control repositories. Treat it with the same sensitivity as an API secret key.
For deployments spanning multiple website inboxes — for example, a telecom operator with separate inboxes for consumer support, dealer support, and enterprise accounts — each inbox has a distinct HMAC token. Your backend must use the correct token for the inbox associated with each web property.
Generating the HMAC hash (server-side)
The HMAC hash must be computed on your server for each authenticated user session. The inputs are the user's unique identifier (the value you will pass as the identifier to the widget SDK) and the HMAC token retrieved from the inbox configuration. The output is a hexadecimal SHA-256 HMAC digest.
Below are reference implementations in commonly used server-side languages.
PHP
<?php
$key = '<webwidget-hmac-token>';
$message = '<identifier>';
$identifier_hash = hash_hmac('sha256', $message, $key);
?>
Node.js
const crypto = require("crypto");
const key = "<webwidget-hmac-token>";
const message = "<identifier>";
const hash = crypto.createHmac("sha256", key).update(message).digest("hex");
Ruby
require 'openssl'
key = '<webwidget-hmac-token>'
message = '<identifier>'
OpenSSL::HMAC.hexdigest('sha256', key, message)
Python
import hashlib
import hmac
secret = bytes('<webwidget-hmac-token>', 'utf-8')
message = bytes('<identifier>', 'utf-8')
hash = hmac.new(secret, message, hashlib.sha256)
hash.hexdigest()
Go
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
)
func main() {
secret := []byte("<webwidget-hmac-token>")
message := []byte("<identifier>")
hash := hmac.New(sha256.New, secret)
hash.Write(message)
hex.EncodeToString(hash.Sum(nil))
}
Elixir
key = '<webwidget-hmac-token>'
message = '<identifier>'
signature = :crypto.mac(:hmac, :sha256, key, message)
Base.encode16(signature, case: :lower)
In each example, replace <webwidget-hmac-token> with the token copied from the inbox configuration and <identifier> with the authenticated user's unique identifier — typically their email address.
Passing identity data to the widget SDK
Once your server has generated the HMAC hash, your frontend code must pass both the identifier and the hash to the live chat widget. This is done through the window.$chatwoot.setUser method, which accepts the user's identifier as the first argument and a data object containing the hash as the second.
window.$chatwoot.setUser("<identifier>", {
identifier_hash: "<hmac-hash-generated-server-side>",
name: "Jane Citizen",
email: "[email protected]",
});
The identifier_hash field is the critical security parameter — it carries the HMAC digest that the platform uses for verification. The name and email fields are optional metadata that populate the contact record within Support Portal.
A common implementation pattern is to render the HMAC hash into a data attribute or inline script variable during server-side page rendering, then reference it in the client-side widget initialization code. This keeps the secret token on the server while making the computed hash available to the browser.
When identity validation is active and a visitor's HMAC hash is successfully verified, the platform displays a verification indicator on the contact record. Agents can use this indicator to confirm that the visitor has been authenticated by the organization's backend systems before sharing sensitive information.
What happens when validation fails
If the HMAC hash provided by the browser does not match the hash computed by the platform — due to a mismatched token, an incorrect identifier, or a deliberate forgery attempt — the visitor's identity claim is rejected. The platform treats the visitor as an unauthenticated guest, and no prior conversation history associated with the claimed identifier is loaded.
This fail-closed behavior is deliberate. In security-sensitive deployments, it is preferable to deny access and require re-authentication rather than risk exposing another user's conversation records to an unverified party.
Governance and compliance considerations
Impersonation prevention in regulated channels. For government digital services, identity validation provides a verifiable chain of trust: the citizen authenticates through the government identity provider, the backend generates a cryptographic proof, and the support platform independently verifies it. This chain is auditable and does not rely on client-side assertions alone.
Telecom subscriber protection. Telecom operators using live chat for account management — SIM swaps, plan changes, billing inquiries — face regulatory requirements around subscriber identity verification. HMAC-based validation integrates naturally with existing authentication flows (SSO, two-factor authentication) and provides a defense-in-depth layer that operates independently of the primary session management system.
Data isolation assurance. In multi-tenant deployments where a single Support Portal workspace serves multiple user populations, identity validation ensures that conversation history is compartmentalized per verified identity. Combined with the per-inbox HMAC token model, this provides organizational assurance that cross-user data leakage through the live chat channel is structurally prevented.
For additional configuration of the live chat widget, including pre-chat forms, business hours, and visual customization, see Live Chat Widget Configuration. For SDK deployment options and parameter reference, see Sdk Setup.