Intercom API v2.10 Migration Details

This changelog contains the implementation and configuration changes while migrating your Intercom cloud mode integration from Intercom API v1.4 to v2.10.

For the existing users of the Intercom destination integration (based on API v1.4), the RudderStack team will do all the necessary migrations internally.

Configuration changes

The following configuration settings are removed from the RudderStack dashboard as they are no longer supported in Intercom API v2.10:

The following configuration setting is added:

Events-related changes

Make sure to review the following sections to accurately send your events to Intercom.

Set the API server

A new configuration setting API Server is introduced in the new Intercom implementation. For migrating all the existing destination integrations, RudderStack will set this field to Standard by default.

If you have an existing Intercom destination integration and your Intercom regional hosting is either EU or AU, make sure to update this setting in the dashboard.

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

In the older implementation leveraging 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 implementation, 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.

For more information on creating and sending custom attributes to Intercom, see the Intercom documentation.

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

First, 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.

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 Intercom version, 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.1. To update the last seen timestamp of a contact, you can send the lastSeenAt field in the event payload.

Questions? Contact us by email or on Slack