NAV
javascript

JavaScript Events

At some point, you may need to hook your custom code into JavaScript events, or you may want to instruct Google Analytics to track certain events. In this article you will find all of SnapEngage's JavaScript Events, and a few example uses.

Close Event

SnapEngage.setCallback('Close', function (type, status) {
    console.log('type: ' + type);
    console.log('status: ' + status);
});

The Close event is fired when a close button is clicked.

This callback can return two pieces of info: type of window that was closed, and widget status when the close event was fired.

Parameter values

Parameter Type Description
Anonymous Function Function This callback function accepts two optional parameters: type and status. Inside the anonymous function, you can check the returned value of the type and status parameters.
type String The type of window that was closed (see table of values below).
status String The widget status when the close event was fired (see table of values below).

Return values of type parameter

SnapEngage.setCallback('Close', function (type, status) {
    console.log('A visitor just closed the ' + type + ' window.');
});

// The callback above returns this
// when the visitor closes a chat window
'A visitor just closed the chat window.'
Type Value Description
String 'form' The visitor closed a prechat or offline form.
String 'chat' The visitor closed a chat window.
String 'proactive' The visitor closed a proactive chat window.

Return values of status parameter

SnapEngage.setCallback('Close', function (type, status) {
    console.log('A visitor closed a ' + type +
     ' and the widget is ' + status + '.');
})

// The callback above returns this
// when the visitor closes a form
'A visitor closed a form and the widget is offline.'
Type Value Description
String 'online' The visitor closed a window when the widget was online.
String 'offline' The visitor closed a window when the widget
was offline.

ChatMessageReceived Event

SnapEngage.setCallback('ChatMessageReceived', function (agent, msg) {
    console.log('agent: ' + agent);
    console.log('msg: ' + msg);
});

The ChatMessageReceived event is fired when a message from the agent is received by the visitor.

This callback can return two pieces of info: name of the agent that sent the message, and the msg that was sent.

Parameter values

Parameter Type Description
Anonymous Function Function This callback function accepts two optional parameters: agent and message. Inside the anonymous function, you can check the returned value of the agent and message parameters.
agent String The agent alias.
msg String The message that was received by the visitor.

Return values

SnapEngage.setCallback('ChatMessageReceived', function (agent, msg) {
    console.log('A visitor received a chat message from ' + agent);
    console.log('And the msg was: ' + msg);
});

// The callback above returns this
// when the visitor receives a chat message
'A visitor received a chat message from Samantha';
'And the msg was: hello ';

Example return values of agent and msg are inside the code example.

ChatMessageSent Event

SnapEngage.setCallback('ChatMessageSent', function (msg) {
    console.log('msg: ' + msg);
});

The ChatMessageSent event is fired when the visitor submits a chat message while in the chat session.

This callback can return one piece of info: the msg that was sent by the visitor.

Parameter values

Parameter Type Description
Anonymous Function Function This callback function accepts one optional parameter: msg. Inside the anonymous function, you can check the returned value of the msg parameter.
msg String The message that was sent by the visitor.

Return values

SnapEngage.setCallback('ChatMessageSent', function (msg) {
    console.log('A visitor sent this chat message: ' + msg);
});

// The callback above returns this
// when a visitor sends a chat message
'A visitor sent this chat message: What does SnapEngage integrate with?';

An example return value of msg is inside the code example.

MessageSubmit Event

SnapEngage.setCallback('MessageSubmit', function (email, msg) {
    console.log('email: ' + email);
    console.log('msg: ' + msg);
});

The MessageSubmit event is fired when the visitor submits an offline message (not a chat message).

This callback can return two pieces of info: the visitor's email, and the msg that was sent.

Parameter values

Parameter Type Description
Anonymous Function Function This callback function accepts two optional parameters: email and msg. Inside the anonymous function, you can check the returned value of the email and msg parameters.
email String The visitor's email address.
msg String The message.

Return values

SnapEngage.setCallback('MessageSubmit', function (email, msg) {
    console.log(email + ' just submitted an offline message.');
    console.log('The message was: ' + msg);
});

// The callback above returns this
// when an offline message is submitted
'[email protected] just submitted an offline message.'
'The message was: hello!';

Example return values of email and msg are inside the code example.

Minimize Event

NOTE: This API is only available for Design Studio widgets. Please consider upgrading to get the most current functionality.

