Intercom v2 Cloud Mode Integration

After you have successfully instrumented Intercom v2 as a destination in RudderStack, follow this guide to correctly send your events to Intercom in cloud mode.

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

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

Identify

You can use the identify call to create or update an user in Intercom.

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)",
})

Remove user from company

To remove users from a company, pass remove: true in the company object, as shown:

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 user

To unsubscribe users from emails, pass unsubscribedFromEmails: true in 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)",
})

Associate user with a company

To link a user to a company, use the group call.

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:

Track

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

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

A sample track call sent to Intercom is shown:

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

Note that:

• You must include any one of the userId, email, or id fields to send a track call to Intercom successfully.
• 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:

Group

The group call lets you link an identified user to a group like a company, organization, or an account. Along with that, you can add tags to a company.

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
})

Note that 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:

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.

Note that:

• You can only send the fields accepted by Intercom for user lookup. These fields are case sensitive.
• The field you pass for the lookup must be 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

Send custom attributes

You need to ensure that the custom attributes you are sending to Intercom in your identify and group events are defined in the Intercom dashboard already. Otherwise, your events might fail.

RudderStack supports sending custom attributes (custom_attributes) to Intercom at a user and company level (identify and group calls).

Intercom validates the custom attribute first, meaning it throws an error if a custom attribute present in the event is not defined in the Intercom dashboard already.

See the Intercom documentation for more information on creating and sending custom attributes to Intercom.

Use case

The following use case highlights how RudderStack considers and sends custom attributes to Intercom.

Suppose you send the following identify call to Intercom:

rudderanalytics.identify(
  "alex98", {
    name: "Alex Keener",
    createdAt: "2024-01-05T19:11:00.337Z",
    email: "alex@example.com",
    phone: "+800 555‑0100",
    address: {
      city: "New Orleans",
      state: "Louisiana",
    },
    plan: "enterprise",
  }, {
    integrations: {
      INTERCOM: {
        lookup: "phone",
      },
    },
  });

RudderStack extracts the following standard Intercom attributes from the event payload:

• userId
• email
• phone
• name
• createdAt

RudderStack considers all the other attributes/properties as custom attributes.

Note that if the custom attributes are a part of an object, then RudderStack flattens them, so the custom_attribute object in the final event payload sent to Intercom looks like the following:

"custom_attributes": {
  "address_city": "New Orleans",
  "address_state": "Louisiana",
  "plan": "enterprise"
}

Make sure to create the above custom attributes in the Intercom dashboard to successfully send the events.

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. RudderStack will drops the event if none of these fields are present in the event.

RudderStack recommends toggling on the Send AnonymousId as Secondary UserId setting in your RudderStack dashboard to avoid any event loss in such a scenario.

Questions? Contact us by email or on Slack