Intercom API v2.10 Migration Details
Configuration changes and differences in sending events when migrating from Intercom API v1.4 to v2.10.
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:
Setting | Comments |
---|
Include Context with Identify Calls | - |
Enable this to update the last seen to the current time | Used to enable the update_last_request_at parameter in Intercom. |
The following configuration setting is added:
Setting | Comments |
---|
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). |
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
Standard Intercom attributes for identify
and group
calls
Identify
userId
role
email
phone
name
avatar
company
ownerId
lastName
lastname
firstName
firstname
createdAt
timestamp
lastSeenAt
originalTimestamp
unsubscribedFromEmails
Group
tags
size
plan
name
email
userId
website
industry
segments
userCount
createdAt
sessionCount
monthlySpend
remoteCreatedAt
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