Intercom destination

Send your event data from RudderStack to Intercom.

Intercom is a real-time business messaging platform that lets you manage all your customer lifecycle activities in a single platform.

Find the open source transformer code for this destination in the GitHub repository.

info

This destination supports Intercom API v2.1 for cloud mode integration.

For existing Intercom destination integrations that leverage API v1.4, the RudderStack team will handle the migration internally. See the Changelog for more information.

Setup

  1. In your RudderStack dashboard, go to Directory > Destinations > Cloud Destinations and search for Intercom.
  2. Connect your source and click Continue.

Connection settings

Configure the following settings to set up Intercom as a destination in RudderStack:

  • Name: Assign a name to uniquely identify the destination.
  • Access Token: Enter your Intercom API access token. You can obtain the token by going to your Intercom dashboard and navigating to Settings > Apps & Integrations > Developer Hub. Then, select your app and go to Configure > Authentication. For more information, see Intercom documentation.
  • API Server: Select your Intercom workspace server. By default, RudderStack sets it to Standard (US) and provides two other options - EU (Europe) and AU (Australia).
  • App ID: The Intercom app ID is required for sending events via the web device mode. 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, see Intercom Knowledge Base.

Connection mode

Specify how you want to route events from your source to Intercom.

RudderStack supports sending events to Intercom via the following connection modes:

Connection modeWebMobileServer
Device modeSupportedSupported-
Cloud modeSupportedSupportedSupported
info
In a web device mode integration, that is, using JavaScript SDK as a source, RudderStack loads the Intercom native SDK from the https://widget.intercom.io/ domain. Based on your website’s content security policy, you might need to allowlist this domain to load the Intercom SDK successfully.

Configuration settings

After completing the initial setup, configure the following settings to correctly receive your data in Intercom:

  • Send AnonymousId as Secondary UserId: Turn on this option to send anonymousId as the user ID to Intercom when the userId is absent from the event payload.
info

Note that:

  • This setting is applicable only when sending events in cloud mode.
  • It is helpful for tracking anonymous users on your site. For more information on the scenario where this setting is useful, see FAQ section below.
  • 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. Note that this setting is applicable only when sending events in device mode.

Other settings

  • Client-side Events Filtering: This setting lets you specify which events should be blocked or allowed to flow through to Intercom. For more information on this setting, see Client-side Events Filtering.
  • OneTrust Cookie Categories: This setting lets you associate the OneTrust cookie consent groups to Intercom.

Adding device mode integration

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

Identify

The identify call captures the details about a visiting user.

A sampleidentify call is shown:

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 anidentify call, RudderStack creates or updates the user in Intercom.
  • Remove users from a company: To remove users from a company, you can pass remove: true inside the company object:
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:
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)",
})
info
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 traitIntercom property
userId
traits.userId
traits.id
context.traits.userId
context.traits.id
Required, if email is absent.
external_id
traits.email
context.traits.email
Required, if userId is absent.
email
traits.phone
context.traits.phone
phone
traits.avatar
context.traits.avatar
avatar
traits.name
context.traits.name
name
traits.role
context.traits.role
role
traits.ownerId
context.traits.ownerId
owner_id
traits.createdAt
context.traits.createdAt
signed_up_at
traits.unsubscribedFromEmails
context.traits.unsubscribedFromEmails
unsubscribed_from_emails
context.traits.lastSeenAt
last_seen_at
last_seen_at

Identity verification

Intercom’s identity verification feature ensures the privacy of the conversations between you and your users. It also makes sure that one user cannot impersonate another.

info
RudderStack supports the identity verification feature for the events sent through the web device mode.

To use the identity verification feature in web device mode, you can pass user_hash within the integrations object, as shown in the following snippet:

rudderanalytics.identify(
  "1hKOmRA4GRlm", {
    name: "Alex Keener",
    country: "USA"
  }, {
    Intercom: {
      user_hash: "9c56cc51b374c3ba189210d5b6d4bf57790d351c96c47c02190ecf1e430635ab",
    },
  }
);
warning
The user_hash is a SHA256 hash of your Intercom API secret and the userId. Note that this hash is not based on the user’s email.
info
To obtain your Intercom API secret, go to your Intercom dashboard and navigate to Settings > Apps & Integrations > Developer Hub. Then select your app and go to Configure > Basic information. You will find the API secret listed here under Client secret.

