Intercom

Step-by-step guide to send your event data from RudderStack to Intercom

Intercom is an industry-leading, real-time business messaging platform, that allows you to bring together and manage all your customer life cycle activities on a single platform.

RudderStack allows you to send your event data from a variety of sources to Intercom through S2S and native SDKs by calling the relevant APIs.

Please note that this documentation is written for Intercom v1.4.

Getting Started

To enable sending events to Intercom, you will first need to add it as a destination to the source from which you are sending event data. Please check if the source platform is supported by Intercom by referring to the table below:

Connection Mode

Web

Mobile

Server

Device mode

Supported

Supported

-

Cloud mode

-

-

-

Once you have ascertained that the source platform is supported by Intercom, please follow these steps:

  • From your RudderStack dashboard, add the source and select Intercom from the list of supported destinations.

Please follow our guide on How to Add a Source and Destination in RudderStack to add a source and destination in RudderStack.

  • Give a name to the destination, and click on Next. You should then see the following screen:

Connection screen for Intercom

Enter the relevant keys in the fields above by obtaining them from the following locations:

  • API Key: This is required for all the S2S (Server to Server) events. This can be obtained by going to Intercom Settings - Developers - Developer Hub - <Your App> - Configure - Authentication.

  • App ID: This is required for sending events via rudderanalytics.js and mobile SDKs. You can get it from Intercom Settings - Installation - <the desired platform> Alternatively, you can follow the instructions listed here.

  • Android API Key & iOS API Key: This is required for sending events from your mobile apps to Intercom. You can get it from Intercom Settings - Installation - <the desired platform>

Adding Intercom to your project

Depending on your platform of integration, follow the steps below to add Intercom to your project.

Android
iOS
Android

If this is the first time you are integrating our RudderStack Android SDK to your project, please refer to our RudderStack Android SDK for more information.

To add the RudderStack Android SDK to your project, please follow these steps:

  • In your app-level build.gradle file, add the following repository:

repositories {
maven { url "https://dl.bintray.com/rudderstack/rudderstack" }
}
  • After that add the following under dependencies

// Rudder core sdk and intercom extension
implementation 'com.rudderstack.android.sdk:core:1.0.2'
implementation 'com.rudderstack.android.integration:intercom:0.1.1'
// intercom core sdk
implementation 'io.intercom.android:intercom-sdk-base:6.+'
// gson
implementation 'com.google.code.gson:gson:2.8.6'
// FCM
implementation 'com.google.firebase:firebase-messaging:20.2.0'
  • Change the initialization of your RudderStack client with the following:

val rudderClient:RudderClient = RudderClient.getInstance(
this,
WRITE_KEY,
RudderConfig.Builder()
.withDataPlaneUrl(DATA_PLANE_URL)
.withLogLevel(RudderLogger.RudderLogLevel.DEBUG) // optional
.withFactory(IntercomIntegrationFactory.FACTORY)
.build()
)
iOS

If this is the first time you are integrating our RudderStack iOS SDK to your project, please refer to our RudderStack iOS SDK for more information.

To add the RudderStack iOS SDK to your project, please follow these steps:

  • Add the required pod followed by pod install

pod 'Rudder-Intercom'
  • Initialize the client:

RSConfigBuilder *builder = [[RSConfigBuilder alloc] init];
[builder withDataPlaneUrl:DATA_PLANE_URL];
[builder withFactory:[RudderIntercomFactory instance]];
[builder withLoglevel:RSLogLevelDebug]; // optional
[RSClient getInstance:WRITE_KEY config:[builder build]];
  • Add a Privacy - Photo Library Usage Description entry to your Info.plist. This is required by Apple for applications that can access the photo library.

Users will be prompted for the permission to access the photo library only when they tap the button to upload their image/s.

Identify

The identify call captures the details about a visiting user. For more information, please refer to our RudderStack API Specification guide.

A sampleidentify call in RudderStack looks like the following code snippet:

rudderanalytics.identify('tp4r23', {
name: 'John Doe',
email: 'john@doe.com',
company: {
id: 'company123',
name: 'John Doe Inc.'
},
createdAt: 'Mon May 19 2019 18:34:24 GMT+0000 (UTC)'
});

The identify call can be used to :

  • Create / Update a user : When you make anidentify call, RudderStack creates or updates a user in Intercom using their Users API.

  • Remove users from a company : To remove users from a company, you must pass remove: true inside the company object.

  • Unsubscribe users : To unsubscribe users from emails, unsubscribedFromEmails: true must be passed inside context object.

The Last Seen feature of the identify call has not been implemented yet. Please stay tuned!

The following RudderStack properties are matched to Intercom's properties -

RudderStack Property

Intercom iOS Property

Intercom Android Property

traits.userId

user_id

user_id

traits.email

email

email

traits.name

name

name

traits.phone

phone

phone

traits.company

company

company

traits.createdAt

signedUpAt

signed_up_at

Collect Context

On enabling the Collect Context option in the RudderStack dashboard for Intercom, events are collected through the mobile libraries (if available). The collected events are : - device.type , device.model, device.manufacturer, os.name, os.version , app.name, and app.version

Track

The track call captures information related to the actions performed by the user, along with all the other properties associated with that action or event. For more information, please refer to our RudderStack API Specification guide.

The following code snippet is an example of a track call in RudderStack:

rudderanalytics.track('Product bought', {
order_ID: '140021222',
category: 'shoes',
product_name: 'sports_shoes',
price: 199.95,
currency: 'USD'
});

All the traits provided in the track call will be converted as per Intercom's API.

Page

The page call contains information such as the URL or the web page visited by the user. For more information, please refer to our RudderStack API Specification guide. The page call works only through our rudderanalytics.js and is not supported by other sources. It works by triggering Intercom's update method, which looks for a list of new conversations that are open and should be displayed to the current user.

A sample page call in RudderStack looks like the following code snippet:

rudderanalytics.page();

Reset

The reset method resets the previously identified user and the related information. For more information, please refer to our RudderStack API Specification guide.

Android
iOS
Android

For Android, simply run the following command:

rudderClient.reset();
iOS

Run the following command to implement the resetmethod in your iOS project:

[[RSClient sharedInstance] reset];

Implementing push notifications and deep linking

None of our SDKs support push notifications at this point of time. Refer to the Intercom documentation for more information on how to set these features up for your project.

FAQs

How do I get the Intercom API key?

You can obtain the Intercom API key by logging into Intercom and navigating to Settings - Developers - Developer Hub - <Your App> - Configure - Authentication. Please check the Getting Started section above for details.

Contact Us

If you come across any issues while configuring Intercom with RudderStack, please feel free to contact us or start a conversation on our Discord channel. We will be happy to help you.