Intercom API v2.10 Migration Guide

This guide covers the steps to migrate your Intercom cloud mode integration from Intercom API v1.4 to v2.10.

Step 1: Change Intercom API version

In the Intercom destination settings, change the Intercom REST API Version connection setting from 1.4 to latest.

Step 2: Review connection settings

Once you set the Intercom REST API Version to latest, note that the following configuration setting will not be visible in the RudderStack dashboard as it is no longer supported in Intercom API v2.10:

Instead, the following new connection setting is added:

Step 3: Review instrumentation changes

After reviewing the configuration changes, follow these sections to send your events to Intercom correctly:

Send custom attributes

If you’re migrating your Intercom destination integration from v1.4 to the latest version v2.10, make sure that the custom attributes that you wish to send to Intercom via the identify and group events are already defined in the Intercom dashboard. Otherwise, your events might fail.

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

In the older integrations leveraging the Intercom API v1.4, you could send a custom attribute that was not defined in the Intercom dashboard already. Intercom did not validate the attribute and created a new custom attribute instead.

In the new integration that leverages the Intercom API v2.10, Intercom validates the custom attributes first, meaning it throws an error if a custom attribute present in the event is not already defined in the Intercom dashboard.

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 in the new API implementation.

Suppose you send the following identify event 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 and considers all the other attributes as custom attributes:

• userId
• email
• phone
• name
• createdAt

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 all the above custom attributes in the Intercom dashboard to successfully send the events.

Attribute lookup

RudderStack supports user lookup in the identify and group calls. By default, it does a lookup based on the user’s email. However, you can change this behavior by passing the required field in the integrations object.

For a successful lookup, make sure to pass a valid field with its value present in the event payload.

A sample identify call highlighting the user lookup:

rudderanalytics.identify(
  "alex98", {
    name: "Alex Keener",
    email: "alex@example.com",
    phone: "+800 555‑0100"
  }, {
    integrations: {
      INTERCOM: {
        lookup: "phone",
      },
    },
  });

Send last seen timestamp

In the older implementation leveraging Intercom API v1.4, RudderStack supported the Enable this to update the last seen to the current time dashboard setting that lets you enable the last seen timestamp (update_last_request_at parameter) for a contact in Intercom.

This feature is no longer supported in the new Intercom API v2.10. To update the last seen timestamp of a contact, you will need to include the lastSeenAt field in the event.

Questions? Contact us by email or on Slack