Recognise signed-in customers

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.THINNEST_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");

import hmac, hashlib, os

digest = hmac.new(
    os.environ["THINNEST_IDENTITY_SECRET"].encode(),
    str(user.id).encode(),
    hashlib.sha256,
).hexdigest()

$hmac = hash_hmac('sha256', (string) $user->id, getenv('THINNEST_IDENTITY_SECRET'));

Then render it into the widget tag:

<script
  src="https://thinnest.ai/widget.js"
  data-key="pk_your_public_key"
  data-user-id="42"
  data-user-hmac="a3f1…"
  data-user-email="priya@example.com"
  data-user-name="Priya"
  data-user-phone="+919876543210"
  async
></script>

If your site is a single-page app, call ThinnestAgents.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.

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.

Getting started

Your agent

Channels

Put it on your site

Reaching out

Meta's rules

Working the conversations

Recognise signed-in customers

Why a signature is required

The recipe

Which fields do what

Per channel, not per workspace

Common mistakes

​Why a signature is required

​The recipe

​Which fields do what

​Per channel, not per workspace

​Common mistakes

Why a signature is required

The recipe

Which fields do what

Per channel, not per workspace

Common mistakes