JavaScript API

The JavaScript API offers many different methods which you can use to customize the live chat look and functionality for your visitors. These methods may be used inside the SnapEngage code snippet where it says /* Place your SnapEngage JS API code below */ which will cause the API method to run after the SnapEngage code is fully loaded. In some cases, some API methods may be used as an event handler on an element on the page. For example, you can set a link's onclick attribute to SnapEngage.startLink() which will open up the chat if someone clicks that link.

Authentication for JavaScript API

An authentication key is not needed to use the Javascript API.

Just be sure to place your function calls inside your SnapEngage code snippet where it says "Place your SnapEngage JS API code below"

API Placement and Availability

Since the SnapEngage code snippet loads asynchronously, there are certain limitations on when you can use, and/or have access to our Javascript API.

Unlike a non-asynchronous include, you cannot be sure that the SnapEngage functions will be available when the document is otherwise ready.

Use our API inside the SnapEngage JavaScript Code Snippet

<!-- begin SnapEngage code -->
<script type="text/javascript">
  (function() {
    var se = document.createElement('script'); se.type = 'text/javascript'; se.async = true;
    se.src = '//storage.googleapis.com/code.snapengage.com/js/...';
    var done = false;
    se.onload = se.onreadystatechange = function() {
      if (!done&&(!this.readyState||this.readyState==='loaded'||this.readyState==='complete')) {
        done = true;
        /* Place your SnapEngage JS API code below */
        /* Example JS API: Enable sounds for Visitors. */
        var allow = true;
        SnapEngage.allowChatSound(allow);
      }
    };
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(se, s);
  })();
</script>
<!-- end SnapEngage code -->

This code snippet has a built in safety net, so to speak, for our Javascript API availability. As long as you place all of your custom Javascript API inside this code block, you can be sure that SnapEngage functions will be available. Be sure to place your function calls after the comment /* Place your SnapEngage JS API code below */.

We recommend that you call API exclusively inside this block. But if you insist on going all cowboy on us...

Using it elsewhere can be tricky

Our chat code is well optimized and loads quickly, but we also defer to your local page first (by design). So if you have a hang or a snag or even just a slow-loading image on your page, it might mean a slight additional delay to the SnapEngage code’s availability.

So what are you to do if you want, say, a hard-coded link on your page that fires onclick="SnapEngage.startLink();" but you want to make sure that function exists before a Visitor clicks it?

One option would be hiding the element until SnapEngage finishes loading, then reveal the element. This is relatively painless to achieve with jQuery or something like it, and only slightly less painless with vanilla 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

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

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

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

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

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

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

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'

Return values of chatType parameter

Return values of boxType parameter

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

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'

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

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

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

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

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

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

Options object

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

Options object

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

API Methods

.allowChatSound()

var allow = true;
SnapEngage.allowChatSound(allow);

Enable or disable all sounds produced by SnapEngage for chat visitors.

Parameters

.allowPageChangeNotification()

var allow = true;
SnapEngage.allowPageChangeNotification(allow);

Deprecated. We are not supporting this API at present. Instead, please use this setting inside your Admin Dashboard as described here.

Should the Chat notify the agent when the visitor navigates to a new page? The notification will include a url to the page in question.

Parameters

.allowProactiveChat()

var allow = true;
SnapEngage.allowProactiveChat(allow);

Should proactive chat invitations be allowed to fire? You can use this to disable (or re-enable) proactive chat wherever it might be necessary.

This option can also be easily configured in the Admin Dashboard. The API call exists primarily for special circumstances, where you want to enable or disable use of proactive chat on specific pages.

Parameters

.allowScreenshot()

var allow = true;
SnapEngage.allowScreenshot(allow);

Deprecated. We are not supporting the screenshot option at present.

Should the Pre-Chat and Offline forms include the Screenshot option? (The screenshot lets visitors send a screenshot of the current page to the agent.)

Parameters

.clearAllCookies()

SnapEngage.clearAllCookies();

Clear and delete all cookies set by SnapEngage for the current visitor.

No Parameters

.disableLightbox()

DEPRECATEDThis API has been deprecated as of Oct 8th, 2019.

SnapEngage.disableLighbox();

