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.

Load Intercom

Intercom('boot', {  
    app_id: 'abc12345',  
    email: '[email protected]',
    created_at: 1234567890,
    name: 'John Doe',
    user_id: '9876'
});

Intercom('shutdown')

If you have the Inbox product (combined with another product like Messages) 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.

Shutdown Intercom

Intercom('shutdown');

🚧

Deleting cookies

Note: If you need to delete cookies created by the Messenger but are unable to use this method (e.g. because our JavaScript hasn’t been loaded), all cookies are prefixed with ‘intercom-’ and are created on your domain.

📘

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.

Update With No Arguments

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.

Update With User Details

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 20 times per 30 minutes. After the 20th call, you'll be throttled and the quota of 20 calls will get reset 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.

Hide the Message Window

Intercom('hide');

Intercom('show')

This will show the messenger home screen by default. To open the message window on a specific page use one of the methods below

Show Intercom Messenger

Intercom('show');

Intercom('showMessages')

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

Open With Message List

Intercom('showMessages');

Intercom('showNewMessage')

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

Open For New Messages

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.

Pre-Populate Messages

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:

Link To Message

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

🚧

Inbox product

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

Intercom('onHide')

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

Hide Action

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

Intercom('onShow')

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

Show Action

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.

Read Notification

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.

Submit Events

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

Events With Metadata

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

Event With Metadata

var metadata = {
  invitee_email: '[email protected]',
  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.

Get Visitor ID

Intercom('getVisitorId')