Deleting a user

You can delete a user in Intercom using the Suppression with Delete regulation of the RudderStack User Suppression API.

info
To delete a user, you must specify their userId in the event. Additionally, you can specify a custom identifier (optional) in the event.

A sample regulation request body for deleting a user in Intercom is shown below:

{
  "regulationType": "suppress_with_delete",
  "destinationIds": [
    "2FIKkByqn37FhzczP23eZmURciA"
  ],
  "users": [{
    "userId": "1hKOmRA4GRlm",
    "<customKey>": "<customValue>"
  }]
}

Track

The track call lets you track user’s actions along with any properties associated with those actions.

warning
You must identify a user with a valid userId or email before making any track calls to Intercom.

A sample track call is shown below:

rudderanalytics.track("Order Completed", {
  order_id: "140021222",
  email: "alex@example.com",
  checkout_id: "EAP3211",
  products: "Sports Shoes",
  total: 145.99,
  currency: "USD"
})
info

Note that:

  • To send a track call to Intercom successfully, you must include any one of the userId or email fields.
  • RudderStack converts and sends all track event properties as per the Intercom API.

Properties mapping

The following table lists the mapping of the RudderStack track properties to the Intercom properties:

RudderStack propertyIntercom property
userId
traits.userId
traits.id
context.traits.userId
context.traits.id
Required, if email is absent.
user_id
traits.email
context.traits.email
Required, if userId is absent.
email
event
Required
event_name
timestampcreated
propertiesmetadata
properties.id
traits.id
id

Page

The page call lets you record your website’s page views with any additional relevant information about the viewed page.

warning
The page call is supported only for the JavaScript SDK when sending events via 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:

rudderanalytics.page("Best Seller")

Group

The group call lets you link an identified user to a group like a company, organization, or an account. RudderStack uses this information to create or update a company in Intercom using their /companies endpoint.

A sample group call is shown below:

rudderanalytics.group("group123", {
  name: "companyName",
  industry: "IT",
  employees: 450
})
warning
RudderStack requires a groupId (group123 in the above example) to send group events to Intercom. It maps this field to Intercom’s company_id field.

Supported mappings

The following table lists the mapping of the RudderStack group traits to the Intercom properties:

RudderStack traitIntercom property
groupId
Required
company_id
namename
websitewebsite
traits.plan
context.traits.plan
plan
traits.size
context.traits.size
size
traits.industry
context.traits.industry
industry
traits.monthlySpend
context.traits.monthlySpend
monthly_spend
traits.remoteCreatedAt
context.traits.remoteCreatedAt
monthly_spend
traitscustom_attributes

Reset

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

User lookup

RudderStack supports user lookup in identify and group calls. By default, it performs the lookup using the email field. However, you can provide a custom field for the lookup using the event’s integrations object.

warning
Make sure the field you are passing for the lookup is present in the event.

A sample identify event highlighting this feature:

rudderanalytics.identify('1hKOmRA4el9Z', {
  email: 'alex@example.com',
  phone: '+1-202-555-0146',
}, {
  integrations: {
    INTERCOM: {
      lookup: 'phone'
    }
  }
});

Troubleshooting

ErrorReasonSolution
Cannot have more than 120 active event namesYou have sent more than 120 event names in your track calls.

Once the event limit is reached, Intercom does not store any new events and returns this error.
Archive any unused events in your Intercom dashboard by going to Settings > Intercom Data > Events.

See Intercom documentation for more information.

FAQ

Does RudderStack support Intercom’s push notification and deep linking features?

None of the RudderStack SDKs support push notifications and deep linking features currently. See Intercom documentation 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 toggle on the Send AnonymousId as Secondary UserId setting in your RudderStack dashboard to avoid any event loss in such a scenario.


Intercom API v2.10 Migration Details

Configuration changes and differences in sending events when migrating from Intercom API v1.4 to v2.10.


Questions? Contact us by email or on Slack