Intercom API v2.10 Migration Details
Configuration changes and differences in sending events when migrating from Intercom API v1.4 to v2.10.
9 minute read
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.
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.
Configure the following settings to set up Intercom as a destination in RudderStack:
Destination info | |||
---|---|---|---|
|
Connection modes | |||
---|---|---|---|
Source | Cloud mode | Device mode | Hybrid mode |
AMP | |||
Android | |||
Cloud | |||
Cordova | |||
Flutter | |||
iOS | |||
React Native | |||
Shopify | |||
Unity | |||
Warehouse | |||
Web |
Supported message types | ||||||
---|---|---|---|---|---|---|
Source | Identify | Page | Track | Screen | Group | Alias |
Cloud mode | ||||||
Supported sources | ||||||
Device mode | ||||||
Android | ||||||
iOS | ||||||
Web |
In the 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.
After completing the initial setup, configure the following settings to correctly receive your data in Intercom:
anonymousId
as the user ID to Intercom when the userId
is absent from the event payload.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.
Depending on your platform of integration, follow the steps below to add Intercom to your project:
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)",
})
identify
callsYou can use the identify
call to create or update user information in Intercom, as explained below:
identify
call, RudderStack creates or updates the user in Intercom.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)",
})
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)",
})
group
call.RudderStack does not support Intercom’s Last Seen feature currently.
The following table lists the mapping of the RudderStack traits to the Intercom properties:
RudderStack trait | Intercom 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 |
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.
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",
},
}
);
Theuser_hash
is a SHA256 hash of your Intercom API secret and theuserId
. Note that this hash is not based on the user’s email.
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.
You can delete a user in Intercom using the Suppression with Delete regulation of the RudderStack User Suppression API.
To delete a user, you must specify theiruserId
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>"
}]
}
The track
call lets you track user’s actions along with any properties associated with those actions.
You must identify a user with a validuserId
ortrack
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"
})
Note that:
- To send a
track
call to Intercom successfully, you must include any one of theuserId
or- RudderStack converts and sends all
track
event properties as per the Intercom API.
The following table lists the mapping of the RudderStack track
properties to the Intercom properties:
RudderStack property | Intercom 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 |
timestamp | created |
properties | metadata |
properties.id traits.id | id |
The page
call lets you record your website’s page views with any additional relevant information about the viewed page.
Thepage
call is supported only for the JavaScript SDK when sending events via device mode. It works by triggering Intercom’supdate
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")
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
})
RudderStack requires agroupId
(group123
in the above example) to sendgroup
events to Intercom. It maps this field to Intercom’scompany_id
field.
The following table lists the mapping of the RudderStack group
traits to the Intercom properties:
RudderStack trait | Intercom property |
---|---|
groupId Required | company_id |
name | name |
website | website |
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 |
traits | custom_attributes |
context.traits.tags | Maps to tag names in Intercom |
The reset
method resets the previously identified user and any related information.
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 are passing 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'
}
}
});
Error | Reason | Solution |
---|---|---|
Cannot have more than 120 active event names | You 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. |
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.
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.
Configuration changes and differences in sending events when migrating from Intercom API v1.4 to v2.10.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.
Questions? Contact us by email or on Slack