Browse docs

Guides

Developers

Events & openChat()

Subscribe to widget events with on(), and open the chat programmatically.

The widget emits a small set of events you can hook into from your own JavaScript, plus a method to open the chat panel programmatically. Use NudgeVisor.on() to react to the widget booting, to single-page navigations, and to chat activity, and use NudgeVisor.openChat() to launch the chat from your own buttons or links.

on(event, callback)

Subscribe to a widget event. The callback is invoked with the event's payload each time the event fires.

on(event, callback)

A few things worth knowing about how it behaves:

  • You can register multiple callbacks for the same event — they are all called, in the order you registered them.
  • A callback that throws never breaks the widget. The error is contained and the remaining callbacks still run.
  • It is safe to call on() immediately after the install snippet — see Calling early & the command queue below.

Events

These are the events the widget emits and the payload each callback receives.

Event Payload Fires when
ready { visitorId } Once the widget has booted. Fires a single time per page load.
pageChange { url } On SPA / history navigation — when your app calls pushState or replaceState.
message message A chat message is received. The payload is the message object itself.
chatStarted { conversationId } A chat conversation starts.

Examples

Reacting to ready

The ready event hands you the visitor's ID once the widget has finished booting.

NudgeVisor.on('ready', function (data) {
  console.log('NudgeVisor ready for visitor', data.visitorId);
});

Tracking navigation in a single-page app

If your app is a SPA, pageChange fires whenever the URL changes via the History API, so you can keep your own analytics in step with the widget.

NudgeVisor.on('pageChange', function (data) {
  console.log('Visitor navigated to', data.url);
});

Following chat activity

Listen for chatStarted to know when a conversation begins, and message for each incoming message.

NudgeVisor.on('chatStarted', function (data) {
  console.log('Conversation started:', data.conversationId);
});

NudgeVisor.on('message', function (message) {
  console.log('New chat message', message);
});

openChat()

Opens the chat panel programmatically. It takes no arguments — call it from a click handler to launch chat from your own help button, link or menu item.

// Wire a custom button to open the chat
document.querySelector('#help').addEventListener('click', function () {
  NudgeVisor.openChat();
});

Conversations opened this way land in your live chat inbox alongside every other conversation.

Calling early & the command queue

You do not need to wait for the widget to load before calling on() or openChat(). The loader stub installed by the snippet queues your calls and replays them once the widget is ready, so it is safe to register listeners and wire up buttons immediately. See the install snippet for details on how the queue works.

Related