SnapEngage.setCallback('Minimize', function(isMinimized, chatType, boxType) {
    // Handle results.
    console.log('Chatbox is' + (isMinimized ? '' : ' not') + ' minimized');
    console.log('Chat Type is: ' + chatType);
    console.log('Chat Box is: ' + boxType);
});

The Minimize event is triggered when the visitor clicks the minimize icon in the chat box, or during live and active chats when they click on the minimized 'button' to maximize the chat box.

Parameter values

Parameter Type Description
Anonymous Function Function This callback function accepts three optional parameters: isMinimized, chatType and boxType. Inside the anonymous function, you can handle the returned values of isMinimized, chatType and boxType arguments.
isMinimized Boolean The state of the chat box AFTER the visitor has clicked.
chatType String The type of chat the visitor is using.
boxType String The type of the chat box the visitor sees.

Return values of isMinimized parameter

SnapEngage.setCallback('Minimize', function(isMinimized, chatType, boxType) {
    // Handle results.
    console.log('Chatbox is' + (isMinimized ? '' : ' not') + ' minimized');
    console.log('Chat Type is: ' + chatType);
    console.log('Chat Box is: ' + boxType);
});

// The callback above returns this
// when a visitor has minimized a manual live chat:
'Chatbox is minimized'
'Chat Type is manual'
'Chat Box is chatManual'
Type Value Description
Boolean true The chat box is minimized.
Boolean false The chat box is not minimized (maximized).

Return values of chatType parameter

Type Value Description
String 'manual' The visitor started a manual chat.
String 'proactive' The visitor started a proactive chat.

Return values of boxType parameter

Type Value Description
String 'chatManual' The box is an ongoing live chat box initiated by the vistitor.
String 'intelliPrechat' The box is a Intelligent Prechat form
String 'offline' The box is an Offline form
String 'prechat' The box is a Prechat form
String 'proactive' The box is an ongoing live chat box initiated by the proactive rules.
String 'proactiveInvite' The box is displaying the proactive invite, awaiting response by the visitor

Open Event

SnapEngage.setCallback('Open', function (status) {
    console.log('status: ' + status);
});

The Open event is fired when the chat form is opened. The form may be opened by the user directly (button click), or as the result of an API call.

This callback can return one piece of info: the widget status when the event was fired.

Parameter values

Parameter Type Description
Anonymous Function Function This callback function accepts an optional parameter: status. Inside the anonymous function, you can check the returned value of the status parameters.
status String The widget status at the time the event was fired.

Return values of status parameter

SnapEngage.setCallback('Open', function (status) {
    console.log('A form just opened and the widget status is: ' + status);
});

// The callback above returns this
// when a form is opened and the widget is offline
'A form just opened and the widget status is: offline'
Type Value Description
String 'online' The widget is online.
String 'offline' The widget is offline.

OpenProactive Event

SnapEngage.setCallback('OpenProactive', function (agent, msg) {
    console.log('agent: ' + agent);
    console.log('msg: ' + msg);
});

The OpenProactive event is fired when the proactive chat is displayed to a visitor. (Note, when the visitor replies, the StartChat event fires.)

This callback can return two pieces of info: the name of the agent used in the proactive message, and the proactive msg itself.

Parameter values

Parameter Type Description
Anonymous Function Function This callback function accepts two optional parameters: agent and msg. Inside the anonymous function, you can check the returned value of the agent and msg parameters.
agent String The agent alias.
msg String The proactive prompt message.

Return values

SnapEngage.setCallback('OpenProactive', function (agent, msg) {
    console.log('A proactive message just popped up. The agent shown is ' +
     agent + '.');
    console.log('The proactive message used is: ' + msg);
});

// The callback above returns this
// when a proactive prompt opens
'A proactive message just popped up. The agent shown is Samantha.';
'The proactive message used is: You know nothing, Jon Snow.';

Example return values of agent and msg are inside the code example.

StartChat Event

SnapEngage.setCallback('StartChat', function (email, msg, type) {
    console.log('email: ' + email);
    console.log('msg: ' + msg);
    console.log('type: ' + type);
});

The StartChat event is fired when the visitor starts a chat, or responds to a proactive invitation.

This callback can return three pieces of info: the visitor's email, the visitor's first msg, and the type of chat (manual or proactive).

Parameter values

Parameter Type Description
Anonymous Function Function This callback function accepts three optional parameters: email, msg, and type. Inside the anonymous function, you can check the returned value of the email, msg, and type parameters.
email String The visitor's email address.
msg String The visitor's first message.
type String The type of chat.

