# Unversioned Changes

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
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](/docs/build-an-integration/learn-more/rest-apis/api-changelog#about-breaking-changes-in-the-intercom-api)

## November 2026

### New OAuth scope: Create and update articles

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`](/docs/references/preview/rest-api/api.intercom.io/content/bulkcontentactions). 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 folders
- `write_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.

## October 2026

### Bulk delete: up to 1,000 items per request

[`POST /contacts/bulk/delete`](/docs/references/rest-api/api.intercom.io/contacts/bulkdeletecontacts) and [`POST /companies/bulk/delete`](/docs/references/preview/rest-api/api.intercom.io/companies/bulkdeletecompanies) 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.

### ❗️`ticket.state.updated` webhook no longer sent when a ticket is created

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.

### Create a message: messages from contacts

The [`POST /messages`](/docs/references/rest-api/api.intercom.io/messages/createmessage) 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`](/docs/references/rest-api/api.intercom.io/conversations/createconversation) 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.

### ❗️Fin Agent API: validation errors name `conversation_id`

[`POST /fin/start`](/docs/references/rest-api/api.intercom.io/fin-agent/startfinconversation), [`POST /fin/reply`](/docs/references/rest-api/api.intercom.io/fin-agent/replytofin), [`POST /fin/ask`](/docs/references/rest-api/api.intercom.io/fin-agent/askfin), [`POST /fin/procedures/{procedure_id}/run`](/docs/references/rest-api/api.intercom.io/fin-agent/runfinprocedure) and [`POST /fin/csat`](/docs/references/rest-api/api.intercom.io/fin-agent/submitfincsat) 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.

### Fin Agent API: target an environment

[`POST /fin/start`](/docs/references/rest-api/api.intercom.io/fin-agent/startfinconversation), [`POST /fin/ask`](/docs/references/rest-api/api.intercom.io/fin-agent/askfin) and [`POST /fin/procedures/{procedure_id}/run`](/docs/references/rest-api/api.intercom.io/fin-agent/runfinprocedure) 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](/docs/guides/fin-agent-api/) for full documentation.

### Fin Agent API: up to 20 conversation attributes

[`POST /fin/start`](/docs/references/rest-api/api.intercom.io/fin-agent/startfinconversation), [`POST /fin/ask`](/docs/references/rest-api/api.intercom.io/fin-agent/askfin) and [`POST /fin/procedures/{procedure_id}/run`](/docs/references/rest-api/api.intercom.io/fin-agent/runfinprocedure) 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](/docs/guides/fin-agent-api/) for full documentation.

### ❗️MCP requests are limited to the teammate's permissions

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:

```json
{
  "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.

### Fin Agent API: content sources on `fin_replied` events

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](/docs/guides/fin-agent-api/) for full documentation.

## September 2026

### Fin Agent API: `intercom_conversation_id` on conversation responses

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`](/docs/references/rest-api/api.intercom.io/fin-agent/startfinconversation) and [`POST /fin/reply`](/docs/references/rest-api/api.intercom.io/fin-agent/replytofin). On Preview it also affects [`POST /fin/ask`](/docs/references/preview/rest-api/api.intercom.io/fin-agent/askfin) and [`POST /fin/procedures/{procedure_id}/run`](/docs/references/preview/rest-api/api.intercom.io/fin-agent/runfinprocedure); [`POST /fin/escalate`](/docs/references/preview/rest-api/api.intercom.io/fin-agent/escalatefinconversation) 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](/docs/guides/fin-agent-api/) for full documentation.

### ❗️Replying to a ticket with a comment is restricted to customer-facing tickets

The [Reply to a ticket](/docs/references/preview/rest-api/api.intercom.io/tickets/replyticket) 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.

### Elasticsearch rate limiting now returns 429 instead of 500

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.

### ❗️Bulk people and company webhook topics no longer accept "Read one user and one company"

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](/docs/references/preview/webhooks/webhook-models) 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](https://app.intercom.com/a/apps/_/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.

## August 2026

### Fin Voice call responses include classified attributes

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.

### Fin Voice call responses include registration metadata

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.

## July 2026

### ❗️Conversation access is limited by the teammate who installed the app

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 `403` error with the code `token_unauthorized` and the message `Not authorized to access this conversation`. This affects the [Retrieve](/docs/references/rest-api/api.intercom.io/conversations/retrieveconversation), [Update](/docs/references/rest-api/api.intercom.io/conversations/updateconversation), [Delete](/docs/references/rest-api/api.intercom.io/conversations/deleteconversation), [Reply to](/docs/references/rest-api/api.intercom.io/conversations/replyconversation), [Manage](/docs/references/rest-api/api.intercom.io/conversations/manageconversation), [Merge](/docs/references/rest-api/api.intercom.io/conversations/mergeconversation) and [Convert](/docs/references/rest-api/api.intercom.io/conversations/convertconversationtoticket) 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](/docs/references/rest-api/api.intercom.io/conversations/listconversations) and [search](/docs/references/rest-api/api.intercom.io/conversations/searchconversations) 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](/docs/build-an-integration/learn-more/authentication/oauth-scopes#conversation-access-is-limited-by-the-installing-teammate) for details.

This change applies to all API versions.

### Fin Agent API: CSAT ratings

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](/docs/guides/fin-agent-api/#submit-a-csat-rating) for full documentation.

## June 2026

### Contact write endpoints document the Unix timestamp format for date fields

The [Create contact](/docs/references/preview/rest-api/api.intercom.io/contacts/createcontact) (`POST /contacts`) and [Update contact](/docs/references/preview/rest-api/api.intercom.io/contacts/updatecontact) (`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.

## May 2026

### ❗️Duplicate conversation custom attribute names now return an error

The [Update a conversation](/docs/references/preview/rest-api/api.intercom.io/conversations/updateconversation/) 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](/docs/references/preview/rest-api/api.intercom.io/conversations-attributes/listconversationattributes) (Preview only) — list with `GET /conversations/attributes`, then rename with `PUT /conversations/attributes/{id}` or archive with `DELETE /conversations/attributes/{id}`
- Your workspace settings (Settings → Data → Conversations)