Disable the "Lightbox" effect for the prechat form. That is: the greyed-out background when the prechat form comes up.

No Parameters

.getAgentStatusAsync()

SnapEngage.getAgentStatusAsync(function (online) {
    if (online) {
        console.log('chat is online/available');
    } else {
        console.log('chat is offline');
    }
});

Check whether or not you have agents online and your live chat is available.

Parameters

Common reasons for chat being unavailable include: All agents are paused, or it is outside of the widget's configured "Hours of Operation".

Example getAgentStatusAsync() Usage

Hide the chat button if chat is unavailable

SnapEngage.getAgentStatusAsync(function (online) {
    if (!online) {
        SnapEngage.hideButton();
    }
});

Hide the SnapEngage button when your agents are offline/unavailable.

Hide a custom inline button if chat is unavailable

// Using Javascript
SnapEngage.getAgentStatusAsync(function (online) {
    if (!online) {
        document.getElementById('myInlineButtonId').style.display = 'none';
    }
});

// Using jQuery
SnapEngage.getAgentStatusAsync(function (online) {
    if (!online) {
        $('#myInlineButtonId').hide();
    }
});

If you have a custom button image that you've embedded into your site, you may want to show or hide it if the widget is online or offline. This is how you would do that.

Check agent status every three minutes

var threeMinutes = 3 * 60 * 1000;
var tid = setTimeout(checkChatStatus, threeMinutes);

// Check the widget status every three minutes
function checkAgentStatus() {
    SnapEngage.getAgentStatusAsync(function(online) {
        if (online) {
            SnapEngage.showButton();
        } else {
            SnapEngage.hideButton();
        }
    });

    // Recursive call
    clearTimeout(tid);

    // Set another three minute time out
    tid = setTimeout(checkAgentStatus, threeMinutes);
}

As you may have guessed, you can call .getAgentStatusAsync() asynchronously.

.getWidgetId()

SnapEngage.getWidgetId();

Sometimes it will be helpful to know the ID of the currently-active widget, especially if you use .setWidgetId() to change the active widget on the fly.

No Parameters

Returns

// An example widget ID is returned from the call above
'1z1z1z1z1-y2y2-x3x3-w4w4-v5v5v5v5v5v'

An example return value of is inside the code example.

Example getWidgetId() Usage

Send a system message to the agent based on the widget ID

SnapEngage.setCallback('StartChat', function(email, msg, type) {
    var success = false;
    var tid;

    function sendWidgetName() {
        var currWidget = SnapEngage.getWidgetId();

        // For each different widget ID, send a message to the agent with that widget's name
        switch (currWidget) {
            case 'xxxxx-xxxx-xxxx-xxxx' :
                success = SnapEngage.sendTextToChat('A Widget\'s Name');
                break;
            case 'yyyyyy-yyyy-yyyy-yyyyy' :
                success = SnapEngage.sendTextToChat('Other Widget\'s Name');
                break;
            default :
                success = SnapEngage.sendTextToChat('Error fetching Widget Name');
                break;
        }
    }

    // Call the function above
    sendWidgetName();

    if (!success) {
        clearTimeout(tid);

        // Try again every two seconds until success.
        tid = setTimeout(sendWidgetName, 2000);
    }
});

Send a message to the agent that changes for each different widget ID. This code sample uses getWidgetId() along with the StartChat JavaScript event and sendTextToChat().

.hideButton()

SnapEngage.hideButton();

Immediately hide the floating online/offline button.

No Parameters

.openProactiveChat()

// Do not open proactive chat if the user has recently
// closed a proactive invite
var forced = false;

// Do not open the offline box if the widget is not online
var offlineFallback = false;

// Do not open the offline box if the widget is not online
var message = 'Hey there! How can I help you today?';

// Regular chat box
var minimizedView = false; 

// Call the API with the above parameters
SnapEngage.openProactiveChat(forced, offlineFallback, message, minimizedView);

Manually open a proactive message.

Parameters

.sendTextToChat()

