From b1bd7946242e828b3390e33f2f48e63c3b58b03d Mon Sep 17 00:00:00 2001 From: Jorge Jaime-Rivera Date: Wed, 5 Aug 2026 10:49:35 -0500 Subject: [PATCH 1/2] Add the side conversation reply endpoint (Preview) Add POST /conversations/{conversation_id}/side_conversations/{id}/reply with its admin and bot request schemas to the Preview spec. Co-Authored-By: Claude Opus 4.8 (1M context) --- descriptions/0/api.intercom.io.yaml | 138 ++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 2ecca2e..f91cde8 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -14485,6 +14485,81 @@ paths: application/json: schema: "$ref": "#/components/schemas/error" + "/conversations/{conversation_id}/side_conversations/{id}/reply": + post: + summary: Reply to a side conversation + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: conversation_id + in: path + required: true + description: The identifier for the parent conversation as given by Intercom. + example: '123' + schema: + type: string + - name: id + in: path + required: true + description: The identifier for the side conversation as given by Intercom. + example: '456' + schema: + type: string + tags: + - Conversations + operationId: replySideConversation + description: | + Reply to a side conversation with a comment or note, authored by a teammate (`admin`) or by a bot (`bot`). Side conversations are internal threads created by teammates from within a conversation. + + Only the `comment` and `note` message types are supported, and replies can only be authored by an `admin` or a `bot`, not by a contact. Replying to Slack-based side conversations is not supported. + + Requires the `write_conversations` OAuth scope. + requestBody: + required: true + content: + application/json: + schema: + "$ref": "#/components/schemas/side_conversation_reply_request" + responses: + '200': + description: Successful response + content: + application/json: + schema: + "$ref": "#/components/schemas/conversation" + examples: + Successful response: + value: + type: conversation + id: '456' + created_at: 1663597223 + updated_at: 1663597260 + '400': + description: Unsupported message type + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + '404': + description: Side conversation not found + content: + application/json: + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + schema: + "$ref": "#/components/schemas/error" "/conversations/redact": post: summary: Redact a conversation part @@ -26561,6 +26636,69 @@ components: - 814865 items: type: integer + side_conversation_reply_request: + title: Side Conversation Reply + description: Payload of the request to reply to a side conversation + oneOf: + - "$ref": "#/components/schemas/side_conversation_admin_reply_request" + - "$ref": "#/components/schemas/side_conversation_bot_reply_request" + side_conversation_admin_reply_request: + title: Side Conversation Admin Reply + type: object + description: Payload to reply to a side conversation on behalf of an admin + properties: + message_type: + type: string + enum: + - comment + - note + example: comment + type: + type: string + enum: + - admin + example: admin + body: + type: string + description: The text body of the reply. Notes accept some HTML formatting. + example: Hello there! + admin_id: + type: string + description: The id of the admin authoring the reply. + example: '3156780' + required: + - message_type + - type + - admin_id + side_conversation_bot_reply_request: + title: Side Conversation Bot Reply + type: object + description: Payload to reply to a side conversation on behalf of Operator (a + bot) + properties: + message_type: + type: string + enum: + - comment + - note + example: comment + type: + type: string + enum: + - bot + example: bot + body: + type: string + description: The text body of the reply. Notes accept some HTML formatting. + example: Hello there! + bot_id: + type: string + description: The id of the bot authoring the reply. + example: '2001' + required: + - message_type + - type + - bot_id admin_reply_conversation_request: title: Admin Reply type: object From 9375340ee3ccfbc632f3b3cb4eaff463c3f61973 Mon Sep 17 00:00:00 2001 From: Jorge Jaime-Rivera Date: Thu, 6 Aug 2026 17:28:52 -0500 Subject: [PATCH 2/2] Require body and use the preview version header on the reply endpoint Mark body as required on the admin and bot reply schemas, and reference intercom_version_preview for this Preview-only endpoint. Co-Authored-By: Claude Opus 4.8 (1M context) --- descriptions/0/api.intercom.io.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index f91cde8..db666e4 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -14492,7 +14492,7 @@ paths: - name: Intercom-Version in: header schema: - "$ref": "#/components/schemas/intercom_version" + "$ref": "#/components/schemas/intercom_version_preview" - name: conversation_id in: path required: true @@ -26669,6 +26669,7 @@ components: required: - message_type - type + - body - admin_id side_conversation_bot_reply_request: title: Side Conversation Bot Reply @@ -26698,6 +26699,7 @@ components: required: - message_type - type + - body - bot_id admin_reply_conversation_request: title: Admin Reply