This change applies to all API versions.

## April 2026

### Fin Agent API: message `id` on `fin_replied` events

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](/docs/guides/fin-agent-api/#fin-reply) for details.

### Cross-post notes to linked conversations on back-office tickets

The [Reply to a ticket](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Tickets/replyTicket/) 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_type` must be `note`
- The reply must be from an admin (`type: admin`)


## February 2026

### ❗️Contact company association limit now returns an error

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.

## July 2025

### News Item API published date control fixed

We've fixed the `published_at` parameter in the `newsfeed_assignments` array so it now works correctly when creating and updating news items:

```json
{
  "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.

## May 2024

### AI Agent metadata in the Conversations API

You can now access additional metadata for conversations where an AI Agent was involved as part of the [Conversations API](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Conversations/retrieveConversation/).

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, like `workflow` or `fin_preview`
- `source_title`: The title of the `profile` or `workflow`
- `last_answer_type`: The type of the last answer delivered in the conversation, like `ai_answer` or `custom_answer`
- `resolution_state`: The resolution outcome from AI Agent's participation in the conversation, such as `confirmed_resolution` or `routed_to_team`
- `rating`: The Customer Satisfaction (CSAT) rating provided from 1-5. Note that you will need to [enable Fin AI Agent CSAT](https://www.intercom.com/help/en/articles/8368157-fin-ai-agent-csat) in order to gather this rating
- `rating_remark`: The user's rating as a comment, if they left one
- `content_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](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Conversations/retrieveConversation/), [list conversations](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Conversations/listConversations/), and [search conversations](https://developers.intercom.com/docs/references/preview/rest-api/api.intercom.io/Conversations/searchConversations/) pages or in your own terminal.

## Define your own created at values in Conversations

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](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Conversations/createConversation/) or [Reply to a Conversation](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Conversations/replyConversation/) endpoints.

## Add a company ID when you create a Ticket

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](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Tickets/createTicket/) endpoint.

## February 2024

### Ticket States

Retrieving custom ticket states is available in versions `2.9`, `2.10`, `2.11` and `Preview` versions of the [Tickets API](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Tickets/getTicket/).

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.


### Email Domains

The `email_domain` attribute has been added to the [Contacts object](https://developers.intercom.com/docs/references/2.7/rest-api/api.intercom.io/Contacts/contact/) in versions `2.0` and above.

## April 2023

### ❗️Conversation Part IDs are not unique across all workspaces

As flagged in a [previous update](#changing-ids-to-no-longer-be-unique-across-all-workspaces), 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](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Articles/article/) 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](https://developers.intercom.com/docs/guides/help-center/supported-html/#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](https://developers.intercom.com/docs/guides/help-center/supported-html/#supported-html). This will ensure your code is resilient in handling any new HTML elements or attributes we may support in the future.

### ❗️Listed Articles no longer return statistics

Articles which have been [listed](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Articles/listArticles/) 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](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Articles/listArticles/).

### Tables and Horizontal Rules are supported as Article HTML content

Articles now support both Tables and Horizontal rules. This will mean they will show in the [Articles model](/docs/references/2.6/rest-api/articles/the-article-model), and can be added within the body of an Article when [creating](/docs/references/2.6/rest-api/articles/create-an-article) or [updating](/docs/references/2.6/rest-api/articles/update-an-article) these using the valid HTML. The Articles endpoint is available from V2.1 upwards.

### Text component headers are bold for Messenger Canvas Kit apps

When a [Text component](/docs/references/preview/canvas-kit/presentationcomponents/text) 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

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:

- [Conversation Message Object](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Messages/message/)
- [Customer First Reply Object](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Conversations/replyConversation/)
- [Conversation Part Object](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Conversations/conversation/)


### ❗️IDs are not unique across all workspaces

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](/docs/references/2.1/rest-api/conversations/conversation-model) 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`.