Installation

We support three different ways to install Intercom on your website. The first is a standard install and will work for most websites. The second is for single page apps and the third uses a Rails gem to install Intercom if your website is built using Ruby on Rails.

First you’ll need to ensure that the web Messenger is enabled from inside the Intercom settings panel. When this is disabled, all requests to Intercom will fail.

Standard installation

If you have a web app with multiple pages where each one triggers a new page refresh then you will most likely need the basic JavaScript method. This means you will not need to create separate actions which trigger when the Messenger will appear or update. The page refresh itself is enough to trigger the action. To set up the basic JavaScript, you will only need to follow one step.

How to Install

To get the Messenger to appear on your web app copy and paste the snippet below before the </body> tag on every page where you want the Messenger to appear for website visitors.

//Set your APP_ID
var APP_ID = "APP_ID";

window.intercomSettings = {
    app_id: APP_ID
  };
(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(document.readyState==='complete'){l();}else if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})();

You can find your workspace ID in the URL when you are logged into Intercom. It will be a string of numbers and letters directly after apps/. So for https://app.intercom.com/a/apps/ecahpwf5/home the workspace ID is ecahpwf5.

Installing the Messenger for Regional Data Hosted Customers

For customers who are using Regional Data Hosting for Intercom, there is an additional parameter to set, to ensure your Messenger is pointing to your regional workspace. The snippet below contains this additional api_base parameter to connect to the Messenger's Regional endpoint.

window.intercomSettings = {
    app_id: REGIONAL_APP_ID,
    api_base: `see table below`
  };
Regional LocationAPI Base to Set
UShttps://api-iam.intercom.io
EUhttps://api-iam.eu.intercom.io
Australiahttps://api-iam.au.intercom.io

Website visitors v Logged In?

Website visitors are generally leads (visitors if they have not communicated via the Messenger) whereas logged in users are users in the Intercom sense. The main difference is the amount of information you know about them. You will have more info on logged in users so you will want to provide this when sending data via the Messenger.

//Set your APP_ID
var APP_ID = "APP_ID";
var current_user_email = "sartre@existentialist.com";
var current_user_name = "Jean Paul Sartre";
var current_user_id = "1940";

window.intercomSettings = {
    app_id: APP_ID,
    name: current_user_name, // Full name
    email: current_user_email, // Email address
    user_id: current_user_id // current_user_id
  };
(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(document.readyState==='complete'){l();}else if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})();

Single Page App

If you have a single page app then you can get Intercom installed on your page in two simple steps. So let's waste no time and get you chatting to your customers.

Step 1: Include Intercom JS Library

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

//Set your APP_ID
var APP_ID = "APP_ID";

(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(document.readyState==='complete'){l();}else if(w.attachEvent){w.attachEvent('onload',l);}else{w.addEventListener('load',l,false);}}})();
Be sure to set your APP_ID!

One of the most common issues people have when setting up Intercom first is they forget to include their App ID in the above library code and copy and paste it into their site. The problem is you won't see any error message and Intercom will not show up when you boot the Messenger in the next step. You can set it using a var as noted in the above example or manually in the code itself. You might need to include the App ID in multiple places so using a var is generally a good idea.

You can find your workspace ID in the URL when you are logged into Intercom. It will be a string of numbers and letters directly after apps/. So for https://app.intercom.com/a/apps/ecahpwf5/home the workspace ID is ecahpwf5.

Step 2: Launch Messenger

Once you have the Intercom library installed then you need to tell the Messenger to startup. You can do this using the Respond code snippet which will enable the Messenger to launch whenever the page is refreshed, i.e. no special action needs to be triggered to launch it.

window.Intercom('boot', {
   app_id: APP_ID,
  //Website visitor so may not have any user related info
});

Adding information in the boot

The above example is the most basic way you can launch the Messenger. It does not include any information when it boots. You can include information here if you like but that will depend on what Intercom products you are using and what information you need from your users.

If you have the launcher on page where a user need to sign in to get to then you can include more info in that boot code.

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

Rails gem

If you have a Rails app then you can use our Rails gem to install Intercom.

Step 1: Add Intercom to your Gemfile.

gem "intercom-rails"

Step 2: Make sure Intercom is installed by running this command:

bundle install

Step 3: Generate a config file with this command:

rails generate intercom:config <YOUR APP ID>

You can find your workspace ID in the URL when you are logged into Intercom. It will be a string of numbers and letters directly after apps/. So for https://app.intercom.com/a/apps/ecahpwf5/home the workspace ID is ecahpwf5.

Step 4: Add this line to the config file to display the Messenger on every page of your app:

config.include_for_logged_out_users = true

Once you’ve completed your changes, open your website. Your Messenger should appear in the bottom right corner.