Integrate Intercom in a single page app

If your product rarely refreshes pages, you'll need to install Intercom using these instructions.

Beth-Ann Sher avatar
Written by Beth-Ann Sher
Updated over a week ago

If your app has very few page refreshes (ie., content is swapped out on the client side but no page refresh happens) and lots of asynchronous JS, you'll need to integrate Intercom in a slightly different way to ensure your customers' data is kept up to date, and they receive all your outbound content (messages, tours, etc.)

Here is what we suggest:

First, include the intercom JS library file in your HTML head element.

(function(){var w=window;var ic=w.Intercom;if(typeof ic==="function"){ic('reattach_activator');ic('update',w.intercomSettings);}else{var d=document;var i=function(){i.c(arguments);};i.q=[];i.c=function(args){i.q.push(args);};w.Intercom=i;var l=function(){var s=d.createElement('script');s.type='text/javascript';s.async=true;s.src='https://widget.intercom.io/widget/' + APP_ID;var x=d.getElementsByTagName('script')[0];x.parentNode.insertBefore(s,x);};if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})();

Important: If you copy the code snippet above make sure to manually change your workspace ID (this is called your APP_ID in the code).

Next, once you have a logged in user on your site (after they have authenticated and you have their details available) you call window.Intercom('boot', {user_data}), where user_data is all the data about the user. Please make sure to send the user_id and/or email on every call to update your users. This will send the logged in user's details to Intercom and will check for new messages that should be shown to the user.

An example of this for logged out visitors would be:

window.Intercom('boot', {
app_id: 'abc12345',
custom_launcher_selector: '#my_custom_link'
});

Important: If you copy the code snippet above make sure to manually change your workspace ID (this is called your APP_ID in the code).

Then, when you'd like to log them in or convert them to a user, simply change the boot method to include their user info:

window.Intercom('boot', {
app_id: 'abc12345',
email: 'example@example.com',
user_id: 'abc123',
created_at: 1234567890,
custom_launcher_selector: '#my_custom_link'
});

Important: If you copy the code snippet above make sure to manually change your workspace ID (this is called your APP_ID in the code).

Install Intercom with Google Tag Manager

Using Intercom with JavaScript frameworks

Single page apps are often built with JavaScript frameworks and libraries. Intercom does not have a prescribed list of maintained or supported Javascript frameworks for 3rd party packages.

Tell Intercom when your data or URL changes

There are two further calls that you may need to use in your app.

If your user's data changes, or if you change the URL in some way without a page load, you should call window.Intercom('update', {user_data}), where user_data is a set of changes to your user data.

Important: An update call simulates a page refresh, causing Intercom to check for any new messages or tours to send to the customer.

You only need to include whatever has changed—you don't need to include all user data in each update. You should, however, still send the user_id and/or email.

You use the update function like this (Make sure to change your app_id):

  • You boot the user as normal: window.Intercom('boot', {app_id: APP_ID, email: 'someuser@example.com', apples: 1});

  • If the user's data is changed, or they've just caused a 'page' change, you would call: window.Intercom('update', {email: 'someuser@example.com', apples: 2}); with any new user data.

Important: You will need to call Intercom("update") with some new user data in order to initiate a "ping" every time a URL changes. If no user data has changed you can send the current time as the value for 'last_request_at' like this:

Intercom("update", {last_request_at: parseInt((new Date()).getTime()/1000)})

If the URL changes without a full page reload, the Intercom Messenger does not automatically send URL changes to Intercom to match messages based on URLs.

Note: The update call is limited to 10 times per user per page without getting throttled. If you exceed this rate, you'll be allowed to call once in 30 minutes. A page refresh or reload will reset this.

We recommend updating only in places where there is a user data change sent to Intercom that could trigger an Auto Message for this reason.

How to end a session

Intercom allows you to put the Intercom Messenger on any public facing site that you own (your marketing site, your docs site, your developer hub, etc). In order to maintain continuity of conversations across all of these potentially different subdomains while your users are logged in, we set a cookie in your user’s browser. This cookie expires after one week.

Any user that uses a shared computer and browser with someone else will be able to see the most recently logged in user’s conversation history until the cookie expires. Because of this, it’s very important to properly shutdown Intercom when a user’s session on your app ends (via manually or automatically logging out).

Here’s how to shutdown Intercom:

  1. You will have already begun tracking your user via the Intercom JS snippet or the “boot” method.

  2. When your user logs out of Intercom (or is automatically logged out by your app), call Intercom('shutdown'); from our JavaScript API, to end the Intercom session and clear the cookie.

  3. If applicable, call Intercom('boot', {app_id: 'YOUR_APP_ID'}) to start a fresh session.

Important: Make sure to change app_id in the code with your own workspace ID.

The Intercom('shutdown');method will automatically reset Intercom to a clean state for logging in another user or booting Intercom for logged-out areas of your application.

Now you're ready to start using Intercom, like Veena 👇

Announcing new features through Intercom is the most effective way our users become aware of what we're building.

Enabling identity verification in a single page app

To enable identity verification on your single page app, you should add the user_hash attribute to your boot call. More details can be found here.

What’s next?

  • Watch a demo: If you'd like to learn how to use Intercom from the people who built it, watch a demo video.


💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts


Did this answer your question?