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 or set a version in the header of your API call.

About breaking changes in the Intercom API

The Intercom API is a versioned API. The version number increments by 0.1 each release, unless we introduce major new functionality, in which case we will increment by 1. We do not follow Semantic Versioning.

Any breaking changes will be released in a new API version. Breaking changes are changes that can potentially break an integration. Breaking changes can include:

  • removing an entire operation
  • removing or renaming a parameter
  • removing or renaming a response field
  • adding a new required parameter
  • making a previously optional parameter required
  • changing the type of a parameter or response field
  • removing enum values
  • adding a new validation rule to an existing parameter
  • changing authentication or authorization requirements


ChangelogRelease dateDocs
Recent unversioned changesN/AN/A

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.

Recent unversioned changes

April 2023

conversation_part IDs are no longer unique across all workspaces

❗️ Breaking change

As flagged in a previous update, we're making changes to our databases and models, and as a result, the id of a conversation_part will no longer be unique across all workspaces. We're continuing to make this change for other models, and we urge you to make the change for all identifiers which don't consider the workspace_id/app_id.

Previous updates

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