The Intercom JavaScript API

Loading the Intercom JavaScript library provides an Intercom JavaScript object that responds to a few methods that allow you to update users without a page refresh and interact with the message window.

Intercom('boot', intercomSettings)

If you'd like to control when Intercom is loaded, you can use the 'boot' method. This is useful in situations like a one-page Javascript based application where the user may not be logged in when the page loads. You call this method with the standard intercomSettings object.

Intercom('boot', {  
    app_id: 'abc12345',  
    email: 'john.doe@example.com',
    created_at: 1234567890,
    name: 'John Doe',
    user_id: '9876'
});

Intercom('shutdown')

If you have the Respond product (combined with another product like Engage) you should call the Intercom shutdown method to clear your users’ conversations anytime they logout of your application. Otherwise, the cookie we use to track who was most recently logged in on a given device or computer will keep these conversations in the Messenger for one week. This method will effectively clear out any user data that you have been passing through the JS API.

Intercom('shutdown');

Shutdown Intercom Properly

For more information on how to properly shutdown Intercom please see our example here

Intercom('update')

Calling the update method without any other arguments will trigger the JavaScript to look for new messages that should be displayed to the current user (the one whose details are in the window.intercomSettings variable) and show them if they exist.

Intercom('update');

Calling the update method with a JSON object of user details will update those fields on the current user in addition to logging an impression at the current URL and looking for new messages for the user.

Intercom('update', {"name": "Inigo Montoya"});

If the person's ID is not found in the user list when calling the update, a new user will be created.

If trying to update a custom_attribute you do not need to include those values as an object. Simply include them in-line with the standard Intercom fields and they will be applied accordingly.

Update Throttling

You can call Intercom('update') without getting throttled up to 10 times per page refresh. After the 10th call, you'll be throttled and you'll be allowed to call Intercom('update') a maximum of once every 30 minutes. Reloading the page will refresh this state.

Intercom('hide')

This will hide the main Messenger panel if it is open. It will not hide the Messenger Launcher.

Intercom('hide');

Intercom('show')

This will show the Messenger. If there are no conversations it will open with the new message view, if there are it will open with the message list.

Intercom('show');

Intercom('showMessages')

To open the message window with the message list you can call

Intercom('showMessages');

Intercom('showNewMessage')

To open the message window with the new message view you can call

Intercom('showNewMessage');

Pre-Populate Messages

This function takes an optional second parameter that can be used to pre-populate the message composer as shown below.

Intercom('showNewMessage', 'pre-populated content');

Example Usage of Pre-Populating a Message

You can add a link anywhere on your site to open the new message screen with default content:

Send us <a href="#" onclick="Intercom('showNewMessage', 'Feedback on the new reports feature:')">your feedback on the reports feature</a>

Respond product

Please note that this call is only available with our Respond product.

Intercom('onHide')

Gives you the ability to hook into the hide event. Requires a function argument.

Intercom('onHide', function() { // Do stuff });

Intercom('onShow')

Gives you the ability to hook into the show event. Requires a function argument.

Intercom('onShow', function() { // Do stuff });

Intercom('onUnreadCountChange')

This method allows you to register a function that will be called when the current number of unread messages changes.

Intercom('onUnreadCountChange', function(unreadCount) {
  // Do stuff...
});

Custom Launcher?

If you use a custom launcher and also want to use the 'badge' delivery option, we recommend that you use the onUnreadCountChangemethod to show a badge on your custom launcher. If you use a custom launcher without a badge, you shouldn't use the badge delivery option.

Intercom('trackEvent')

You can submit an event using the trackEvent method. This will associate the event with the currently logged in user and send it to Intercom. The final parameter is a map that can be used to send optional metadata about the event.

Intercom('trackEvent', 'invited-friend');

Events With Metadata

You can also add custom information to events in the form of event metadata.

var metadata = {
  invitee_email: 'pi@example.org',
  invite_code: 'ADDAFRIEND'
};
Intercom('trackEvent', 'invited-friend', metadata);

Intercom('getVisitorId')

A visitor is someone who goes to your site but does not use the messenger. You can track these visitors via the visitor user_id. This user_id can be used to retrieve the visitor or lead through the REST API.

Intercom('getVisitorId')

The Intercom JavaScript API