API Changelog
This represents a log of all changes to the API and the versions that are related to each new addition. To access the latest features, you'll need to change your API version in the Developer Hub.
Getting notified of changes
To be notified of changes, you simply have to create an app in the Developer Hub, or sign up to our community.
Both will mean you get emails from us - whether specifically for community posts (which you can also subscribe to notifications for) or for our dedicated Partner Newsletter.
Some changes may need to be made across multiple versions and therefore are not considered to be released under any one version. We place all of these recent changes here.
Supported HTML in Articles
From now on, additive changes to the HTML content returned by the Articles model will not be considered a breaking change. We will not be introducing new API versions when adding new supported HTML elements or attributes.
Removing element support or changing its shape in a way that causes previously supported HTML to become unsupported will still constitute a breaking change, and a new API version will be introduced in such cases.
We encourage all API consumers reading the contents of the Articles model response to handle any valid HTML in the article body, not just the subset defined in the supported HTML specification. This will ensure your code is resilient in handling any new HTML elements or attributes we may support in the future.
Listed Articles will no longer return statistics
Breaking Change
Articles which have been listed will no longer return a statistics
object. In order to get these statistics, you will now have to take the id
of the article you want to fetch the statistics object for, and retrieve the article individually.
Tables and Horizontal Rules are now supported as Article HTML content
Articles now support both Tables and Horizontal rules. This will mean they will show in the Articles model, and can be added within the body of an Article when creating or updating these using the valid HTML. The Articles endpoint is available from V2.1 upwards.
Text component headers are now bold for Messenger Canvas Kit apps
When a Text component which has a style of header
is now rendered in a Messenger Canvas Kit app on web, the text will automaticaly be bold without need for markdown. This is in an effort to better style the text based on its given purpose, and makes for greater content accessibility.
Obfuscating Twitter data within Conversation objects
Breaking Change
We’ve been informed by Twitter that changes to their API policies mean we’re no longer compliant. As a result, we’ve obfuscated several fields for conversations received from Twitter. This affects all versions of the API for the following models:
Changing id’s to no longer be unique across all workspaces
Breaking Change
To improve performance, we’re making changes to our databases and models, and as a result, id
will no longer be unique across all workspaces.
This means that the only unique identifier you should use is the workspace_id
/app_id
. If you’ve mapped any data to id’s other than the workspace_id
/app_id
, then you should ensure that you are providing the workspace_id
/app_id
alongside, or in place of, other id’s.
We made the change for conversation identifiers in late February — meaning the id
of a conversation will only be unique to a given workspace. We plan to do the same for the id of a conversation_part some time in the future. We are also likely to apply this across several models in the future so we urge you to make the change for all identifiers which don't consider the workspace_id
/app_id
.
Unstable Version
This version is not stable and everything within is subject to change. We recommend using this for test and staging environments, as opposed to within production.
Export Message data through our API
You can use the API to export data for all messages sent in a given timeframe. This data will be valuable in analysing the performance of your messages or joining message engagement data with user data external to Intercom to attribute performance. You can see the three operations you'll have to perform to retrieve this in our reference.
List Tag dependencies on deletion
If a tag has dependencies and cannot be deleted, we will now return an error message listing those dependent objects. Previously, we would have failed without listing dependencies. See the Delete a tag section in our reference for a sample response.
Switch API
You can use the Switch API to deflect phone calls to the Intercom Messenger. Calling this endpoint will send an SMS with a link to the Messenger to the phone number specified.
Conversation Webhook Refactor
With this change, we've updated the webhooks Conversation payloads to match the latest version of the conversation API model.
Webhook payload & topics versioning
We have introduced versioning to webhook payloads and webhook topics.
New Webhook Topics
- Conversations Priority Updated: A webhook which fires when the prority of a conversation is updated
- Granular Unsubscribe: A webhook which fires when a user unsubscribes from message subscription type
- Admin Added to Workspace: A webhook which fires when an admin being added to workspace
- Admin Removed From Workspace: A webhook which fires when an admin being removed to workspace
- Admin Away Mode Updated: A webhook which fires when an admins away mode updates
New Contact Topics
Renamed all user/lead topics to start with a "contact." prefix. We have Versioned User/Lead Topics and Payloads to allowed us to easily update the Contact topics and payloads to more closely align with our current Contact model without breaking any existing apps. Additionaly we have added a new topic "contact.lead.updated" to enable customers and partners to subscribe to changes on leads
Previous Topic Name | Topic | Item Type | Description |
user.deleted | contact.deleted | Contact | Subscribe to contact deletions |
user.email.updated | contact.email.updated | Contact | Subscribe to contact email address being updated |
contact.added_email | contact.lead.added_email | Contact | Subscribe to emails being added to leads |
contact.created | contact.lead.created | Contact | Subscribe to lead creations |
contact.signed_up | contact.lead.signed_up | Contact | Subscribe to leads converting to users |
user.tag.created | contact.lead.tag.created | ContactTag | Subscribe to leads being tagged |
user.tag.deleted | contact.lead.tag.deleted | ContactTag | Subscribe to leads being untagged |
✨!NEW!✨ | contact.lead.updated | Contact | Subscribe to lead updates |
user.unsubscribed | contact.unsubscribed | Contact | Subscribe to contact unsubscriptions from email |
user.unsubscribed_from_sms | contact.unsubscribed_from_sms | Contact | Subscribe to contact unsubscriptions from sms |
user.created | contact.user.created | Contact | Subscribe to user creations |
user.tag.created | contact.user.tag.created | ContactTag | Subscribe to users being tagged |
user.tag.deleted | contact.user.tag.deleted | ContactTag | Subscribe to users being untagged |
Fix for source.author.type field in case of auto message from a team
The source.author.type field in the Conversation Model has been updated to have the value of "team" for cases where a conversation is started with an auto message from a team. Previously the value would be "admin" for this case.
Add fields to the contact model
Add location.country_code
, location.continent_code
, referrer
, utm_campaign
, utm_content
, utm_medium
, utm_source
, and utm_term
to the Contact Model
Update companies
Update companies using Update a Company
Conversation Topic Information in Conversation Response
We've updated our Conversation API to support Conversation Topics as a read-only attribute.
- See top level Conversation Topic data related to conversations within any returned Conversations Model.
Support for Conversation Data Attributes
We've updated both our Conversation and Data Attribute APIs to support the addition of data attributes for conversations.
- See data attributes associated to conversations within any returned Conversations Model.
- Update a conversation's data attribute values through the Conversations API.
- List all data attributes associated to conversations through the Data Attributes API in order to understand which data attributes can be added to conversations.
Breaking Change
We found that it was increasingly important for you to keep persistent context of where a conversation originated from - no matter how many people handled it previously. We also wanted to reduce compexity of identifying which conversations are owned by who, particularly when using the Conversation Search endpoint.
As a result, you can now specify both a team and an admin as assignee's of a conversation. We show both an admin_assignee_id
and a team_assignee_id
in the conversation object. This replaces the assignee
object and is therefore a breaking change. See more on the feature in our Help Center and take a look at our Conversation API reference for example objects.
View the title of a conversation
You can now see the added `title` of a conversation within all returned Conversation objects. This can only be added through the UI, or if a conversation was started via email whereby the subject will be the title. See our Conversation API reference for the updated model.
Redact a conversation part
You can now redact a conversation part or the source message of a conversation. See our Conversation API reference for further detail.
List attached segments for contacts and companies
You can now fetch a list of segments associated to a contact or a company. See our Contacts reference and Companies reference respectitvely to understand more.
Installation Health Check Endpoint
There may be issues that result in your app running into a state where it no longer functions after (or during) installation. In order to alert users and encourage them to solve this, we provide a Health Check which is designed to increase re-activation of your app and decrease any loss in retention.
Our Health Check webhook system sends a request every 24 hours to check on the health of your app. Instead of waiting these 24 hours, we now offer you the possibility to proactively notify us of when an app's state (for a given workspace) might have changed. See our Health Check guide for more on how to make this call.
Introducing the Articles API
We've now released a brand new way for you to access your Articles and Help Center within Intercom - through the API! This includes:
- A fully RESTful Articles endpoint which allows you to create rich & multi-lingual articles, fetch these by retrieving one or listing all, and which can be kept in sync with external repositories through updating their settings and content.
- A fully RESTful Help Center endpoint in order to manage the overall layout of your single-language or multilingual Help Center through the collections and sections under which your Articles live.
Breaking Change
Note that this version includes breaking changes to the API and may require a code change. Major changes include:
- Users API & Leads API are deprecated and replaced with Contacts API.
- Custom Data Attributes can only be created through the Data Attributes API. If you want to update a contact with an attribute that does not exist yet then you must create it through the Data Attributes API and update the contact afterwards.
Contact, Conversation & Data Attribute APIs
We’re excited to share that we’ve now launched a major update to our API - giving you more powerful, contextual, and intuitive access to your data:
- A new, strictly RESTful Contacts API that combines users and leads — collectively known as “contacts” — and enables you to search for the exact contacts you need by filtering using any combination of fields, like location or a custom NPS score. Plus, the API exposes new attributes, like
last_contacted
andbrowser_version
, and uses cursor-based pagination to give you access to all of your contacts without restrictions. - An updated Conversations API that enables you to tag conversations directly, search and retrieve conversations by any combination of fields, and access more granular attributes, like timestamps and out-of-the-box metrics such as
time_to_first_response
andmedian_time_to_reply
. - A new Data Attributes API that lets you create and update custom data attributes, set a label and description for each, and build a dropdown list of defined attribute options. This means your app users can more easily leverage data when targeting and communicating with customers and leads.
Breaking Change
Note that this version includes breaking changes to the API and may require a code change. See below for more details.
Listing Data Attributes
We've modified the way data attributes are retrieved via our Data Attributes API. You can now retrieve a list of all data attributes by sending a GET request to the data_attributes
endpoint.
- Listing customer data attributes - you can list customer data attributes by specifying a
model
parameter in the request URL with the valuecustomer
. - Listing company data attributes - you can list company data attributes by specifying a
model
parameter in the request URL with the valuecompany
.
With the introduction of this change, customer and company data attributes can no longer be listed by using the old endpoints. For example, sending a request to the data_attributes/customer
endpoint and sending a request to the data_attributes/company
will no longer work.
Validating Custom Data Attributes
Custom Data Attributes created via the API must now use the same naming rules as the ones created via the UI. Names can therefore only contain alphanumeric characters, currency symbols, and hyphens.
Adding owner_id to User & Lead objects
We now expose a user or lead's account owner through the `owner_id` attribute. This will be the integer for an admin's id, meaning you can use this to make a call to our Admin API and get more details on the given owner.
Removing archived Custom Data Attributes from User responses
Archived Custom Data Attributes will no longer be present on the User model in API responses.
Removing Teams from Admin responses
The Admins endpoint will no longer return Teams in its responses. The Teams endpoint should be used instead.
Breaking Change
Note that this version includes breaking changes to the API and may require a code change. See below for more details.
Introducing Canvas Kit
Say hello to a quicker and easier way to build contextual and action-oriented apps embedded into Intercom's UI. With the launch of Canvas Kit, you keep all the capabilities of embedding apps in the Messenger, and gain:
- Capbilities for emebedding apps in Inbox - you can now build apps for the conversation details within Intercom's Inbox product. Take a look at our revampped Canvas Kit guides to understand just how easy it is.
- New Components - to make it easy to display data and input larger voucher, we've launched Data Table and Text Area components.
- Canvas Kit Builder - preview the JSON of your app to see what it will look like and how people can interact with it. The Builder is embedded throuhgout the docs but can also be accessed here.
Removing the users object from Canvas Kit request payloads
Instead of sending a users
object within Canvas Kit requests, we now send a customer
object instead. This returns exactly the same payload but also includes leads.
Removing the app_id key from Canvas Kit request payloads
Instead of sending an app_id
key within Canvas Kit requests, we now send a workspace
key instead. This returns exactly the same information as the value.
Adding an author object to Conversation payloads
We now return an author
object within Conversation and Conversation Part objects sent throughout our REST API responses and Canvas Kit requests. This will contain the name
and email
of the message's author.
Preventing null for unsubscribed_from_emails
The API will now return an error if unsubscribed_from_emails
is set to null
for User requests.
Removing personally identifiable information (PII) from our API & Webhooks
Across our API & Webhooks, we will no longer return the last_seen_ip
, location_data.longitude
, location_data.latitude
, and user_agent_data
for users, leads, and visitors. This is part of an effort to keep customers data secure and uphold the availability of Intercom across services that require such information to not be exposed.
View activity logs for admins through our API
You can now get a log of activities taken by all admins in an app through our API. Simply send a GET request to https://api.intercom.io/admins/activity_logs
. You can see request, params, and responses on our reference.
Set waiting since attribute to null for admin replies
In previous versions of our API, the value of the waiting_since
attribute on the Conversation model is set to 2000 years in the future if the last reply is from an admin. This change sets the value of waiting_since
to null
instead.
List users by email returns users only
Previously, the list users by email endpoint returned a list of users and contacts. It will now return users only.
Allow contacts to be viewed/listed by phone
Previously, the you could list contacts by email only. Now you can also list them by phone.
New Conversations Part Redacted Webhook
There is a new webhook which fires when a conversation part is redacted.
New Conversations Rating Added Webhook
There is a new webhook which fires when a rating is added to a conversation.
The full list of changes in this version is:
- Users endpoint - Find multiple users via email
- Conversations endpoint - Adding more information for the user's first reply
- Messenger framework -
new_canvas
no longer accepted - Messenger framework - Disable component option
- Webhooks - Four new webhook topics added
Breaking change
Note that this version includes a breaking change to the API and may require a code change if you are using this feature:
users endpoint - search via email, we now returns a list
with zero or more entries, whereas previously it returned a user object
Messenger framework - new_canvas
no longer accepted
Users endpoint - Find multiple users via email
Previously if you searched for a user via email it would return an error if more than one user existed with the email. It returned a user object. Now it will return the same list object as with list users.
curl https://api.intercom.io/users?email=[email protected] \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Accept: application/json' \
-H 'Intercom-Version: 1.1'
{
"limited": false,
"pages": {
"next": null,
"page": 1,
"per_page": 50,
"total_pages": 1,
"type": "pages"
},
"total_count": 3,
"type": "user.list",
"users": [
{
"anonymous": false,
"app_id": "fyq3wodw",
"created_at": 1506339558,
"custom_attributes": {},
"do_not_track": null,
"email": "[email protected]",
"has_hard_bounced": false,
"id": "45c8eae6fac10f5584e7508e",
"last_request_at": 1529737920,
"last_seen_ip": "78.144.182.179",
....
....
},
{
"anonymous": true,
"app_id": "fyq3wodw",
"created_at": 1503488750,
"custom_attributes": {},
"do_not_track": null,
"email": "[email protected]",
"has_hard_bounced": false,
"id": "5123d6aeeda850883ed8ba7c2",
"last_request_at": 1503488749,
....
....
},
{
"anonymous": false,
"app_id": "fyq3wodw",
"created_at": 1494940172,
"custom_attributes": {},
"do_not_track": null,
"email": "[email protected]",
"has_hard_bounced": false,
"id": "789afa0cb781d52fd3044ecc",
"last_request_at": 1494940211,
....
....
}
]
}
{
"limited": false,
"pages": {
"next": null,
"page": 1,
"per_page": 50,
"total_pages": 0,
"type": "pages"
},
"total_count": 0,
"type": "user.list",
"users": []
}
Conversations endpoint - Adding more information for user's first reply
It is now possible to get more information about your users first response. Customer have asked for this feature so they can better understand key metrics which may help identify patterns around what encouraged your customers to reply to a particular message. Similarly, it will also allow you to prioritise messages based on whether they were delivered as Auto-Messages
, Bot messages
or Manual Messages
for example.
The new information will be available in the conversation model object returned when you list your conversations. It will contain:
- Source URL - The URL for the page from where your customer replied. This will not be available in all cases, e.g. when a customer replies via email.
- Channel - The channel the replay occurred within e.g. via email, in a conversation or via a 3rd party integration such as twitter or facebook
- Created at time - The time the users response was created
- How was the original message delivered - Was it an
Auto-Message
or aCampaigns Message
or aManual Message
for example.
Conversation list
There is no change to how your list conversations. We have just added some new attributes to the conversation model returned.
New or updated Attributes
The conversation model will include the follow new attributes
customer_first_reply
Object
An object containing information on the first users message. For a user initiated message this will represent the users original message.
type
String
This has been updated and now includes conversation
, push
, facebook
, twitter
and email
delivered_as
String
How was the message delivered by Intercom. They types of delivery are customer_initiated
, automated
, campaigns_initiated
, admin_initiated
, and operator_initiated
.
"delivered_as" message types explained
customer_initiated means this message was delivered as a user initiated message
automated means the message was delivered as either a visitor auto message or an automated message
campaigns_initiated means the message was delivered as a campaigns message
operator_initiated means the message was delivered as a bot auto message
admin_initiated means the message was delivered as an admin initiated message
Channel
String
Over which channel did the first reply occur. Options include conversation
, push
, facebook
, twitter
and email
URL
String
The URL where the first reply originated from. In some cases, e.g. email replies this will be blank.
Created_at
Timestamp
The time the users messages was created. This is in unix timestamp format
"customer_first_reply" set to null
If a user has not replied to an Intercom initiated message (e.g. auto messages, admin initiated messages, campaigns) then the customer_first_reply
attribute will be null
# You still list conversations in the same way. The only change is there are some new attributes added as part of the conversation message.
curl "https://api.intercom.io/conversations" \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Accept: application/json' \
-H 'Intercom-Version: 1.1'
{
"conversations": [
{
"assignee": {
"id": null,
"type": "nobody_admin"
},
"conversation_message": {
"attachments": [],
"author": {
"id": "5bd155b5d8b61587a0203f31",
"type": "lead"
},
"body": "<p>\ud83d\ude00</p>",
"delivered_as": "customer_initiated",
"id": "271978806",
"subject": "",
"type": "conversation",
"url": "https://s.codepen.io/test/app"
},
"created_at": 1540449375,
"customer_first_reply": null,
"customers": [
{
"id": "5bd112b5d8b61534a0203f12",
"type": "lead"
}
],
"first_action_at": 1540449375,
"id": "19205537453",
"last_action_at": 1540449378,
"open": true,
"read": true,
"sent_at": 1540449378,
"snoozed_until": null,
"state": "open",
"type": "conversation",
"updated_at": 1540449379,
"user": {
"id": "5bd112b5d8b61534a0203f12",
"type": "lead"
},
"waiting_since": 1540449375
},
...
...
...
],
"pages": {
"next": "https://api.intercom.io/conversations?per_page=20&page=2",
"page": 1,
"per_page": 20,
"total_pages": 76,
"type": "pages"
},
"type": "conversation.list"
}
{
"conversations": [
{
"assignee": {
"id": null,
"type": "nobody_admin"
},
"conversation_message": {
"attachments": [],
"author": {
"id": "814865",
"type": "admin"
},
"body": "<p>Hi \ud83d\ude00 We hope you enjoy the example app. To get started just copy and paste some code into the JS editor. Let us know if you think this is useful? <br></p>",
"id": "55951247",
"subject": "",
"type": "conversation_message",
"url": null
},
"created_at": 1540314098,
"customers": [
{
"id": "1234bea776767676676bae2334",
"type": "lead"
}
],
"first_action_at": 1540314131,
"id": "19179279317",
"last_action_at": 1540314133,
"open": true,
"read": true,
"sent_at": 1540314133,
"snoozed_until": null,
"state": "open",
"type": "conversation",
"updated_at": 1540314134,
"user": {
"id": "aa444f2314fe1334r345",
"type": "lead"
},
"waiting_since": 1540314131
},
...
...
],
"pages": {
"next": "https://api.intercom.io/conversations?per_page=20&page=2",
"page": 1,
"per_page": 20,
"total_pages": 15,
"type": "pages"
},
"type": "conversation.list"
}
Conversations endpoint - Adding more information to tags
It is now possible to get more information about the conversation's tags when both fetching one conversation and listing all conversations. There's two new attributes you can see in the tag object of a conversation:
applied_at
UNIX Timestamp
The date and time when the tag was applied to the conversation.
applied_by
Object
Contains the id
of the admin
that applied the tag.
Messenger framework - new_canvas
no longer accepted
During the beta launch of the Messenger framework we accepted both new_canvas
and canvas
as valid names for the canvas
object returned to Intercom during the request flows. The new_canvas
name is no longer accepted as a valid name for the canvas
object.
Messenger framework - Disable component option
This version includes the ability to disable certain messenger framework components
. This allows you to prevent certain components
, such as elements in a list, from being selected. This may occur when customers are signed up to certain packages and have restricted options for some categories. The components
which you can now disable are:
- Input
- Button
- List + each list item
- Dropdown + each dropdown option
- Single Select + each single select option
For each of the above components it simply adds one optional boolean parameter which can be set to identify whether thiscomponent
should be disabled or not
disabled
Boolean
No
'true' indicates the component is disabled. This is set to 'false' by default.
{
"type": "button",
"id": "button-123",
"label": "Submit form",
"style": "secondary",
"disabled": true,
"action": {
"type": "url",
"url": "https://www.intercom.com/"
}
}
{
"type": "list",
"items": [
{
"type": "item",
"id": "article-123",
"title": "How to install the messenger",
"subtitle": "An article explaining how to integrate Intercom",
"image": "http://somesite.com/article.png",
"image_width": 48,
"image_height": 48,
"roundedImage": false,
"action": {
"type": "submit"
}
},
{
"type": "item",
"id": "article-133",
"title": "How to un-install the messenger",
"subtitle": "An article explaining how to uninstall Intercom integrations",
"image": "http://somesite.com/article2.png",
"image_width": 48,
"image_height": 48,
"roundedImage": false,
"disabled": true,
"action": {
"type": "submit"
}
}
]
}
New webhook topics
This version includes a number of new webhook topics to which you can now subscribe. The new topics are described in the table below. To find out more about webhooks and learn how to subscribe to these topics please see our Setting up Webhooks page.
conversation.admin.snoozed
Conversation
Subscribe to admin conversation snoozes
conversation.admin.unsnoozed
Conversation
Subscribe to admin conversation unsnoozes
contact.tag.created
ContactTag
Subscribe to leads being tagged.
contact.tag.deleted
ContactTag
Subscribe to leads being tagged.
This is the base version of the API that existed before versioning was introduced.
Updated 16 days ago