Intercom

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

RudderStack supports Intercom as a destination to which you can send your event data from a variety of sources.

This documentation is written for Intercom API v1.4.

Find the open-source transformer code for this destination in our GitHub repo.

Getting started

Before configuring Intercom as a destination in RudderStack, verify 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	Supported	Supported	Supported

To know more about the difference between cloud mode and device mode in RudderStack, refer to the RudderStack connection modes guide.

Once you have confirmed that your source platform supports sending events to Intercom, follow these steps:

From your RudderStack dashboard, add the source. From the list of destinations, select Intercom.

Follow our guide on Adding a Source and Destination in RudderStack for more information.

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

Connection settings

The connection settings required to configure Intercom as a destination in RudderStack are listed below:

API Key: Enter your Intercom API key. You can obtain the key by going to your Intercom dashboard and navigating to Settings - Developers - Developer Hub. Then, go to your app and navigate to Configure - Authentication.

For more information on obtaining the Intercom API key, refer to their documentation.

App ID: This is required for the sending events via the web and mobile SDKs. You can get it from Intercom Settings - Installation and choosing your desired platform.

For more information on obtaining the your Intercom app ID, refer to their documentation.

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 and selecting your desired platform.
Send AnonymousId as Secondary UserId: Enable this option to send anonymousId as the user ID to Intercom when the userId is absent from the event payload.

This option is helpful for tracking anonymous users on your site.

Adding device mode integration

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

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

Your Android project must be on version 5.0 (API level 21) or higher for RudderStack to be able to send events to Intercom.
Once confirmed, follow these steps to add Intercom to your Android project:

In your app-level build.gradle file, add the following repository:
```
repositories {
    mavenCentral()
}
```

Then, 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()
)

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

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

Add the required pod followed by pod install:
```
pod 'Rudder-Intercom'
```

Initialize the client as follows:

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

Identify

The identify call captures the details about a visiting user.

A sampleidentify call 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 the 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 the context object.

The Last Seen feature of the identify call has not been implemented yet. We will be implementing it soon - 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 option

On enabling the Collect Context option in the RudderStack dashboard, the events are collected through the mobile libraries (if available).

The collected events are as follows:

device.type
device.model
device.manufacturer
os.name
os.version
app.name, and
app.version

Track

The track call lets you record the customer events, i.e. the actions that they perform, along with any properties associated with them.

A sample track call is shown below:

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 lets you record your website's page views with any additional relevant information about the viewed page. Many destinations require the page events to be called at least once every page load.

The page call works only through the RudderStack web SDK rudderanalytics.js and is not supported by other sources. It works by triggering Intercom's update method, which looks for a list of new open conversations to be displayed to the current user.

A sample page call looks like the following code snippet:

rudderanalytics.page()

Reset

The reset method resets the previously identified user and the related information.

For Android, run the following command:

rudderClient.reset();

For iOS, run the following command to implement the reset method in your iOS project:

[[RSClient sharedInstance] reset];

Implementing push notifications and deep linking

None of the RudderStack SDKs support push notifications at this point. Refer to the Intercom documentation for more information on setting 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. Then, select your app and go to Configure - Authentication.

For more information on obtaining the Intercom API key, refer to their documentation.

What happens if both userId or email are missing in the identify/track calls?

For both identify and track calls, either userId or email is a mandatory field. In case both these fields are missing, RudderStack will drop the event.

We highly recommend enabling the Send AnonymousId as Secondary UserId setting in your RudderStack dashboard in such scenarios, to avoid any event loss.

Contact us

For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.