Widget API

All methods are available on window.Beacon (script tag) or via the useBeacon hook return value (React/Vue). Methods called before boot() complete are silently queued and executed once the widget is ready.

---

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'
});

// Hide the default floating launcher button
Beacon.boot({
  workspace_id: 'YOUR_WORKSPACE_ID',
  hide_default_launcher: true
});

Parameter	Type	Required	Description
workspace_id	string	Yes	Your Renprofile workspace ID
hide_default_launcher	boolean	No	When true, the floating launcher button is not rendered. The messenger panel loads silently in the background, ready to open via Beacon.open(). Default: false.

The data-hide-launcher attribute is the script-tag equivalent:

<script
  src="https://cdn.renprofile.me/widget/loader.js"
  data-workspace-id="YOUR_WORKSPACE_ID"
  data-hide-launcher="true"
  async
></script>

---

Beacon.identify(identity)

Links the current session to a known contact. Call after login, before the visitor opens the widget.

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

For verified identity, include identity_timestamp and identity_signature generated on your backend:

Beacon.identify({
  name: user.name,
  email: user.email,
  phone: user.phone,
  external_id: user.id,
  identity_timestamp,         // Unix timestamp, expires after 10 min
  identity_signature          // HMAC-SHA256 hex digest, generated server-side
});

Field	Type	Notes
name	string	Shown to agents in the inbox
email	string	Used to match and merge existing contacts
phone	string	Optional
external_id	string	Strongly recommended; links conversations to your own user record
identity_timestamp	number or string	Required when identity_signature is provided
identity_signature	string	Backend-generated HMAC-SHA256 hex digest. Never generate this in the browser.

See Identify Users for the full guide on basic vs verified identity.

---

Beacon.shutdown()

Removes the widget from the page and clears the session. Call on logout.

Beacon.shutdown();

After shutdown(), call Beacon.boot() again to re-initialise.

---

Beacon.open()

Opens the widget panel.

Beacon.open();

---

Beacon.show()

Alias for Beacon.open().

Beacon.show();

---

Beacon.close()

Closes the widget panel without removing it from the page.

Beacon.close();

---

Beacon.hide()

Alias for Beacon.close().

Beacon.hide();

---

Beacon.showNewMessage(text?)

Opens the widget and focuses the message composer. Optionally pre-populates the composer with a string the visitor can edit before sending.

// Open with an empty composer
Beacon.showNewMessage();
 
// Open with pre-filled text
Beacon.showNewMessage('I have a question about my invoice');

Parameter	Type	Required	Description
text	string	No	Text to pre-populate in the message composer

---

Beacon.startConversation(message)

Opens the widget and immediately sends message as the visitor's first message. Unlike showNewMessage, no visitor input is required — the message is sent automatically.

Beacon.startConversation('My payment failed at checkout');

Parameter	Type	Required	Description
message	string	Yes	The message to send immediately

---

Beacon.showSpace(space)

Opens the widget directly to a specific tab.

Beacon.showSpace('home');      // Home screen
Beacon.showSpace('messages');  // Conversation list
Beacon.showSpace('articles');  // Help articles

Value	Opens to
'home'	Home screen
'messages'	Conversation list
'articles'	Help articles search

---

Beacon.toggleLauncher(visible)

Shows or hides the default floating launcher button at runtime, without affecting the messenger panel.

Beacon.toggleLauncher(false);  // Hide the launcher
Beacon.toggleLauncher(true);   // Show the launcher

Parameter	Type	Description
visible	boolean	true shows the launcher, false hides it

---

Beacon.onShow(callback)

Registers a callback that fires when the widget panel opens. Multiple callbacks can be registered.

Beacon.onShow(function () {
  analytics.track('Beacon Opened');
});

---

Beacon.onHide(callback)

Registers a callback that fires when the widget panel closes. Multiple callbacks can be registered.

Beacon.onHide(function () {
  analytics.track('Beacon Closed');
});

---

Beacon.onUnreadCountChange(callback)

Registers a callback that fires with the current unread count immediately on registration, and again whenever it changes.

Beacon.onUnreadCountChange(function (count) {
  var badge = document.getElementById('badge');
  badge.textContent = count;
  badge.style.display = count > 0 ? 'inline' : 'none';
});

Callback argument	Type	Description
count	number	Current number of unread messages

---

Beacon.onNewMessage(callback)

Registers a callback that fires when a new message arrives from an agent or Rian. The callback receives the message object.

Beacon.onNewMessage(function (message) {
  console.log('New message:', message.content);
});

Callback argument	Type	Description
message	object	The incoming message. message.content contains the text.

---

Beacon.getUnreadCount()

Returns the current unread count as a number. Use for a one-off read rather than subscribing to changes.

var count = Beacon.getUnreadCount();

---

TypeScript types

interface BeaconBootConfig {
  workspace_id: string;
  hide_default_launcher?: boolean;
}
 
interface BeaconIdentity {
  name?: string;
  email?: string;
  phone?: string;
  external_id?: string;
  identity_timestamp?: number | string;
  identity_signature?: string;
}
 
type BeaconSpace = 'home' | 'messages' | 'articles';
 
interface BeaconMessage {
  content?: string;
  [key: string]: unknown;
}
 
interface BeaconAPI {
  boot(config: BeaconBootConfig): void;
  identify(identity: BeaconIdentity): void;
  shutdown(): void;
 
  open(): void;
  show(): void;
  close(): void;
  hide(): void;
 
  showNewMessage(text?: string): void;
  startConversation(message: string): void;
  showSpace(space: BeaconSpace): void;
  toggleLauncher(visible: boolean): void;
 
  onShow(callback: () => void): void;
  onHide(callback: () => void): void;
  onUnreadCountChange(callback: (count: number) => void): void;
  onNewMessage(callback: (message: BeaconMessage) => void): void;
 
  getUnreadCount(): number;
}
 
declare global {
  interface Window {
    Beacon: BeaconAPI;
  }
}