// You MUST use sendTextToChat() inside the ChatMessageReceived callback
// which ensures that there is an active chat before the message is sent.
SnapEngage.setCallback('ChatMessageReceived', function (agent, msg) {

    // Send a message to the agent
    var text = 'Remember to mention the current promotion!';
    SnapEngage.sendTextToChat(text);

    // Now clear the ChatMessageReceived callback since you
    // just sent the message. (Otherwise, this callback will
    // send the message every time ChatMessageReceived fires)
    SnapEngage.setCallback('ChatMessageReceived', '');

});

Send a message to the active chat agent without showing it to the visitor. Optionally, add a second parameter of 'visitor' to send this message to the visitor.

Parameters

// You MUST use sendTextToChat() inside the ChatMessageReceived callback
// which ensures that there is an active chat before the message is sent.
SnapEngage.setCallback('ChatMessageReceived', function (agent, msg) {

    // Send a message to the visitor
    var text = 'Thanks for chatting! Here is a 10% off coupon code: TENOFF';
    SnapEngage.sendTextToChat(text, 'visitor');

    // Now clear the ChatMessageReceived callback since you
    // just sent the message. (Otherwise, this callback will
    // send the message every time ChatMessageReceived fires)
    SnapEngage.setCallback('ChatMessageReceived', '');

});

Parameter values

Return values

// if the call above returns 'false', it means
// there is an active chat and the message was
// sent to the visitor.
false

.setButtonEffect()

var negativePixels = '-4px';
SnapEngage.setButtonEffect(negativePixels);

Deprecated. This API method is not supported in the Design Studio. (If you are a legacy Style tab user, this API is supported).

Set the non-hover button position for your button. (Direction is set automatically by your button’s position.)

Parameters

.setCallback()

SnapEngage.setCallback(eventName, function (eventParameters) {
    console.log(eventParameters);
});

The method used to hook a function onto a SnapEngage JavaScript Event. For a full list of eventName and eventParameters, please reference the SnapEngage JavaScript Events documentation.

Parameters

.setChatFormPosition()

// Set the legacy chatbox to pop up in the 'tl' (top left)
// corner of the browser window
var position = 'tl';
SnapEngage.setChatFormPosition(position);

Deprecated. This API method is not supported in the Design Studio. Design Studio users may change the position of the chat form by going to Chat Box -> Global Box Settings -> In-page Popup. (If you are a legacy Style tab user, this API is still supported).

Manually set the position where you would like the chat window to appear. (Will not reposition an already-visible chat box.)

This option can also be easily set in the legacy Style tab of the Admin Dashboard without the need for an API call. But you can use this function if you need to reposition the chat box in a special circumstance.

Parameters

Parameter Values

.setCustomField()

var fieldName = 'Company';
var fieldValue = 'Vandelay Industries';

SnapEngage.setCustomField(fieldName, fieldValue);

Pre-populate any field on your prechat or offline form. (The field is still editable by the visitor.)

For Design Studio users only. Legacy chat users may instead use the .setDescription(), .setUserEmail(), or .setUserName() API methods to pre-populate their non-custom form fields. Custom form users will be able to pre-populate any custom fields on their forms by simply using JavaScript, for example, document.getElementById("myFavoriteColor").value = "blue".

Parameters

.setDescription()

var description = 'Hello! I need help!';
SnapEngage.setDescription(description);

Pre-populate the 'Description' field on the prechat form. (The description is still editable by the visitor.)

Parameters

.setLocale()

var languageCode = 'de';
SnapEngage.setLocale(languageCode);

Allows you to set the visitor chat to use a different language than the one you have set up in your Admin Dashboard. See table of Paramter Values for potential locales.

Parameters

Parameter values

.setNoProactiveChatDelay()

// Delay the proactive invitation for 10 minutes
var delayInMinutes = 10;
SnapEngage.setNoProactiveChatDelay(delayInMinutes);

Disable or alter the amount of time that proactive invitations remain disabled for any visitor who closes a chat window. The default proactive invitation delay (without using this API) is 30 minutes.

Parameters

.setProactiveAutoCloseDelay()

// Autoclose the proactive invitation after 5 minutes of inactivity
var minutes = 5;
SnapEngage.setProactiveAutocloseDelay(minutes);

Adjust the time before the proactive invitation disappears. The default proactive autoclose delay is 2 minutes.

