From ff7700d38ddc6873241e53836293712d980197c4 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Fri, 30 Oct 2026 17:09:24 +0000 Subject: [PATCH 1/3] Document removeAdmin on 2.17 and ticket scopes on Preview Add the DELETE /admins/remove endpoint to the 2.17 spec and correct its descriptions. Document the read_tickets and write_tickets scope requirements on the Preview conversation and ticket operations, and trim the 2.17 mergeConversation description. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 66 +++++++--- descriptions/2.17/api.intercom.io.yaml | 167 ++++++++++++++++++++++++- 2 files changed, 214 insertions(+), 19 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index fc223902..af28299d 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1174,8 +1174,8 @@ paths: - name: reassign_conversations_admin_id in: query required: true - description: The unique identifier of a human admin with Inbox access to - reassign the removed admin's conversation replies to. Pass `0` to leave + description: The ID of an admin with Inbox access, or a team, to reassign + the removed admin's conversation replies to. Pass `0` to leave conversations unassigned. example: 456 schema: @@ -1183,8 +1183,9 @@ paths: - name: reassign_replies_teams in: query required: false - description: A list of teams and the admin each team's conversation replies - should be reassigned to. + description: For teams that will have no members once this admin is + removed, the admin to reassign each team's conversations to. Emptied + teams that aren't listed are reassigned to the workspace's Operator. schema: type: array items: @@ -1203,9 +1204,10 @@ paths: You can remove a single admin (teammate) from your workspace. Requires the `remove_admins` OAuth scope. - This removes the admin's access to the workspace and reassigns their - work — auto-messages, ownership, article authorship, and conversation - replies — to the admins named by the `reassign_*` parameters. + This removes the admin's access to the workspace. In most cases their + work is reassigned to the IDs given in the `reassign_*` parameters. In + workspaces with more than one seat type, no reassignment happens if the + admin has no seat or a Collaborator seat. responses: '200': description: Successful response @@ -1249,9 +1251,9 @@ paths: schema: "$ref": "#/components/schemas/error" '405': - description: Method Not Allowed. Returned when `admin_id`, or one of - the `reassign_*_admin_id` parameters, refers to a bot or a team rather - than a human admin. + description: Method Not Allowed. Returned when `admin_id`, + `reassign_messages_admin_id`, `reassign_owner_admin_id` or + `reassign_articles_author_id` refers to a bot. A team ID in any of these four parameters returns `404`. content: application/json: examples: @@ -1266,7 +1268,8 @@ paths: "$ref": "#/components/schemas/error" '403': description: Forbidden. Returned when `reassign_conversations_admin_id` - refers to an admin without Inbox access for the workspace. + refers to an admin without Inbox access for the workspace. This + includes bots and teammates with a Lite seat. content: application/json: examples: @@ -17582,8 +17585,10 @@ paths: - Tags - Conversations operationId: attachTagToConversation - description: You can tag a specific conversation. This will return a tag object - for the tag that was added to the conversation. + description: | + You can tag a specific conversation. This will return a tag object for the tag that was added to the conversation. + + If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. responses: '200': description: successful @@ -17685,8 +17690,10 @@ paths: - Tags - Conversations operationId: detachTagFromConversation - description: You can remove tag from a specific conversation. This will return - a tag object for the tag that was removed from the conversation. + description: | + You can remove tag from a specific conversation. This will return a tag object for the tag that was removed from the conversation. + + If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. responses: '200': description: successful @@ -17814,6 +17821,8 @@ paths: You can use pagination to limit the number of results returned. The default is `20` results per page. See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param. {% /admonition %} + + Tickets are only included in the results if the access token has the `read_tickets` scope. Without it, tickets are left out and no error is returned. responses: '200': description: successful @@ -18179,6 +18188,8 @@ paths: {% /admonition %} For AI agent conversation metadata, please note that you need to have the agent enabled in your workspace, which is a [paid feature](https://www.intercom.com/help/en/articles/8205718-fin-resolutions#h_97f8c2e671). + + If the conversation is a ticket, the access token must include the `read_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. responses: '200': description: conversation found @@ -18848,6 +18859,8 @@ paths: - Your workspace settings (Settings → Data → Conversations) {% /admonition %} + If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. + responses: '200': description: update a conversation with an association to a custom object @@ -19143,6 +19156,8 @@ paths: {% /admonition %} For more info, see [this help center article](https://www.intercom.com/help/en/articles/13885146-deleting-a-conversation). + + If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. responses: '200': description: successful @@ -19325,6 +19340,8 @@ paths: | !~ | String | Doesn't Contain | | ^ | String | Starts With | | $ | String | Ends With | + + Tickets are only included in the results if the access token has the `read_tickets` scope. Without it, tickets are left out and no error is returned. responses: '200': description: successful @@ -19515,6 +19532,8 @@ paths: {% admonition type="info" name="Managing a conversation" %} To close, open, snooze or assign a conversation, use [Manage a conversation](/docs/references/preview/rest-api/api.intercom.io/conversations/manageconversation). {% /admonition %} + + If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. responses: '200': description: User last conversation reply @@ -19981,6 +20000,8 @@ paths: {% admonition type="info" name="Sending messages" %} To send a comment, note or quick reply, use [Reply to a conversation](/docs/references/preview/rest-api/api.intercom.io/conversations/replyconversation). {% /admonition %} + + If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. responses: '200': description: Assign a conversation @@ -20432,6 +20453,8 @@ paths: {% admonition type="warning" name="Experimental" %} This is an experimental endpoint. It requires a valid HMAC secret for authentication in addition to the standard bearer token. {% /admonition %} + + If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. responses: '200': description: Conversation part updated @@ -20572,6 +20595,8 @@ paths: If you add a contact via the email parameter and there is no user/lead found on that workspace with he given email, then we will create a new contact with `role` set to `lead`. {% /admonition %} + If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. + responses: '200': description: Attach a contact to a conversation @@ -20691,6 +20716,8 @@ paths: You cannot remove the last remaining contact from a conversation. {% /admonition %} + If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. + responses: '200': description: Detach a contact from a group conversation @@ -21169,6 +21196,8 @@ paths: If you are redacting a conversation part, it must have a `body`. If you are redacting a source message, it must have been created by a contact. We will return a `conversation_part_not_redactable` error if these criteria are not met. {% /admonition %} + If the conversation is a ticket, the access token must include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. + responses: '200': description: Redact a conversation part @@ -21329,8 +21358,9 @@ paths: The secondary conversation is closed and linked to the primary, which becomes the surviving thread. Returns the primary conversation on success. - Requires `write_conversations` OAuth scope. When the secondary is a ticket, - `write_tickets` scope is also required. + Requires `write_conversations` OAuth scope. When either conversation is a ticket, + the `read_tickets` and `write_tickets` scopes are also required. Without them, + the request returns a `401` with the error code `token_unauthorized`. responses: '200': description: Conversation merged @@ -33774,6 +33804,8 @@ paths: {% /admonition %} Deleting a ticket permanently removes it from the inbox. All sensitive data is deleted, including admin and user replies, ticket attributes, uploads, and related content. The ticket will still appear in reporting, though some data may be incomplete due to the deletion. + + Requires the `write_conversations` OAuth scope. The access token must also include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. responses: '200': description: successful diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index a3c388a8..55de0b69 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -2334,6 +2334,170 @@ paths: message: Not authorized to access resource schema: "$ref": "#/components/schemas/error" + "/admins/remove": + delete: + summary: Remove an admin + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: admin_id + in: query + required: true + description: The unique identifier of the admin to remove. + example: 123 + schema: + type: integer + - name: reassign_messages_admin_id + in: query + required: true + description: The unique identifier of a human admin to reassign the removed + admin's auto-message ownership to. + example: 456 + schema: + type: integer + - name: reassign_owner_admin_id + in: query + required: true + description: The unique identifier of a human admin to reassign the removed + admin's ownership (of users and leads) to. + example: 456 + schema: + type: integer + - name: reassign_articles_author_id + in: query + required: true + description: The unique identifier of a human admin to reassign the removed + admin's article authorship to. + example: 456 + schema: + type: integer + - name: reassign_conversations_admin_id + in: query + required: true + description: The ID of an admin with Inbox access, or a team, to reassign + the removed admin's conversation replies to. Pass `0` to leave + conversations unassigned. + example: 456 + schema: + type: integer + - name: reassign_replies_teams + in: query + required: false + description: For teams that will have no members once this admin is + removed, the admin to reassign each team's conversations to. Emptied + teams that aren't listed are reassigned to the workspace's Operator. + schema: + type: array + items: + type: object + properties: + team_id: + type: integer + example: 789 + assignee_id: + type: integer + example: 456 + tags: + - Admins + operationId: removeAdmin + description: |- + You can remove a single admin (teammate) from your workspace. + Requires the `remove_admins` OAuth scope. + + This removes the admin's access to the workspace. In most cases their + work is reassigned to the IDs given in the `reassign_*` parameters. In + workspaces with more than one seat type, no reassignment happens if the + admin has no seat or a Collaborator seat. + responses: + '200': + description: Successful response + content: + application/json: + examples: + Successful response: + value: + id: '123' + object: admin + removed: 'true' + schema: + type: object + properties: + id: + type: string + description: The unique identifier of the removed admin. + example: '123' + object: + type: string + enum: [admin] + example: admin + removed: + type: string + description: Whether the admin was removed. Returned as the + string `"true"`. + enum: ['true'] + example: 'true' + '404': + description: Admin not found + content: + application/json: + examples: + Admin not found: + value: + type: error.list + request_id: 00000000-0000-4000-8000-000000000001 + errors: + - code: admin_not_found + message: "Admin for admin_id not found" + schema: + "$ref": "#/components/schemas/error" + '405': + description: Method Not Allowed. Returned when `admin_id`, + `reassign_messages_admin_id`, `reassign_owner_admin_id` or + `reassign_articles_author_id` refers to a bot. A team ID in any of these four parameters returns `404`. + content: + application/json: + examples: + Method Not Allowed: + value: + type: error.list + errors: + - code: action_forbidden + message: "This method is not allowed for this type of Admin + for admin_id" + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden. Returned when `reassign_conversations_admin_id` + refers to an admin without Inbox access for the workspace. This + includes bots and teammates with a Lite seat. + content: + application/json: + examples: + Forbidden: + value: + type: error.list + errors: + - code: action_forbidden + message: "The admin for reassign_conversations_admin_id does + not have Inbox access permissions" + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 00000000-0000-4000-8000-000000000002 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" "/ai/content_import_sources": get: summary: List content import sources @@ -20911,8 +21075,7 @@ paths: The secondary conversation is closed and linked to the primary, which becomes the surviving thread. Returns the primary conversation on success. - Requires `write_conversations` OAuth scope. When the secondary is a ticket, - `write_tickets` scope is also required. + Requires `write_conversations` OAuth scope. responses: '200': description: Conversation merged From 37d8ba2c6a1d949874b78b9a79b2d3fca6f9a121 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Mon, 2 Nov 2026 10:24:45 +0000 Subject: [PATCH 2/3] Tighten removeAdmin and ticket scope wording Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 11 +++++------ descriptions/2.17/api.intercom.io.yaml | 9 ++++----- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index af28299d..6cb74a41 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1183,9 +1183,8 @@ paths: - name: reassign_replies_teams in: query required: false - description: For teams that will have no members once this admin is - removed, the admin to reassign each team's conversations to. Emptied - teams that aren't listed are reassigned to the workspace's Operator. + description: A list of teams and the admin each team's conversation replies + should be reassigned to. schema: type: array items: @@ -1207,7 +1206,7 @@ paths: This removes the admin's access to the workspace. In most cases their work is reassigned to the IDs given in the `reassign_*` parameters. In workspaces with more than one seat type, no reassignment happens if the - admin has no seat or a Collaborator seat. + admin has no seat, a Collaborator seat or a Lite seat. responses: '200': description: Successful response @@ -1269,7 +1268,7 @@ paths: '403': description: Forbidden. Returned when `reassign_conversations_admin_id` refers to an admin without Inbox access for the workspace. This - includes bots and teammates with a Lite seat. + includes teammates with a Lite seat. content: application/json: examples: @@ -33805,7 +33804,7 @@ paths: Deleting a ticket permanently removes it from the inbox. All sensitive data is deleted, including admin and user replies, ticket attributes, uploads, and related content. The ticket will still appear in reporting, though some data may be incomplete due to the deletion. - Requires the `write_conversations` OAuth scope. The access token must also include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. + Requires the `write_conversations` OAuth scope. If the ID refers to a ticket, the access token must also include the `write_tickets` scope. Without it, the request returns a `401` with the error code `token_unauthorized`. responses: '200': description: successful diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 55de0b69..8d39e6b6 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -2385,9 +2385,8 @@ paths: - name: reassign_replies_teams in: query required: false - description: For teams that will have no members once this admin is - removed, the admin to reassign each team's conversations to. Emptied - teams that aren't listed are reassigned to the workspace's Operator. + description: A list of teams and the admin each team's conversation replies + should be reassigned to. schema: type: array items: @@ -2409,7 +2408,7 @@ paths: This removes the admin's access to the workspace. In most cases their work is reassigned to the IDs given in the `reassign_*` parameters. In workspaces with more than one seat type, no reassignment happens if the - admin has no seat or a Collaborator seat. + admin has no seat, a Collaborator seat or a Lite seat. responses: '200': description: Successful response @@ -2471,7 +2470,7 @@ paths: '403': description: Forbidden. Returned when `reassign_conversations_admin_id` refers to an admin without Inbox access for the workspace. This - includes bots and teammates with a Lite seat. + includes teammates with a Lite seat. content: application/json: examples: From fbe610c42932616faa2af1621c9a434255e2058f Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Mon, 2 Nov 2026 11:56:04 +0000 Subject: [PATCH 3/3] Document the not_found 404 for removeAdmin Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 4 +++- descriptions/2.17/api.intercom.io.yaml | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 6cb74a41..a459a4fa 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -1236,7 +1236,9 @@ paths: enum: ['true'] example: 'true' '404': - description: Admin not found + description: Admin not found. A `reassign_conversations_admin_id` that is + missing, or doesn't match an admin or team, returns `404` with the + code `not_found` and the message "Resource Not Found". content: application/json: examples: diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 8d39e6b6..f8d18e72 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -2438,7 +2438,9 @@ paths: enum: ['true'] example: 'true' '404': - description: Admin not found + description: Admin not found. A `reassign_conversations_admin_id` that is + missing, or doesn't match an admin or team, returns `404` with the + code `not_found` and the message "Resource Not Found". content: application/json: examples: