Some changes may need to be made across multiple versions and therefore are not considered to be released under any one version. You can find details of those changes here.
Breaking changes listed below are prepended with a ❗️symbol. For more details on the Intercom API policy around breaking changes see the details on the API Changelog information page
From 16 November 2026, List execution results and Retrieve an execution result return request_body, response_body and raw_response_body only when the request comes from an app your workspace owns. An app your workspace owns is one created in your workspace's Developer Hub. An app created in another workspace, such as a separate development workspace, is not, even when you install it in yours. Requests through the Intercom MCP server also receive them.
Apps owned by another workspace, including apps installed from the App Store, receive the same response without these three fields. This applies even when they pass include_bodies=true. The request still succeeds, and every other field is unchanged.
Execution results can contain your end users' data and credentials sent to or returned by your other systems. If you build an integration that needs these bodies, contact us.
This change applies to all API versions.
You can now give an app the create_update_articles OAuth scope to read, create, update and publish Help Center articles, collections and sections without being able to delete them. It grants:
- Articles: list, retrieve, search, create and update, and retrieve, update and publish a draft
- Article versions: list and retrieve
- Help Center collections and sections: list, retrieve, create and update
- Help centers: list and retrieve
- Article tags: attach and detach
It does not grant deleting articles, collections or sections, any access to internal articles or folders, or POST /content/bulk_actions. An app with this scope can still set an article's folder_id when it creates or updates the article. On Preview, setting url_redirects on an article replaces its existing redirects, so it also needs read_write_help_center_redirects_scope. Without it, the request returns 401.
An app's scopes add together, so an app with both create_update_articles and read_write_articles_scope can still delete. To allow writes without deletes, give the app create_update_articles instead of read_write_articles_scope. An access token keeps the scopes it was issued with until it is regenerated after the app's scopes change.
The descriptions of two existing scopes now state everything they allow. Their behaviour is unchanged:
read_write_articles_scope— Read, create, update and delete Help Center articles, collections and sections, internal articles and folderswrite_content— Bulk-modify or bulk-delete articles, content snippets, external pages, uploaded files and internal articles, and upload, update or delete products in an ecommerce catalog
This change applies to all API versions.
POST /contacts/bulk/delete and POST /companies/bulk/delete now accept up to 1,000 items per request, up from 100. Requests with more than 1,000 return a 422 error with the message maximum number of contacts per request is 1000 (or companies). The limit on bulk create and bulk update is unchanged at 100.
This change applies to API versions 2.17 and above for contacts, and to Preview for companies.
From 23 November 2026, creating a ticket will no longer send a ticket.state.updated webhook. Creating a ticket will send only ticket.created, which already includes the ticket's starting state. ticket.state.updated will continue to be sent whenever a ticket's state changes after it has been created.
If you use ticket.state.updated to learn about new tickets, subscribe to the ticket.created topic before 23 November 2026.
The POST /messages reference page now describes what happens when from is a user or lead instead of an admin. The request is not rejected: it creates a conversation initiated by that contact, as POST /conversations does, and the to, cc and bcc fields are ignored. To create a conversation initiated by a contact, use POST /conversations.
This is a documentation update for API versions 2.10 and above. The API's behavior has not changed.
POST /fin/start, POST /fin/reply, POST /fin/ask, POST /fin/procedures/{procedure_id}/run and POST /fin/csat now return 422 errors about the conversation ID under the conversation_id key, matching the request parameter, instead of external_conversation_id. A missing or blank conversation_id now returns the message Conversation ID is required.
This change applies to API versions 2.14 and above.
POST /fin/start, POST /fin/ask and POST /fin/procedures/{procedure_id}/run now accept an optional environment parameter. If your Fin for Platforms workspace has environments, pass an environment's identifier, the same value you use for messenger_environment in your Messenger installation, to start the conversation in that environment instead of the workspace's default. An identifier that matches no environment returns a 422 error with the message Invalid environment. If your workspace has no environments, omit the parameter.
This is an additive change that applies to API versions 2.14 and above.
See the Fin Agent API guide for full documentation.
POST /fin/start, POST /fin/ask and POST /fin/procedures/{procedure_id}/run now accept up to 20 attributes in conversation_metadata.attributes, up from 10. Requests with more than 20 return a 422 error with the message Conversation attributes cannot contain more than 20 items. The limit on user attributes is unchanged at 10.
This is an additive change that applies to API versions 2.14 and above.
See the Fin Agent API guide for full documentation.
Requests that the Intercom MCP server makes to the REST API on behalf of a teammate are now limited to what that teammate can do in Intercom. They follow the same permissions and seat rules as the Intercom app. For example, searching conversations needs a seat with full Inbox access, just as conversation search in the Inbox does.
A request the teammate is not permitted to make returns a 403 error with the code action_forbidden. The error's data.required_permissions lists the permissions that would allow it; holding any one of them is enough. For example:
{
"type": "error.list",
"request_id": "...",
"errors": [
{
"code": "action_forbidden",
"message": "Not authorized to access resource",
"data": { "required_permissions": ["access_core_inbox"] }
}
]
}To resolve it, ask a workspace admin to give the teammate the missing permission or a seat that includes it. Requests made with an access token or OAuth app outside the MCP server are not affected.
This change applies to all API versions.
The fin_replied event's message object now includes an optional sources array listing the content Fin used to generate its reply, in the same order as the [n] citation markers in message.body. Each source has a title, a type (article or external), and a url. The array is present only when Fin cited content.
This is an additive change that applies to API versions 2.14 and above.
See the Fin Agent API guide for full documentation.
The Fin Agent API endpoints that create or continue a conversation now return intercom_conversation_id, the internal Intercom conversation ID. Use it to match an Agent API session to the conversation as it appears in Intercom — in the Inbox, in the Conversations API, and in reporting.
On 2.14, 2.15 and 2.16 this affects POST /fin/start and POST /fin/reply. On Preview it also affects POST /fin/ask and POST /fin/procedures/{procedure_id}/run; POST /fin/escalate returns it only when the escalation creates a conversation.
This is an additive change that applies to API versions 2.14 and above.
See the Fin Agent API guide for full documentation.
The Reply to a ticket endpoint (POST /tickets/{id}/reply) rejects message_type: comment on tracker tickets, and on back-office tickets that are not shared with the customer. These requests return a 400 error with the code parameter_mismatch.
Use message_type: note on these ticket types instead.
This change applies to all API versions.
Requests that hit an Elasticsearch rate limit during a period of high load now return a 429 Too Many Requests error with a Retry-After header, instead of an unhandled 500 error. Retry after the number of seconds given in Retry-After.
This change applies to all API versions.
The webhook topics that stream events for every user, lead, visitor and company in a workspace no longer accept the Read one user and one company (read_single_user) permission. This affects 43 topics across the company.*, contact.*, user.*, visitor.* and granular.* families, some of which are not listed in the reference tables. Subscribing to them now requires Read and list users and companies (read_users_companies) or Read and write users (read_write_users). The webhook topic reference lists the permissions that apply to each topic it documents.
If your app requests only Read one user and one company:
- Creating or updating a subscription to these topics returns
403. This includes an update that does not change the topic list. - Existing subscriptions keep delivering until your app's webhook definition is next rebuilt — on an install, an uninstall, or a save on the Webhooks page of your Developer Hub — at which point the affected topics are dropped.
- The Webhooks page reports a missing permission on these topics immediately.
- To keep them, add Read and list users and companies to the permissions your app requests. Because that widens your app's permission set, every workspace that has installed your app must re-authorize it before the change takes effect.
This change applies to all API versions.
The Fin Voice call response now includes an attributes object listing the conversation attributes Fin classified during the call, as attribute name to value. This sits alongside the existing intent array, which is unchanged. attributes is an empty object when the number has no classification attributes configured, or when none were set on the call.
This affects registerFinVoiceCall, collectFinVoiceCallById, collectFinVoiceCallByExternalId, collectFinVoiceCallByPhoneNumber, and collectFinVoiceCallsByConversationId.
This is an additive change that applies to API versions 2.15 and above.
The Fin Voice call response now includes a data field — the metadata object you supplied when registering the call, returned back verbatim. data is an empty object when no metadata was supplied.
This affects registerFinVoiceCall, collectFinVoiceCallById, collectFinVoiceCallByExternalId, collectFinVoiceCallByPhoneNumber, and collectFinVoiceCallsByConversationId.
This is an additive change that applies to API versions 2.15 and above.
An app's access to conversations through the API is now limited by the conversation access of the teammate who installed it, in addition to the app's OAuth scopes. For a public app, that is the teammate who authorized the app through OAuth. For a private app, it is the teammate who installed the app on the workspace, or who last regenerated its Access Token.
If that teammate's conversation access is limited, for example to conversations assigned to them or to their teams:
- Requests that act on a single conversation outside their access return a
403error with the codetoken_unauthorizedand the messageNot authorized to access this conversation. This affects the Retrieve, Update, Delete, Reply to, Manage, Merge and Convert a conversation endpoints, redacting a conversation part, attaching and detaching a conversation's contacts and tags, updating a conversation part, and the other endpoints that act on a single conversation. - List and search return only the conversations the teammate can access.
conversation.*webhook topics are delivered only for conversations the teammate can access.
Teammates with access to All conversations, the default, are not affected. To let an app work across all conversations, have it installed by a teammate with that access. Changes to a teammate's conversation access apply to the app's requests straight away. See Conversation access is limited by the installing teammate for details.
This change applies to all API versions.
The Fin Agent API adds a new POST /fin/csat endpoint that records a customer's satisfaction rating for a conversation, with an optional free-text remark. A new csat_requested event, delivered over webhooks or SSE, carries the rating options to present to the user before you submit their choice.
This is an additive change that applies to API versions 2.14 and above.
See the Fin Agent API guide for full documentation.
The Create contact (POST /contacts) and Update contact (PUT /contacts/{id}) endpoints now document that the signed_up_at and last_seen_at fields accept a Unix timestamp in seconds. The accepted format is unchanged.
This applies to all API versions.
The Update a conversation endpoint (PUT /conversations/{id}) now returns a 400 INVALID_PARAMETER error when the request includes custom_attributes and your workspace contains multiple non-archived conversation custom attributes with the same name. Previously, the update would silently apply to a non-deterministic attribute, which could result in the value being written to a different attribute than the one shown in the UI.
To resolve the conflict, rename or archive the duplicate attribute so each name is unique, then retry the request. You can do this through:
- The Conversation Attributes API (Preview only) — list with
GET /conversations/attributes, then rename withPUT /conversations/attributes/{id}or archive withDELETE /conversations/attributes/{id} - Your workspace settings (Settings → Data → Conversations)
This change applies to all API versions.
The fin_replied event's message object now includes an optional id field — a unique identifier for the message.
This is an additive change that applies to API versions 2.14 and above.
See the Fin Agent API guide for details.
The Reply to a ticket endpoint now documents the cross_post boolean parameter. When set to true on a note message type reply to a back-office ticket, the note will be automatically cross-posted to all linked conversations connected through the ticket's message thread.
Requirements:
- The ticket must be a back-office ticket
- The
message_typemust benote - The reply must be from an admin (
type: admin)
The POST /contacts/{id}/companies endpoint now returns a 400 Bad Request error with code contact_company_limit_exceeded when a contact has reached the maximum of 1000 company associations. Previously, the API returned 200 but silently dropped the new association. Re-adding a company that is already associated with the contact continues to return 200 successfully.
We've fixed the published_at parameter in the newsfeed_assignments array so it now works correctly when creating and updating news items:
{
"news_item": {
"title": "Halloween is here! 👻",
"body": "<p>New costumes in store for this spooky season</p>",
"newsfeed_assignments": [
{
"newsfeed_id": 1,
"published_at": 1677638214
}
]
}
}You can now successfully set custom published dates for news items, allowing news items to have historic published dates.
You can now access additional metadata for conversations where an AI Agent was involved as part of the Conversations API.
When ai_agent_participated is true, data in the ai_agent object will be populated, including:
source_type: How the AI Agent involvement was triggered, likeworkfloworfin_previewsource_title: The title of theprofileorworkflowlast_answer_type: The type of the last answer delivered in the conversation, likeai_answerorcustom_answerresolution_state: The resolution outcome from AI Agent's participation in the conversation, such asconfirmed_resolutionorrouted_to_teamrating: The Customer Satisfaction (CSAT) rating provided from 1-5. Note that you will need to enable Fin AI Agent CSAT in order to gather this ratingrating_remark: The user's rating as a comment, if they left onecontent_sources: A list of content sources that were used by the AI Agent in the conversation
You can export and save this data for compliance and legal reasons, send it to your data warehouse, and use it in your own BI tools for further analysis and visualization.
Try it on the Conversations API get a conversation, list conversations, and search conversations pages or in your own terminal.
When you create or reply to a conversation via the API, you now have the option to define your own created_at timestamps.
This is especially useful if you are importing conversations data from another source. Try it out using the Create a Conversation or Reply to a Conversation endpoints.
Now when you create a Ticket, you can add the company_id that should be associated with the Ticket.
This is especially useful if you are importing conversations data from another source or if you need to retroactively add a company that the contacts on the ticket are associated with. Try it out using the Create a Ticket endpoint.
Retrieving custom ticket states is available in versions 2.9, 2.10, 2.11 and Preview versions of the Tickets API.
Two states have been added:
ticket_state_internal_label: The state the ticket is currently in, in a human readable form. This is only visible within Intercom to teammates.ticket_state_external_label: The state the ticket is currently in, in a human readable form. This is visible to customers and can be viewed in the Messenger, Email, and Tickets portal.
The email_domain attribute has been added to the Contacts object in versions 2.0 and above.
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.
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 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.
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.
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.
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.
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:
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 — 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.