> 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 [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: ![Intercom connection settings](/files/BceEVZD111G0yEy2X22d) * **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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://rudderlabs.gitbook.io/rudderlabs-1/docs/destinations/business-messaging/intercom.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.