By default, the proactive chat window is set to close after 2 minutes of inactivity, that is: if a visitor does not respond for a couple minutes, we generally assume that they are not interested in chatting. If you never want the proactive invitation to disappear, set the parameter to 0.

Parameters

.setUserEmail()

var email = '[email protected]';

// Set the email field
SnapEngage.setUserEmail(email);

// Do the same as above AND make the email field read-only
// i.e. not editable for the visitor
SnapEngage.setUserEmail(email, true);

This API will do three things:

First, it pre-populates the 'email' field on your prechat or offline form (if this field exists).

Second, this API will provide a visitor’s email address to an agent who takes the chat. The email gets stored on the conversation (case) and will be passed to your integration at the close of the case.

Third, on submit of a prechat or offline form, a cookie will be stored in the visitor's browser called 'SnapABugUserEmail' to repeat this same behavior on future chats. Read more about the SnapABugUserEmail cookie here.

Parameters

.setUserName()

var name = 'Arya Stark';
SnapEngage.setUserName(name);

This API will do four things:

First, it pre-populates the 'name' field on your prechat or offline form (if this field exists).

Second, it updates the visitor alias that is displayed in the chatbox chat transcript.

Third, this API will provide the visitor’s name to the agent who takes the chat. If the user's email is known, SnapEngage will update the database contact with this name (note: see green box below).

Fourth, this API stores a cookie in the visitor's browser called 'SnapABugUserAlias'¹ to repeat this same behavior on future chats. Read more about the SnapABugUserAlias cookie here.

¹ This cookie was previously known as the 'SnapABugUserName' cookie which is now deprecated.

Parameters

.setWidgetId()

DEPRECATED as of March 12th 2018. See switchWidget() for improved functionality.

var widgetId = '1234-5678-91011-1213-1415'
SnapEngage.setWidgetId(widgetId);

Manually set the currently-active widget. A common use case would be offering chat buttons which are linked to separate widgets on a single page; for instance, creating one link that goes to your Help Desk widget, and another that goes to your Sales Team widget. Learn how to set that up right here.

Parameters

.showButton()

SnapEngage.showButton();

Show the floating online or offline button defined in your Design Studio theme (or for legacy users, the button set up in your Style tab).

No Parameters

.startChat()

var msg = 'Hey there, do you need help learning about' +
' The Invigaron System?';
SnapEngage.startChat(msg);

Start a chat session and send a manually defined message to the visitor.

Parameters

.startLink()

SnapEngage.startLink();

// You can also use this JavaScript method inside the onclick attribute
// of an <a> tag on your page. When a visitor clicks this link, it will fire
// SnapEngage.startLink() and open the chat box.
<a href="#" onclick="SnapEngage.startLink();">Chat with us!</a>

The default method for starting a chat from an on-page <a> link's onclick event.

No Parameters

.switchWidget()

var newWidgetId = "1234-5678-91011-1213-1415";
var switchCallback = function() {
    // do something
};

SnapEngage.switchWidget(newWidgetId, switchCallback);

Enable switching between two widgets.

We have deprecated the setWidgetId() API to provide a better solution for switching between two widgets and returning a more accurate status to help with your business needs. Additionally, we now offer an optional callback parameter so you can do more when the new status is returned. Here we do not differentiate between online and offline status, however, you can use the getAgentStatusAsync API to call different methods based on the new status.

Parameters

Returns

Example switchWidget() Usage

// Setup required parameters
var newWidgetId = "1234-5678-91011-1213-1415";
var switchCallback = function() {
    SnapEngage.getAgentStatusAsync(function(online) {
        if (online) {
            console.log("Chat available");
        } else {
            console.log("Chat offline");
        }
    });
};

// Now call the API
SnapEngage.switchWidget(newWidgetId, switchCallback);

.endChat()

var options = { closeChatBox: true };
SnapEngage.endChat(options);

Forces chat to end.

Parameters

Options object

Returns

Example endChat() Usage

Force chat box to close when a chat ends.

var event = SnapEngage.callbacks.CHAT_ENDED;
function callback() {
  SnapEngage.endChat({ closeChatBox: true });
}
SnapEngage.setCallback(event, callback);