Recognise signed-in customers
Four lines on your server, and a logged-in customer stops being a stranger.
Optional, and the single highest-value thing you can add after the widget itself. With it, a customer who is logged in to your site is recognised by the agent — their website chat, their WhatsApp messages and their history become one customer in your inbox.
Without it, every visitor is anonymous. That is the safe default, not a broken one.
Why a signature is required
Anyone can put anything in a POST body. If an unsigned user id were enough to bind somebody to stored history, a stranger could read another customer's conversations by guessing their user id.
So the claim is signed with a secret only your server and we hold, and we recompute it before acting on it. A claim that does not verify is dropped — never downgraded to "probably them".
The recipe
Your identity secret is on the agent's Channels page. Keep it on your server; it must never reach the browser.
import { createHmac } from "node:crypto";
const hmac = createHmac("sha256", process.env.IDENTITY_SECRET)
.update(String(user.id))
.digest("hex");
import hmac, hashlib, os
digest = hmac.new(
os.environ["IDENTITY_SECRET"].encode(),
str(user.id).encode(),
hashlib.sha256,
).hexdigest()
$hmac = hash_hmac('sha256', (string) $user->id, getenv('IDENTITY_SECRET'));
Then render it into the widget tag:
<script
src="https://app.katexs.com/widget.js"
data-key="pk_your_public_key"
data-user-id="42"
data-user-hmac="a3f1…"
data-user-email="[email protected]"
data-user-name="Priya"
data-user-phone="+919876543210"
async
></script>
If your site is a single-page app, call AgentWidget.identify({…}) after
sign-in instead.
Which fields do what
| Field | Signed | What it decides |
|---|---|---|
data-user-id | Yes | Which history the agent may read. This is the one that matters |
data-user-hmac | — | The signature over the id |
data-user-email | No | What your inbox calls them |
data-user-name | No | What your inbox calls them |
data-user-phone | Under the same signature | Joins their WhatsApp messages to the same customer |
Only the id is signed as an identity. Name and email are written to the record but never used to find one, so changing a display name does not mean re-signing anything.
Warning
The phone number is the field that makes WhatsApp join up, and it is exactly why the whole claim has to be signed. A phone number is trivially guessable, so an unsigned one would hand a stranger the matching WhatsApp history. Leave it out and everything else still works.
Per channel, not per workspace
The secret belongs to a channel. If you run a brochure site and a logged-in app, install two widgets with two secrets — a key lifted from the brochure site must not be able to assert identities against the app.
Common mistakes
Signing something other than the id
The digest must be of the user id alone. A digest of the secret itself is a constant and verifies nothing.
Computing the HMAC in the browser
That publishes the secret to every visitor, and the secret is the only thing stopping anyone forging any customer's identity.
Sending an id with no signature
It is treated as unverified and bound to nothing. The widget works; the customer stays anonymous, and it looks exactly like a working feature.
