Adding the code

Installing Intercom requires you to paste the code snippet right before the closing </body> tag of every page where your users are logged in. You can access your code snippet through your App Menu.

You must edit the code to include the email address and signed-up date of the user who is currently logged in. This involves some basic server side code to swap in some variables.

var intercomSettings = {
  app_id: 'bk7tlzy4',
  email: 'john.doe@example.com', // Replace with email of current user
  created_at: 1234567890, // Replace with Unix timestamp of signup date
  name: 'John Doe', // Optional: Replace with real name if available
  user_id: '9876' // Optional: Replace with a unique identifier that won't change
};

What is a Unix timestamp, why is it needed?

One of the features of Intercom is the ability to distinguish new users from old ones. To do this, Intercom needs to know when your existing users signed up. This date is sent to Intercom in the form of a Unix timestamp. Every modern programming language has ways to calculate these timestamps. Intercom will also accept ISO 8601 timestamps if generating a Unix one is troublesome.

What if I don’t know or can’t generate the timestamp?

You can send us the date in the example, and every other feature will work correctly, but your sign up date will be incorrect for all users, so features such as “Message users who signed up in the past 30 days” will not work correctly.

What is user_id and why would I want to use it?

You may want to send Intercom a user_id (a unique user identifier that won’t change) instead of or in combination with an email. One reason to do this is that while the user’s email address is subject to change in most apps, you can control the unique identifier that is sent to us, therefore maintaining a consistent user record in Intercom even if the user changes his or her email address. Another reason to use the user_id is if you are very concerned with user privacy and do not want to send an email address at all (Remember that if you don’t send an email we won’t be able to send email messages for you).

My code isn’t working, how can I debug it?

90% of the time, this is due to incorrect JavaScript. These issues are easily spotted by viewing the rendered code in your web application and looking for a missing quote, comma or semi-colon, or occasionally an invalid timestamp. If you believe you have installed the code correctly, and have loaded the page in your web browser, but Intercom hasn’t detected it, simply mail team@intercom.io and include the rendered code (i.e. view source on your web application and code and paste it from there).

Companies

You can also group your users into companies. This is useful if you run a software as a service application or have a multitude of users who all belong to the same organization. You can also track revenue information across all of your companies.

Company information is sent over in the intercomSettings code snippet, as a JSON object called company. Please double check that your company is valid json (even when your database returns a nil value); this means double quotes around all keys and around all strings.

company: {
  "id": 6, // Send numbers without quotes
  "name": "Intercom", // Put quotes around text
  "plan": "Messaging",
  "monthly_spend": 50,
  "created_at" : 1350466020
}

You can also send other attributes within the company object. Those will be treated like custom data attributed to that particular company. You can read more about custom data below.

Custom data

You can send any data you like to Intercom. Typically our customers see a lot of value in sending data that relates to customer development, such as price plan, value of purchases, number of teammates added, etc.

Send custom data in your intercomSettings code snippet as additional key/value pairs. Please double check that your custom data keys always have a json-valid value, this means double quotes around strings and sending nil as a value when there isn't a value for that user.

window.intercomSettings {
  email: "bob@example.com",
  user_id: "123",
  app_id: "abc1234",
  created_at: 1234567890,

  "subdomain": "intercom", // Put quotes around text strings
  "teammates": 4, // Send numbers without quotes
  "active_accounts": 12,
  "last_order_at" : 1350466020, // Send dates in unix timestamp format and end key names with "_at"
  "custom_domain": nil // Send nil when no value exists for a user
}

You can apply filters based on custom data. Intercom allows string-based operators for strings, numerical operators for numerical values, and simple true false filters for booleans values.

Special treatment of dates

You can send dates in custom data by sending a unix timestamp. If the name of your custom data attribute ends with _at then we'll automatically treat it as a date, rather than a number. In the example above, 'last_order_at' will be treated as a date by default.

Adding an Inbox

By default Intercom adds nothing visual to your application. When you send out a message users will see it as a modal, but once viewed they will not be able to recall it, nor can users start a conversation. If you wish to make this possible, you make a small change to your code to tell Intercom to show itself.

There are two types of Inbox supported: simple and advanced.

Simple Inbox

The simple mode attaches a question mark icon in the bottom right hand corner of your application. The background color of the button is customizable. Clicking the question mark opens the message list. Here’s an example:

Advanced Inbox

Advanced mode lets you specify a link in your application that will open the Inbox. You can style this link any way you wish, and choose to include or omit icons, and unread counts. You can see an example of an advanced Inbox in Intercom itself:

Forwarding support emails to your Intercom Inbox

If you use a support email address, such as help@yourapp.com, or support@yourapp.com, you can forward your emails to Intercom to handle all support requests from your Intercom Inbox. Each app has a unique incoming email address, this is found in Settings -> Messaging. When emails arrive to that address we will try and match the sender to a user in your app based on the sender's email address.