Return values

SnapEngage.setCallback('StartChat', function (email, msg, type) {
    console.log(email + ' just started a ' + type + ' chat.');
    console.log('The message was: ' + msg);

});

// The callback above returns this
// when the visitor starts a manual chat
'[email protected] just started a manual chat.';
'The message was: The King in the North!';

Example return values of email, msg, and type are inside the code example.

Return values of type parameter

Type Value Description
String 'manual' The visitor started a manual chat.
String 'proactive' The visitor started a proactive chat.

StartCallme Event

SnapEngage.setCallback('StartCallme', function (phone) {
    console.log('phone: ' + phone);
});

The StartCallMe event is fired when the visitor starts a call-me.

This callback can return one piece of info: the visitor's phone number.

Parameter values

Parameter Type Description
Anonymous Function Function This callback function accepts one optional parameter: phone. Inside the anonymous function, you can check the returned value of the phone parameters.
phone String The visitor's phone number.

Return values

SnapEngage.setCallback('StartCallMe', function (phone) {
    console.log('A visitor just started a callme request.');
    console.log('Their phone number is ' + phone);
});

// The callback above returns this
// when the visitor starts a callme request
'A visitor just started a callme request.'
'Their phone number is 555-1234';

Example return values of phone are inside the code example.

SwitchWidget Event

NOTE: This API is only available for Design Studio widgets. Please consider upgrading to get the most current functionality.

SnapEngage.setCallback('SwitchWidget', function(newWidgetId) {
    // Handle results.
    console.log('I just switched to widget ID: ' + newWidgetId);
});

You must have the widget selector enabled in your Design Studio prechat &/or offline form to utilize this event callback functionality. The switchWidget event is triggered when the visitor has selected a value from the available dropdown list options. It will return the value of the newWidgetId.

Parameter values

Parameter Type Description
Anonymous Function Function This callback function accepts one optional parameter: newWidgetId. Inside the anonymous function, you can handle the returned value of the newWidgetId argument.
newWidgetId String The widgetId of the selected option.

Return values of newWidgetId parameter

SnapEngage.setCallback('SwitchWidget', function(newWidgetId) {
    // Handle results.
    console.log('I just switched to widget ID: ' + newWidgetId);
});

// The callback above returns this
// when a visitor has selected an option:
'I just switched to widget ID: 123-abc'

Button Event

The InlineButtonClicked event is fired when the visitor clicks on messages that are buttons.

SnapEngage.setCallback('InlineButtonClicked', function(options) {
    console.log('A visitor clicked on a bot button sent from ' + options.botName);
    console.log('And the button label was: ' + options.buttonLabel);
    console.log('And the button value was: ' + options.buttonValue);
});

Parameter values

Parameter Type Description
options object Object containing information about the button that got clicked

Options object

Property name Type Description
botName string Bot name (alias) that sent button message
buttonLabel string Label of the button
buttonValue string Value of the button

ChatEnded Event

The ChatEnded event fires when the chat ends. If your widget has chat survey enabled or any other post chat feature, this event is fired at the same time the post chat flow starts.

SnapEngage.setCallback(SnapEngage.callbacks.CHAT_ENDED, function(options) {
    console.log('Who has ended the chat?');
    console.log(options.endedByUser ? "Visitor" : "Agent or the System");
});

Parameter values

Parameter Type Description
options object An object containing options

Options object

Property Type Description
endedByUser boolean Whether the user has ended the chat or not

Rating Prompt Clicked Event

SnapEngage.setCallback('RatingPromptClicked', function (botAlias, scaleType, selectedOption) {
    console.log('botAlias: ' + botAlias);
    console.log('scaleType: ' + scaleType);
    console.log('selectedOption: ' + selectedOption);
});

The RatingPromptClicked event is fired when the rating prompt is clicked on the visitor side.

This callback can return three pieces of info: botAlias of agent the visitor is interacting with, the scaleType of the rating, and the selectedOption as a number.

Parameter values

Parameter Type Description
Function Function This callback function accepts two optional parameters: botAlias, scaleType, and selectedOption. Inside the anonymous function, you can check the returned value of the botAlias, scaleType, and selectedOption parameters.
botAlias String The agent alias the visitor is interacting with.
scaleType String The scale type, NUMBER or STAR.
selectedOption Number The rate selected by the visitor.