Event Callbacks

Beacon fires callbacks when the widget opens, closes, receives a new message, or the unread count changes. Register callbacks with the dedicated methods below to drive your own UI — analytics events, custom badges, browser notifications, or anything else.

Callbacks are registered on window.Beacon and work regardless of how the widget was installed.

Beacon.onShow(callback)

Fires when the widget panel opens.

Beacon.onShow(function () {
  console.log('Widget opened');
});

Multiple callbacks can be registered and all will fire:

Beacon.onShow(function () {
  analytics.track('Beacon Opened');
});
 
Beacon.onShow(function () {
  document.getElementById('help-badge').style.display = 'none';
});

Beacon.onHide(callback)

Fires when the widget panel closes.

Beacon.onHide(function () {
  console.log('Widget closed');
});

Beacon.onUnreadCountChange(callback)

Fires immediately when registered with the current unread count, and again whenever the count changes. Use this to drive a custom unread badge anywhere in your UI.

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

Because the callback fires immediately on registration, you don't need to manually call Beacon.getUnreadCount() to initialise your badge — just register the callback and it handles the initial state for you.

Beacon.onNewMessage(callback)

Fires when a new message arrives from an agent or Rian while the widget is closed. The callback receives the message object.

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

Use this for browser notifications or in-app toasts:

Beacon.onNewMessage(function (message) {
  if (Notification.permission === 'granted') {
    new Notification('New message from Support', {
      body: message.content
    });
  }
});

Beacon.getUnreadCount()

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

var count = Beacon.getUnreadCount();
console.log('Unread:', count);

Example: analytics integration

Beacon.boot({ workspace_id: 'YOUR_WORKSPACE_ID' });
 
Beacon.onShow(function () {
  analytics.track('Support Widget Opened');
});
 
Beacon.onHide(function () {
  analytics.track('Support Widget Closed');
});
 
Beacon.onNewMessage(function (message) {
  analytics.track('Support Message Received');
});

Example: custom badge in a nav bar

<nav>
  <button id="help-nav-btn">
    Help
    <span id="nav-badge"></span>
  </button>
</nav>
 
<script>
  Beacon.boot({
    workspace_id: 'YOUR_WORKSPACE_ID',
    hide_default_launcher: true
  });
 
  Beacon.onUnreadCountChange(function (count) {
    var badge = document.getElementById('nav-badge');
    badge.textContent = count > 9 ? '9+' : count;
    badge.style.display = count > 0 ? 'inline-flex' : 'none';
  });
 
  document.getElementById('help-nav-btn').addEventListener('click', function () {
    Beacon.open();
  });
</script>

Example: browser notifications for new messages

// Request permission once (e.g. after login)
if (Notification.permission === 'default') {
  Notification.requestPermission();
}
 
Beacon.onNewMessage(function (message) {
  // Only notify when the page is not focused or the widget is closed
  if (document.hidden && Notification.permission === 'granted') {
    new Notification('New reply from Support', {
      body: message.content ? message.content.substring(0, 80) : 'You have a new message',
      icon: '/favicon.ico'
    });
  }
});

Example: close the widget when navigating in a SPA

// In your router's navigation handler
router.beforeEach(function (to, from) {
  Beacon.close();
});

Callback behaviour

• All callback methods (onShow, onHide, onUnreadCountChange, onNewMessage) can be called multiple times. Each call registers an additional callback; existing ones are not replaced.
• onUnreadCountChange fires immediately with the current value at the time of registration.
• Callbacks are not automatically removed. If you need to stop reacting to an event, manage that with a flag in your own code.
• Callbacks that throw an error are caught silently so they don't break other registered callbacks.