Secure mode

Secure mode prevents an attack where a malicious user, with knowledge of another users email address, could read their Intercom messages. It uses a server side generated hash based message authentication code (HMAC), using SHA256, on either the user’s users_id or email. If you send Intercom a user_id in your intercomSettings you must use the user’s user_id instead of their email to generate the HMAC.

When to enable secure mode

You should only enable secure mode once you have changed your code to send over the hash. Once you enable it, Intercom will only recognize snippets where the hash is present and correct.

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

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: 'bk7tlzy4',
              email: 'john.doe@example.com',
              created_at: 1234567890,
              name: 'John Doe',
              user_id: '9876'
            });
          
        

Intercom('update')

Calling the update method without any other arguments will log an impression at the current URL for the current user (the one whose details are in the window.intercomSettings variable). This will trigger the JavaScript to look for new messages that should be shown to the user and show them if any exist.

          
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.

          
Intercom('update', {"name": "Inigo Montoya"});
          
        

Intercom('reattach_activator')

If your app deletes and re-adds your inbox link (which we call your 'activator'), you can call this function to reconnect your link to the Intercom message box. If you're using the default Intercom activator, this will also regenerate it for you.

          
Intercom('reattach_activator');
          
        

Intercom('hide')

This will hide the default Intercom message box.

          
Intercom('hide');
          
        

Intercom('show')

This will show the default Intercom message box.

          
Intercom('show');
          
        

User data

A default Intercom install will gather the following data about your users:

• User email
• Date of last activity
• Date user signed up
• Number of sessions user has had since Intercom was installed. A session for a user starts when the user arrives and ends when (A) More than 30 minutes have elapsed between pageviews for a single visitor. (B) When any traffic source value for the user changes.
• City & Country of user
• Local timezone for user
• Date of last message sent to user
• Date of last message received from user
• Social profiles (including Twitter, LinkedIn, Facebook, and more)
• Twitter follower count

If you want to link directly to a user within Intercom you can use certain user attributes in the url instead of the id string.

To show a user by their email address:

https://www.intercom.io/apps/xxxxxx/users/show?email=jeff@intercom.io

https://www.intercom.io/apps/xxxxxx/users/show?user_id=4868

What does Relationship measure?

Relationship is an indicator of the amount of personal contact a user been involved in. A user who has received and responded to a message in the past 30 days is said to have a 100% relationship (50% awarded for sending a message, 50% for receiving). Both of these figures drop 5% per month. So a user who one received a message 9 months ago will have a 5% relationship.

How does Intercom get my users location?

We use the users IP address to geolocate the user. This method is generally correct and is the industry standard way to locate a web user. There are a few reasons that your users location may appear inaccurate or may not show up at all.

• The location data attached to any IP address is maintained by the ISP (Internet Service provider). The ISP can send as much or as little information as they want. We can only locate a user to the degree that the data from the ISP is accurate and precise.
• Users using VPN's and users behind certain types of firewalls can appear to be somewhere else.

Where do the social profiles come from?

We use a third party service (FullContact) to enrich the user profile view. Given a user’s email address, FullContact will return publicly available social profiles. These are shown by small icons next to the users name on the user profile page. In addition, Twitter follower can be shown on the user list page, allowing you to sort and filter by follower count.

Note: FullContact will return the users name if they have it. If you use message variables to add the users name in your auto-messages we will first try to use the name you provide us in your intercomSettings script, if none exists we will use the FullContact name. In some cases this can unnerve your users if they haven't given your app their name. Please consider what data your users give you when creating auto-messages.

Why is my social data missing or incorrect?

There are two reasons why this happens:

• The data has yet to be captured yet. Intercom periodically updates the social profile data. For new accounts it can take up to 3 days before your userbase will be complete.
• There are no social accounts associated with the email addresses of the user. Often this happens when a user keeps all their accounts tied to their personal address, but is using their work account for your product.
• FullContact has the wrong data attributed to the users email address. This can often be corrected by having the user go to FullContact's site and claim their data. You can claim your data here.

What are Tags?

Tags let you group users together. You can tag specific users based on something they have in common. For example if 3 users have asked for PDF Export, you can tag them with "PDF" and this will make them easy to recall in the future. Anywhere you see a tag you can click it to see who else is tagged with it, and you can use the filter bar to recall users with certain tags applied.

What are Segments?

Segments are like tags that get added to users automatically based on rules you set. For example, if you want to find your monthly active users on your Pro plan, you can just create the filter and then choose Segment. Like so:

How can I delete tags and segments?

You can see your tags and segments, and delete the ones you no longer use, in your App Settings screen under Tags.

