Catching and tracking events

In the case of chatbots running on the WebMessenger platform, events occurring before, during, and at the end of a chatbot conversation can be caught and used for various purposes. Such typical purposes among others are debugging or tracking.

Setting up event catching

Events can be caught by adding handlers to them in the chatbot integration code snippet. Make sure that event handlers are added before calling JobPal.init.

To bind an event, use JobPal.on(<event name>, <handler>);. To unbind events, you can either call JobPal.off(<event name>, handler) to remove one specific handler, call JobPal.off(<event name>) to remove all handlers for an event, or call JobPal.off() to unbind all handlers.

Events to catch

ready

// This event triggers when init completes successfully.
JobPal.on('ready', function(){
    console.log('the init has completed!');
});

JobPal.init(...).then(function() {
    // init also returns a promise, so you can alternatively specify a .then() callback
});

destroy

// This event triggers when the widget is destroyed.
JobPal.on('destroy', function(){
    console.log('the widget is destroyed!');
});

message received

// This event triggers when the user receives a message
JobPal.on('message:received', function(message) {
    console.log('the user received a message', message);
});

message sent

// This event triggers when the user sends a message
JobPal.on('message:sent', function(message) {
    console.log('the user sent a message', message);
});

message

// This event triggers when a message was added to the conversation
JobPal.on('message', function(message) {
    console.log('a message was added to the conversation', message);
});

unreadCount change

// This event triggers when the number of unread messages changes
JobPal.on('unreadCount', function(unreadCount) {
    console.log('the number of unread messages was updated', unreadCount);
});

chatbot widget opened

// This event triggers when the chatbot widget is opened
JobPal.on('widget:opened', function() {
    console.log('Widget is opened!');
});

chatbot widget closed

// This event triggers when the chatbot widget is closed
JobPal.on('widget:closed', function() {
    console.log('Widget is closed!');
});

Tracking user user/chatbot interaction in Google Analytics

A typical use case of event handling is to track user actions in external tracking systems; for example, in Google Analytics.

The code snippet below will record a “MessageSent” event action in Google Analytics whenever an enduser sends a message to the chatbot:

// Google Analytics tracking of messages sent by endusers
JobPal.on('message:sent', function(message){
ga('send', 'event', 'Chatbot', 'MessageSent');
});

In this example, “Chatbot” is the event category, and “MessageSent” is the event action. Additionally you might add parameters for event label and event value. You can learn more about event measurement in Google Analytics here.

Please don’t forget to add these lines before invoking the JobPal.init function!

The setup above will allow you to compare behavioural differences (like conversion rates) in Google Analytics between endusers interacting with the chatbot, and endusers not using the chatbot.