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. |
| 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. |
| 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. |