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

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.


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');
Intercom('update', {"name": "Inigo Montoya"});

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

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

Intercom('showNewMessage');
Intercom('showNewMessage', 'pre-populated content');
# 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>

Inbox Only

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


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...
});

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.

Intercom('trackEvent', 'invited-friend');
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')

What's Next

Understand more about the data that can be passed in with these calls through our second Javascript API documentation page.

Javascript API: Attributes & Objects