Identity and sessions

How the SDK identifies a visitor, what it stores on the device, and how the email gate works.

Visitor id

Every device gets a visitor id the first time the SDK runs. It is the only thing the SDK persists, and it is what ties a conversation to a device across launches. The web embed does the same in localStorage.

Pass a storage adapter to keep it:

<SupportProvider storage={AsyncStorage} … />

Anything with getItem(key) and setItem(key, value) returning promises works: AsyncStorage, MMKV behind a small wrapper, or SecureStore. Without one the id lives in memory and each launch is a new visitor.

The session token is deliberately never persisted. The server replaces a visitor's token on every session call, so a stored token paired with a lost visitor id would collide server-side. A fresh token is minted on every launch; continuity comes from the visitor id.

Identity

identity on the provider tells the workspace who the visitor is. Every field is optional:

Field	Where it goes
`email`	Creates or links a contact when the session opens, with source "chat widget"
`name`	Contact name, and the sender name on messages
`company`	Creates or links an account
`phone`	Stored on the session
`userId`	Your app's own user id. Stored on the session and used to match sessions across devices
`customerId`, `avatarUrl`	Stored on the session as custom data

<SupportProvider
  identity={user ? { email: user.email, name: user.name, userId: user.id } : undefined}
  …
/>

Change the prop when the user logs in or out. The SDK re-identifies the existing session without reconnecting; you do not need to remount the provider.

To identify from inside the tree, for example after your own form, use identify from useSupport():

const { identify } = useSupport();
await identify({ email, name });

It merges with what is already known and keeps the same session token.

The email gate

If the widget has Require email on under Customer Support → Support Hub, visitors must give an email before they can chat. On the web the widget shows a small form; in the SDK:

needsEmail from useSupportConfig() is true until an email is known, whether from the identity prop or a later identify() call.
SupportChatScreen renders a form for it and calls identify() when submitted.
If you build your own screen, gate sending on needsEmail and call identify({ email }) from your form.

Once identified, the gate closes for the rest of the session and for later launches on the same device as long as your app passes the email again.

One visitor, several devices

Sessions are matched by visitor id, widget, and userId. Two devices with the same userId share conversations, and the most recent one to open a session holds the live token. The other device keeps working until its next launch, when it mints a new token of its own.

What the workspace sees

Opening a session with an email creates a contact (and an account when a company is given) before the visitor sends anything, the same as the Support Hub on the web. Conversations, messages, escalations and attachments then attach to that contact. Sandbox mode is decided by the widget, not the client; the SDK never sends a sandbox header.