All pages

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

FieldSignedWhat it decides
data-user-idYesWhich history the agent may read. This is the one that matters
data-user-hmac—The signature over the id
data-user-emailNoWhat your inbox calls them
data-user-nameNoWhat your inbox calls them
data-user-phoneUnder the same signatureJoins 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.