Identify signed-in users

When your site tells the chat who’s signed in, their conversations go under their customer profile, with the data you send on it, and they skip the details form. Your server signs each user, so nobody can pretend to be someone else.

Owners and admins set it up on the Install page: under the snippet, choose Connect your web app. The install prompt for AI coding agents sets this up too.

Create your identity secret

There’s no secret until you make one. Choose Create secret: it’s shown once, so copy it then and keep it on your server, like a password; never put it in your site’s pages. After that only its last four characters show. Lost it, or it leaked? Make a new secret replaces it, and the old one stops working straight away.

Sign the user on your server

Make an HMAC-SHA256 of the user’s ID with the secret. If your users have no IDs, sign their email instead.


// Node.js
import crypto from "node:crypto";
 
const userHash = crypto
  .createHmac("sha256", process.env.UNCLENCH_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");


# Ruby
user_hash = OpenSSL::HMAC.hexdigest("SHA256", ENV["UNCLENCH_IDENTITY_SECRET"], user.id.to_s)


# Python
import hashlib, hmac, os
 
user_hash = hmac.new(os.environ["UNCLENCH_IDENTITY_SECRET"].encode(), str(user.id).encode(), hashlib.sha256).hexdigest()

Tell the chat who it is

On pages where the user is signed in, before the chat’s script tag:


<script>
  window.unclenchSettings = {
    user_id: "42",
    email: "[email protected]",
    name: "Ada Lovelace",
    user_hash: "<the hash from your server>",
    attributes: { plan: "pro", seats: 5 }
  };
</script>

On a single-page app, call Unclench.identify({ ... }) with the same fields once the user signs in.

What happens

The customer’s profile gets their name, email and the attributes you send: plain values like text, numbers and yes/no, up to 100 of them. Sending an attribute again replaces it.
Last seen updates on every page they open with the chat on it.
They skip the details form, and the chats they had on this device before signing in go under their profile.
Someone who chatted with their email before signing up keeps that history: the user ID is added to the customer with that email.

A call with no user_hash, or a wrong one, is ignored: the visitor just gets the usual chat. Check the hash is made from exactly the user_id you send (or the email, when there’s no ID).

Send what they do

Events show as a timeline on the customer’s profile:


Unclench.track("upgraded", { plan: "pro" });

Use a short name for what happened, and plain values for the details. Events only count for a user you’ve identified.