> For the complete documentation index, see [llms.txt](https://rudderlabs.gitbook.io/rudderlabs-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rudderlabs.gitbook.io/rudderlabs-1/docs/destinations/business-messaging/intercom.md).
# Intercom
Step-by-step guide on sending your event data from RudderStack to Intercom.
[Intercom](https://www.intercom.com/) is a real-time business messaging platform that lets you bring together and manage all your customer life cycle activities in a single platform.
Find the open source transformer code for this destination in the [GitHub repository](https://github.com/rudderlabs/rudder-transformer/tree/master/v0/destinations/intercom).
**This destination supports Intercom API v1.4.**.
## 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](https://rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/) guide.
Once you have confirmed that your source platform supports sending events to Intercom, follow these steps:
* From your [RudderStack dashboard](https://app.rudderstack.com/), add the source. Then, from the list of destinations, select **Intercom**.
* Assign a name to the destination and click on **Next**.
### Connection settings
To successfully configure Intercom as a destination, you will need to configure the following settings:
* **Access Token**: Enter your Intercom API access token. You can obtain the token by going to your Intercom dashboard and navigating to **Settings** > **Developers** > **Developer Hub**. Then, select your app and go to **Configure** > **Authentication**.
For more information on obtaining the Intercom API access token, refer to the [Intercom Knowledge Base](https://help-desk-migration.com/help/get-intercom-api-access-token/).
* **App ID**: The Intercom app ID is required for sending events via the web and mobile SDKs. You can get this ID from your Intercom dashboard by going to **Settings** > **Installation** and selecting the relevant platform.
For more information on obtaining the your Intercom app ID, refer to the [Intercom Knowledge Base](https://www.intercom.com/help/en/articles/3539-where-can-i-find-my-workspace-id-app-id).
* **Android API Key** / **iOS API Key**: This is required for sending events from your mobile apps to Intercom. You can get it from your Intercom dashboard by going to **Settings** > **Installation** and selecting the relevant platform.
* **Include Context with Identify Calls**: Enable this option to send the user context details to Intercom in the [`identify`](#collecting-identify-context) calls.
* **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. For more information on the scenario where this setting is useful, refer to the [FAQ](#faq) section below.
## Adding device mode integration
Depending on your platform of integration, follow the steps below to add Intercom to your project:
Android iOS If this is the first time you are integrating the RudderStack Android SDK to your project, refer to the [Android SDK](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-android-sdk/) documentation for more information.\
Your Android app 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:
1. In your app-level `build.gradle` file, add the following `repository`:
```groovy
repositories {
mavenCentral()
}
```
2. Then, add the following under `dependencies`:
```groovy
// 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'
```
3. Change the initialization of your RudderStack client with the following:
```kotlin
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 the RudderStack iOS SDK to your project, refer to the [iOS SDK](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-ios-sdk) documentation for more information.\
To add the RudderStack iOS SDK to your project, follow these steps:
1. Add the required pod followed by `pod install`:
```ruby
pod 'Rudder-Intercom'
```
2. Initialize the client as follows:
```objectivec
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]];
```
3. Add a **Privacy - Photo Library Usage Description** entry to your `Info.plist`. This is [required by Apple](https://developer.apple.com/library/content/qa/qa1937/_index.html) 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`](https://www.rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/identify/) call captures the details about a visiting user.
A sample`identify` call looks like the following code snippet:
```javascript
rudderanalytics.identify("1hKOmRA4GRlm", {
name: "Alex Keener",
email: "alex@example.com",
company: {
id: "group01",
name: "Tech Group",
},
createdAt: "Mon May 19 2019 18:34:24 GMT+0000 (UTC)",
})
```
### Using `identify` calls
You can use the `identify` call to create or update user information in Intercom, as explained below:
* **Create/update a user**: When you make an`identify` call, RudderStack creates or updates the user in Intercom using their [Users API](https://developers.intercom.com/reference#users).
* **Remove users from a company**: To remove users from a company, you can pass `remove: true` inside the `company` object, as shown:
```javascript
rudderanalytics.identify("1hKOmRA4GRlm", {
name: "Alex Keener",
email: "alex@example.com",
company: {
id: "group01",
name: "Tech Group",
remove: true
},
createdAt: "Mon May 19 2019 18:34:24 GMT+0000 (UTC)",
})
```
* **Unsubscribe users**: To unsubscribe users from emails, you can pass `unsubscribedFromEmails: true` inside the `context` object, as shown:
```javascript
rudderanalytics.identify("1hKOmRA4GRlm", {
name: "Alex Keener",
email: "alex@example.com",
company: {
id: "group01",
name: "Tech Group",
},
unsubscribedFromEmails: true,
createdAt: "Mon May 19 2019 18:34:24 GMT+0000 (UTC)",
})
```
RudderStack does not support Intercom's **Last Seen** feature currently.
### Traits mapping
The following table lists the mapping of the RudderStack traits to the Intercom properties:
| RudderStack trait | 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` |
### Collecting `identify` context
If you enable the **Include Context with Identify Calls** option in the RudderStack dashboard, RudderStack collects the following contextual properties through its mobile libraries (if available):
* `device.type`
* `device.model`
* `device.manufacturer`
* `os.name`
* `os.version`
* `app.name`
* `app.version`
## Track
The [`track`](https://www.rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/track/) call lets you record the customer events, that is, the actions they perform, along with any properties associated with them.
A sample `track` call is shown below:
```javascript
rudderanalytics.track("Order Completed", {
order_id: "140021222",
checkout_id: "WAP3211",
products: "sports_shoes"
revenue: 77.95,
currency: "USD",
})
```
RudderStack converts and sends all the `track` event properties as per the [Intercom API](https://developers.intercom.com/intercom-api-reference/reference#event-metadata-types).
## Page
The [`page`](https://www.rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/page/) call lets you record your website's page views with any additional relevant information about the viewed page.
The `page` call is supported **only** for the [**JavaScript SDK**](https://www.rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk/) when sending events via the [**device mode**](https://www.rudderstack.com/docs/rudderstack-cloud/rudderstack-connection-modes/#device-mode). 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:
```javascript
rudderanalytics.page("Best Seller")
```
## Reset
The `reset` method resets the previously identified user and any related information.
Android iOS To reset user identification in your Android app, run the following command:
```kotlin
rudderClient.reset();
```
To reset user identification in your iOS app, run the following command:
```objectivec
[[RSClient sharedInstance] reset];
```
## FAQ
### Does RudderStack support Intercom's push notification and deep linking features?
Unfortunately, none of the RudderStack SDKs support push notifications and deep linking features currently. Refer to the [Intercom documentation](https://developers.intercom.com/installing-intercom/docs) for more information on configuring these features for your project.
### What happens if both `userId` or `email` are missing in the `identify` / `track` calls sent to Intercom?
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.
It is highly recommended to enable the [Send AnonymousId as Secondary UserId](#connection-settings) setting in your RudderStack dashboard to avoid any event loss in such a scenario.
## Contact us
For queries on any of the sections covered in this guide, you can [contact us](mailto:%20docs@rudderstack.com) or start a conversation in our [Slack](https://rudderstack.com/join-rudderstack-slack-community) community.