Filtering the user list

You can drill down into subsets of your users by using the filter bar. The filter bar is contextual, so for each different attribute you’ll see a different set of options on which to filter.

One of the most powerful features of Intercom is the ability to create Auto Messages based on complex filters. For example, if you wanted to send a message to all users who have racked up more than 100 sessions and signed up more than a year ago to thank them for their loyalty your filters would look something like this:

From here all you need to do is click Auto Message on the right side of the filter bar to create an auto message. Your message will be sent to the users that currently match the filter and, if you leave the auto message active, any user that matches your filter criteria any time in the future. For more detailed information check out the docs on auto messages.

Different Message Types

Conversation

The conversation is a medium-sized popup message that appears in the middle of the browser window and interrupts your users from using your app.

Announcement

Announcements are a larger version of the conversation popup. They will expand to fill a large portion of the users browser window and will definitely interrupt the user. With that in mind, they should only be used when you really have something important to say.

Notification

A small popup that appears in the top-right corner of the browser window. These are great for information that you want to share with your users but shouldn't interrupt them from what they're currently doing.

Inbox

This message is the most subtle. We just add the message to the user's inbox. If you're using the simple inbox or the advanced inbox with the inbox count enabled, the user will see a badge appear to alert them there is a new message waiting.

Email

Exactly what it sounds like, this is a message sent through email. We will also add the message to the user's inbox so that they can easily refer back to it from within your app.

What are Manual Messages?

Manual messages target users. A manual message is sent immediately to a select group of users. You can send a manual message from either the user list, or an individual user’s profile. Manual messages add to a user’s relationship score, and can be sent by email, pop-up, or to the users inbox.

What are Auto Messages?

Auto Messages target conditions. They are messages shown to a user when they match a set of filters. Auto Messages can be created from the user list, once one or more filters are applied. A user will see an auto message the first time they match the filters. Auto Messages can be shown as a pop-up, inbox message or by automated email. Auto Messages can have two additional parameters: you can choose to display them on a specific URL, and have them stop showing after a certain date. You can find these in the “Advanced” section at the bottom of the modal.

How to use Automated Emails

Automated emails are really useful for improving your marketing / engagement / retention processes. Here are a couple of use cases:

1. Retain customers: Automatically email users after 30 days of inactivity Simply filter users last seen more than 30 days ago, and click Auto Message, and then choose email. This mail will go out immediately to those targeted and will also be automatically sent from now onwards to users as they meet the criteria.
2. Increase engagement: Automatically email users who haven’t performed key actions In Intercom, for example, we email users a week after they sign up if they haven’t installed our JavaScript to explain how easy it is. We use these conditions: Signed up: Exactly 7 days, Activated: False.

Read more about auto messages and automated emails in our blog post Automated mails and Customer Respect.

Can users reply to messages?

Users can reply to all messages they receive. When a user replies, the initiator of the conversation will receive an email.

Who receives notifications about user messages?

Each user controls their own mail notifications, via their personal account settings.

How does assignment work?

In App Settings, you can choose a user who is assigned to handle all new conversations from users. Note: users can only start new conversations when you have an inbox link in your web application.

Re-Assigning a conversation

You can re-assign a conversation, simply by clicking re-assign. Adding a private note (only seen by your team) is optional.

Do users see assignment, archiving, or notes?

No. The user only see’s the communications sent to them. If a conversation is re-assigned many times with several notes posted, the user will see nothing until a reply is posted.

How to send a message to all your users

In Intercom, we actively promote targeted messaging; that is, choosing the recipients so that the material is always relevant. That said, occasionally it makes sense to message all your users, and you can do this using a manual message. Simply select all your users on the user list, and click “Manual Message”. This will be sent to all your current users. If you choose to send by email, it will be sent immediately, otherwise they will see it when they next log in to your application.

How to message new users

Filter your user list to show users who signed up after today. This may be zero users, that’s not a problem. It’s the conditions we’re targeting.

Write your message, as you see fit. You may want to restrict this message to show to show only on a specific url, to make sure you greet your users at the right time in your application.

How to message high-value users

Different businesses have different definitions of “high value”. For some apps, it might be long term users on high-value plans. For others it might be frequent visitors, or users with lots of Twitter followers. In any case, sending Intercom custom data will help you see the key figures that matter. After that it’s a case of applying a series of filters based on what you value.

How to re-engage older users

Churn is a problem is all web applications. Some customers will churn because your competitor is cheaper, some because they no longer have a need for product, but most of your customers churn because either they never understood your product, or they felt you never cared about them. Both of these are solved regular customer contact, which Intercom is fantastic for. One sign that you’re losing a customer is gradual disengagement. Re-engaging older users simply requires you to filter to identify high value customers who are less active than they should be.

