Widget API

All methods are available on window.Beacon (script tag) or via the useBeacon hook return value (React/Vue).

Beacon.boot(config)

Initialises and renders the widget. Called automatically when using data-workspace-id on the script tag.

Beacon.boot({ workspace_id: 'YOUR_WORKSPACE_ID' });

Parameter	Type	Required
workspace_id	string	Yes

---

Beacon.identify(identity)

Links the current session to a known contact.

Basic identity is unsigned and identifies the contact visually. Verified identity is required when Rian needs to safely use account or app tools such as Stripe.

Beacon.identify({
  name: '[name]',
  email: '[email]',
  phone: '[phone_number]',   // optional
  external_id: 'user_123'    // your internal user ID
});

Field	Type	Notes
name	string	Shown to agents
email	string	Used to match existing contacts
phone	string	Optional
external_id	string	Strongly recommended; links sessions across devices
identity_timestamp	number or string	Required with identity_signature
identity_signature	string	Backend-generated HMAC-SHA256 hex digest

Verified identity

Generate identity_timestamp and identity_signature on your backend. Never expose WIDGET_IDENTITY_SECRET in browser code.

First create a secret in Settings > Channels > Beacon > Security:

1. Enter a name like Production website.
2. Click Generate.
3. Copy the secret into your backend environment as WIDGET_IDENTITY_SECRET.
4. Rotate the secret from the Security tab if it is ever exposed.

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

The signed payload is:

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

The algorithm is HMAC-SHA256 with WIDGET_IDENTITY_SECRET, returned as a hex digest. Signatures expire after 10 minutes. If the signature is invalid, /widget/boot returns 400 Invalid widget identity signature.

---

Beacon.open()

Opens the widget panel.

Beacon.open();

---

Beacon.close()

Closes the widget panel.

Beacon.close();

---

Beacon.shutdown()

Removes the widget from the page. Call on logout.

Beacon.shutdown();

---

Beacon.on(event, callback)

Subscribe to widget lifecycle events.

Beacon.on('open', () => { /* widget opened */ });
Beacon.on('close', () => { /* widget closed */ });
Beacon.on('message:received', (msg) => { console.log(msg.content); });
Beacon.on('conversation:started', () => { /* first message sent */ });
Beacon.on('handoff', () => { /* escalated to human */ });

Event	Fired when
open	Widget panel is opened
close	Widget panel is closed
message:received	A new message arrives
conversation:started	Visitor sends their first message
handoff	Rian escalates to a human agent

---

TypeScript types

interface BeaconIdentity {
  name?: string;
  email?: string;
  phone?: string;
  external_id?: string;
  identity_timestamp?: number | string;
  identity_signature?: string;
}
 
interface BeaconConfig {
  workspaceId: string;
  identity?: BeaconIdentity;
  cdnUrl?: string;  // override CDN base URL
}