Skip to main content

Sessions and Users

Appilots tracks two related but distinct things: the lifetime of a single conversation (a session), and, optionally, who the person having that conversation is (an end user).

Sessions​

Every conversation happens inside an agent session. Each session comes with a session token — a secret that's the only way to read or continue that conversation, so knowing a session id isn't enough to open it. The SDK client creates a session automatically around the chat's lifecycle — one session per open conversation — and ends it when the chat is cleared or unmounted. You don't need to manage sessions manually; opening <AppilotsChat/> starts one, and its messages, actions, and any escalation state live within that session for as long as the chat stays open.

Identifying end users​

By default, a session is anonymous — the agent knows it's talking to someone, but not who. If your app already knows its current user, you can tell Appilots via AppilotsConfig.user:

interface AppilotsUser {
  id: string;
  name?: string;
  identifiers?: Record<string, string>;
}
  • id — your app's own user id, used to match this person across sessions.
  • name — an optional display name.
  • identifiers — free-form lookup keys (e.g. email, phone), capped at 10 entries.

Setting user alone is a claim, not proof: the SDK key ships inside your app, so Appilots won't attribute conversations or write to your user registry based on it. To make the identity count, also configure getUserToken. It's a callback that fetches a short-lived token your backend issues after checking its own login session:

getUserToken: async () => {
  const res = await fetch("/your-backend/appilots-token", { credentials: "include" });
  return res.ok ? (await res.json()).token : null;
},

With both set, the SDK attaches the token to its requests, and the conversation is attributed to that user. It also sends a write-only "identify" upsert once per client, so the operator dashboard can show a real person in the support queue instead of an anonymous session id. Use the same id in user.id as in the token, otherwise requests return 403. If getUserToken returns null, the SDK doesn't send the request.

See Authentication → Verified end users for issuing the token, and API Reference: identify for the wire contract.

Privacy guarantee: user identifiers are never sent to the model.

Last updated on