Skip to main content
Use this page when you need to decide who the widget should treat as the same person, and how much trust to place in the identity data you pass in.
If your goal is to get the widget on the page first, start with Install Widget.
Want to see how identity settings look on screen? The Playground lets you toggle visitor data collection and other options live, then copy the matching snippet.

​
Start With The Right Identity Model

Lowest friction. Best for public support chat where history stays tied to the same browser.
Best when you want name, email, or lightweight personalization without server-issued identity.
Best when signed-in customers should keep history across devices and you need stronger protection against impersonation.

​
What Changes Between Non-Verified And Verified

Verified customers can keep history across devices. Anonymous and non-verified visitors should be treated as browser-bound or device-bound experiences.
and help you personalize the chat, but they do not prove identity. is the strong identity path.
Browser-provided custom data is useful, but should be treated with caution. Server-authenticated custom data is the safer choice when it affects support decisions.

​
Two Tokens, Two Jobs

Do not confuse these tokens:

Widget token

This token loads your organization’s widget. Get it from the widget setup flow, then use it when you install the widget.

Authenticated contact token

This token identifies a verified customer. Your backend requests it, then passes it to user.token.

​
Implementation Paths

1

Choose this path for public visitors

Use this when visitors are not signed in and you want the widget to ask for basic details before chat begins.
2

Turn on built-in collection

Add collectUserData: true to the widget options.
const options = {
  token: '<WIDGET_TOKEN>',
  collectUserData: true,
};
3

Test the welcome flow

Confirm the widget asks for the visitor’s name and email before they enter the chat.
This creates a non-verified identity. It improves context for your team, but it should not be treated as strong proof that the visitor owns that email address.

​
Extra Identity Controls

​
Scope History With externalId

Use when the same person can belong to multiple accounts, workspaces, or tenants inside your product. 
const options = {
  token: '<WIDGET_TOKEN>',
  user: {
    token: authenticatedContactToken,
    externalId: currentWorkspaceId,
  },
};
This keeps history aligned to the right account context instead of treating every conversation for that email address as one shared history.

​
Prefill Or Collect More Fields

name and email are the visitor details the widget can show or collect. fills those fields before the visitor types, while adds more fields to the collection form. If you are using the widget’s built-in data collection flow, you can:
  • prefill name and email with prefillUserData
  • collect additional fields with extraDataCollectionFields
These are good onboarding improvements for public support flows, but they do not replace verified identity.

​
API Notes For Server-Side Authentication

The widget authentication API is designed for your backend:

1. Call the endpoint

Call POST /widget/authenticate-user from your backend.

2. Use the right API key

Authenticate with an org API key that has .

3. Return or store the token

Store the contact token in your app flow or return it to the frontend.

4. Pass it to user.token

Give the widget the verified token through user.token.

Widget Authentication API

Open the full API contract, request example, and response shape for authenticated contact tokens.

​
If Your AI Actions Need Request Data

, , and do not identify the visitor. They add request data to the HTTP calls your AI actions make to your own APIs.
Use widget authentication to decide who the visitor is. Use action request fields to decide what your AI action sends to your API. If you need help with that second part, see Authentication.

Install Widget

Load the widget with HTML, React, or headless setup.

Configuration

Prefill data, prompts, routing, and advanced widget behavior.

Conversation Sessions

See how identity choices change history and continuity.

Widget Authentication API

Request and inspect verified contact tokens.