Identify Users

By default, Beacon treats every visitor as anonymous. Calling identify upgrades the session to a known contact so Rian and your agents can see who they're talking to and reference past conversations.

Basic identity is unsigned. It identifies the contact visually in Beacon, but it should not be used as proof that the visitor owns that account. Use verified identity when Rian needs to safely use account or app tools such as Stripe.

When to call identify

Call it immediately after a user logs in — before they might open the widget.

Basic identity

Use basic identity when you only need to display the contact's name, email, phone, or your internal user ID.

Script tag

window.Beacon.identify({
  name: user.name,
  email: user.email,
  phone: user.phone,         // optional
  external_id: user.id       // your internal user ID — strongly recommended
});

React

Pass the identity prop to BeaconWidget:

<BeaconWidget
  workspaceId="YOUR_WORKSPACE_ID"
  identity={{
    name: user.name,
    email: user.email,
    external_id: user.id
  }}
/>

Or call it imperatively via the hook:

const beacon = useBeacon({ workspaceId: 'YOUR_WORKSPACE_ID' });
 
// After login:
beacon.identify({ name: user.name, email: user.email, external_id: user.id });

Angular

Pass identity to BeaconService.boot():

this.beacon.boot({
  workspaceId: 'YOUR_WORKSPACE_ID',
  identity: { name: user.name, email: user.email, external_id: user.id }
});

Verified identity

Use verified identity for logged-in users when Rian needs to act on account data or use app tools. Your backend must generate the signature and return it to your app after login or session refresh.

Generate an identity secret

1. Open Settings > Channels > Beacon > Security.
2. Enter a name for the secret, such as Production website or Mobile app.
3. Click Generate.
4. Copy the generated secret and store it in your backend environment as WIDGET_IDENTITY_SECRET.

You can create separate secrets for different sites, apps, or environments. If a secret is exposed, rotate it from the same Security tab and update your backend environment.

Never expose WIDGET_IDENTITY_SECRET in browser code.

window.Beacon.identify({
  name: user.name,
  email: user.email,
  phone: user.phone,
  external_id: user.id,
  identity_timestamp,
  identity_signature
});

Your backend signs this payload:

{workspace_id}.{external_id}.{email_or_empty}.{timestamp}

Use HMAC-SHA256 with WIDGET_IDENTITY_SECRET and return the hex digest:

{
  "identity_timestamp": 1710000000,
  "identity_signature": "hex_hmac_sha256_digest"
}

Signatures expire after 10 minutes. If identity_signature is provided, include identity_timestamp. If the signature is invalid, Beacon returns 400 Invalid widget identity signature.

On logout

Call shutdown() to clear the session so the next visitor starts fresh:

window.Beacon.shutdown();
// React hook: beacon.shutdown()

Identity fields

Field	Type	Notes
name	string	Display name shown to agents
email	string	Used to match existing contacts
phone	string	Optional
external_id	string	Your internal user ID; used to link conversations across sessions
identity_timestamp	number or string	Required when identity_signature is provided
identity_signature	string	Backend-generated HMAC-SHA256 hex digest