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.

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

---

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;
}
 
interface BeaconConfig {
  workspaceId: string;
  identity?: BeaconIdentity;
  cdnUrl?: string;  // override CDN base URL
}