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. 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.

When user is set, the SDK sends it once per client via a write-only "identify" upsert, so the operator dashboard can show a real person in the support queue instead of an anonymous session id. See API Reference: identify for the wire contract.

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

Related pages

• How it works — where sessions fit into a chat turn
• API Reference: identify — the identify request/response shape
• Dashboard: human escalation ops — where identified users show up for operators