Javascript API: Methods

Loading the Intercom JavaScript library provides an Intercom JavaScript object that responds to a few methods. These allow you to update users without a page refresh and interact with the messenger 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 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.

Intercom('shutdown');

Deleting cookies

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.

Intercom('update')

Calling the update method with some new user data 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.

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');

IDs & Data

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

Intercom('hide');

Intercom('show')

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

Intercom('show');

Intercom('showSpace', spaceName)

This will show the specified space in the Messenger, if that space is enabled.

Intercom('showSpace', 'home');
Intercom('showSpace', 'messages');
Intercom('showSpace', 'help');
Intercom('showSpace', 'news');
Intercom('showSpace', 'tasks');
Intercom('showSpace', 'tickets');

Intercom('showMessages')

This will open the Messenger with the message list.

Intercom('showMessages');

Intercom('showNewMessage')

This will open the Messenger as if a new conversation was just created.

This function can also take an optional second parameter, used to pre-populate the message composer as shown in the code example below..

Open For New Messages

Intercom('showNewMessage');

Pre-Populate Messages

Inbox Only

Pre-populating messages is only possible with our Inbox Essential & Pro product.

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

Intercom('onHide')

When we hide the messenger, you can hook into the event. This requires a function argument.

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

Intercom('onShow')

When we show the messenger, you can hook into the event. This requires a function argument.

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

Intercom('onUnreadCountChange')

This method allows you to register a function that will be called immediately when invoked, and again whenever the current number of unread messages changes.

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

Using with a Custom Launcher

If you use a custom launcher and also want to use the 'badge' delivery option, we recommend that you use the onUnreadCountChange method 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.

You can also add custom information to events in the form of event metadata, which can be included in event based messages to your customers.

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

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

Intercom('startTour', tourId)

If you would like to trigger a tour based on an action a user or visitor takes in your site or application, you can use this API method. You need to call this method with the id of the tour you wish to show. The id of the tour can be found in the “Use tour everywhere” section of the tour editor.

Please note that tours shown via this API must be published and the “Use tour everywhere” section must be turned on. If you're calling this API using an invalid tour id, nothing will happen. Nothing will happen if you call this API on mobile web as tours do not work on mobile.

Intercom('startTour', 123);

Intercom('showArticle', articleId)

If you would like to trigger an article in the Messenger, you can use the showArticle method. The article will be shown within the Messenger, and clicking the Messenger back button will return to the previous context.
If the Messenger is closed when the method is called, it will be opened first and then the article will be shown.

Intercom('showArticle', 123);

Intercom('showNews', newsItemId)

If you would like to trigger a news item in the Messenger, you can use the showNews method. The news item will be shown within the Messenger, and clicking the Messenger back button will return to the previous context.
If the Messenger is closed when the method is called, it will be opened first and then the news item will be shown.

Intercom('showNews', 123);

Intercom('startSurvey', surveyId)

If you would like to trigger a survey in the Messenger, you can use the startSurvey method. The id of the survey can be found in the “Additional ways to share your survey” section of the survey editor as well as in the URL of the editor.

Please note that surveys shown via this API must be live. If you're calling this API using an invalid survey id, nothing will happen.

Intercom('startSurvey', 123);

Intercom('startChecklist', checklistId)

If you would like to trigger a checklist in the Messenger, you can use the startChecklist method. The id of the checklist can be found in the “Additional ways to share your checklist” section of the checklist editor as well as in the URL of the editor.

Please note that checklists shown via this API must be live. If you're calling this API using an invalid checklist id, nothing will happen.

Intercom('startChecklist', 123);

Intercom('showTicket', ticketId)

If you would like to trigger a ticket in the Messenger, you can use the showTicket method. The ticket will be shown within the Messenger, and clicking the Messenger back button will return to the previous context.
If the Messenger is closed when the method is called, it will be opened first and then the ticket will be shown.

Intercom('showTicket', 123);

Intercom('showConversation', conversationId);

You can show a conversation programatically in the Messenger by calling showConversation method

Intercom('showConversation', 123);

Intercom('onUserEmailSupplied')

When a visitor enters their email into the Messenger, you can hook into the event. This requires a function argument.

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