1. Use filters to identify high value users
2. Add a filter “Last see more than X days ago”, with X varying depending on your web app. Some apps (e.g. project management, to-do etc) should be used every day, others (e.g. invoicing) would be use a few times per month.
3. Send a manual message, by email, to these users. Thank them for their custom, tell them about new features launched or upcoming, give them a compelling reason to return to the app.
4. Be prepared to respond to any questions or concerns they may have.

Intercom customers have found this to be really useful for keeping users onboard beyond an initial flurry of activity.

Using Variables in Messages

You can easily personalise a message to users by including variables specific to their account. For example, you can greet each user by name. To do this just click "Insert Data"

Replace the fallback variable with whatever you would like to include, for users where we do not have the information available. For example this message:
Hey {{ first_name | fallback:"there"}}
will say "Hey John" if we know the users name and "Hey there" if we do not.

HTML Messages

Intercom supports HTML in its messages. This lets you include rich messages to point out new product features, or to include videos or other imagery. To use it, simply write HTML, like so…

Intercom supports the following tags in admin messages:

• Headings: h1, h2, h3, h4, h5, and h6
• Text formatting tags such as strong, em, sub, sup, small, and strike
• Tags for creating tables: table, thead, tbody, tfoot, th, tr, and td
• Lists: Both ol and ul
• Images
• iframes: Supported only for embedding youtube or vimeo videos

Intercom also supports Markdown when writing messages and responding to customers.

Some tips:

• Use https for images to avoid any mixed content warnings.
• Take care to preview your message, especially when sending it by email. You can always tweak in-app messages, but once an email goes out, there’s no turning back.
• While embedded videos work well for in-app messages, many email clients don’t support iframes and will not show your embedded videos. We recommend using a placeholder image with a link to the video instead for email messages.

What types of email can be sent?

Intercom sends 2 types of email, official, and personal. Let's look at each

Official, shown above, includes name and photograph, making the exchange more human, and person to person.

Personal style is designed to make it look 100% manual, and is identical to a normal email.

How to change style of emails?

You can change between styles in the "Advanced" section of the compose message dialogue

Stopping/Editing Messages

If you’re unhappy with a message, you can easily edit it to change the contents, and correct any mistakes. You can edit the contents of a message, but not the conditions under which it is sent. If you no longer want to show a message, you can stop it. The message will no longer show to users as they log in. Emails, once sent, cannot be edited or stopped however :)

Users opting out of emails

Intercom provides a way for users to opt out of receiving bulk emails. When sending a bulk email message, you get the option to include an unsubscribe link in the footer. If the user clicks that, they'll no longer receive any bulk emails from you on Intercom.

You can also opt out a particular user from receiving bulk emails, by including an extra option in the intercomSettings.

var intercomSettings = {
  'app_id' : 'abc123',
  'email' : 'john@example.com',
  'created_at' : 1350467386,
  'unsubscribed_from_emails' : true
}

It is also possible to unsubscribe/resubscribe users from receiving bulk emails in the 'Actions' drop down on the user details page. However if you provide a value for unsubscribed_from_emails in intercomSettings for a user, it will override any manual action by you here, or by the user clicking unsubscribe links in their emails.

What are the price plans for Intercom?

Our pricing is very simple. To use the communication features in Intercom (i.e. Manual Messages, Auto Messages, Inbox etc) costs $50 per application, per month. All other features are free of charge.

What are the Terms of Usage & Privacy Policy for Intercom?

We would like to make two things clear. Firstly we respect your privacy and go to significant efforts to protect all your data. Secondly, we would never do anything with your data that we wouldn't be proud to tell the world about.

Our Terms of Service and Privacy Policy are available for all to read. We welcome feedback on them from our users.

Updating Your Privacy Policy

Always review changes to your sites terms & privacy policy with your lawyers. We suggest that you include the following section to account for using Intercom on your website or web application.

Use of Intercom Services: We use third party analytics services to help understand your use of our services. In particular, we provide a limited amount of your information (such as your email address and sign-up date) to Intercom, Inc. (“Intercom”) and we use Intercom to collect data for analytics purposes when you visit our website or use or product. Intercom analyzes your use of our website and/or product and our relationship with you, so that we can improve our service to you. We may also use Intercom as a medium for communications, either through email, or through messages within our product(s). Also as part of their service to us, Intercom collects publicly available contact and social information related to you, such as your email address, gender, company, job title, photos, website URLs, social network handles and physical addresses, so that we can continue to improve our relationship with you. For more information on the privacy practices of Intercom, please check http://docs.intercom.io/privacy. Intercom’s services are governed by Intercom’s terms of use which can be found at http://docs.intercom.io/terms. If you would like to opt out of having this information collected by or submitted to Intercom, please contact us.