Identify your logged-in users with custom data

By default, Yaplet treats every browser session as an anonymous visitor. That means your team sees "Visitor 1234" instead of a real name, and the same customer starts a fresh conversation every time they log in. Calling Yaplet.identify() once per session fixes this: the widget shows the user's name, links all their past conversations, and lets you filter your inbox by plan, company, or any custom property you send.

Prerequisites

• The Yaplet snippet is already installed. If not, start with Install Yaplet with the JavaScript snippet.
• You have a server-side session that knows the current user's ID and email.
• You can run a few lines of code on your server — identifying a user requires a signature that can only be produced there.

1. Sign the user ID on your server

Anyone can open your website and talk to your chat widget, so a user ID on its own is only a claim — without proof, a stranger could send us one of your customers' IDs and your team would see them as that customer. To stop that, every identify() call has to carry a signature that only your server can produce. Calls without a valid one are rejected and the visitor stays anonymous.

Find your identity secret in the Yaplet dashboard under Brand → (your brand) → Chat widget → Install → Identity verification, and store it as an environment variable on your server.

The secret is hidden until you press Show identity secret, and there is a copy button next to it. There is also a Rotate secret action behind a confirmation — use it if the secret ever leaks, but understand what it does: the old secret stops working the instant you confirm, and every identify() call fails until your server is redeployed with the new one.

Then hash the user's ID with it. In Node.js:

import crypto from "crypto";

const userHash = crypto
  .createHmac("sha256", process.env.YAPLET_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");

Send userHash to your front end together with the user's profile — for example as one more field on whatever "current user" endpoint you already call.

Never put the identity secret in your website's code. Anything the browser can download, a visitor can read — and whoever has the secret can impersonate any of your users. It belongs on your server only.

2. Call identify()

Call Yaplet.identify() after your page loads and your user session is available. Pass the user's unique ID first, an object with their details second, and the signature from step 1 third:

Yaplet.identify("user-123", {
  name: "Jane Smith",
  email: "[email protected]",
  phone: "+1 555-0100",
  createdAt: new Date("2024-03-15"),
  plan: "pro",
  companyId: "acme-001",
  companyName: "Acme Corp",
}, userHash);

The user ID and the signature are both required, and the ID you pass must be exactly the string you hashed on the server. Everything in the middle object is optional — but the more you send, the more context your team has when a conversation comes in.

Standard fields

Field	Type	Description
name	string	Full name shown in the inbox and on the visitor profile.
email	string	Contact email. Enables email follow-ups after a chat.
phone	string	Phone number in E.164 format (e.g. +14155550100).
value	number	Lifetime value in your currency. Shown on the visitor sidebar.
companyId	string	Your internal company identifier for B2B filtering.
companyName	string	Company display name.
plan	string	Subscription plan name (e.g. "free", "pro", "enterprise").
sla	number	Target response time in hours for this user. Highlights SLA-sensitive conversations.
createdAt	Date	When the user signed up. Useful for cohort-based support rules.

Custom attributes

Any data that doesn't fit the standard fields goes into customData. These are free-form key-value pairs:

Yaplet.identify("user-123", {
  name: "Jane Smith",
  email: "[email protected]",
  customData: {
    subscriptionStatus: "trialing",
    trialEndsAt: "2026-06-15",
    accountRegion: "EU",
    featureFlags: "ai-phone,affiliate",
  },
}, userHash);

Custom attributes appear on the visitor sidebar in the inbox, and your team can filter conversations by them.

They also reach your AI. Anything you pass in customData becomes available to your API tools as custom_<key>, so the AI can pass a visitor's own account details to your systems while it answers. The limits: the first 50 keys are used, each value is trimmed to 512 characters, and nested objects and lists are skipped because they have no sensible single-line form in a web address or a header.

Where to call identify()

Call it as soon as your app knows who the current user is — typically right after your authentication check resolves. In a single-page app this is usually in your root component or auth store. In a server-rendered app you can inline it in the page response.

You can call Yaplet.identify() at any point after the snippet runs — even before the SDK has fully loaded. The snippet queues the call and replays it once the SDK is ready.

Logging out

When a user logs out of your app, clear their Yaplet identity so the next visitor doesn't inherit their conversation history:

Yaplet.clearIdentity();

Troubleshooting

If your users still show up as anonymous visitors, work through these four causes in order. It is also worth opening your browser console and checking for a Yaplet warning about identify() — when one is printed, it carries the server's own reason for refusing the call.

• No signature was sent. The third argument is missing, or the value your server returned was empty.
• The signature doesn't match the ID. Your server hashed something different from what the browser passed — a number on one side and a string on the other, an email instead of an ID, or extra whitespace.
• The wrong secret was used. The identity secret belongs to this widget, so a secret copied from anywhere else will never match.
• The secret was rotated and your server is still using the old one.

What's next

With identification in place, your team can see who they're talking to the moment a conversation comes in. Check that everything is working with Verify your installation.