From 6320d072a0be77a7725016742cb43cdbb48b37bc Mon Sep 17 00:00:00 2001 From: yasser-aboelgheit-intercom Date: Thu, 22 Oct 2026 15:47:57 +0100 Subject: [PATCH] Document side conversation, WhatsApp status and phone switch errors Add the 400 side_conversation error to delete, attach contact, detach contact and convert to ticket. Give the WhatsApp status errors the error.list shape, and add the 403 to the WhatsApp message status endpoint. For phone call redirects, list the 422 error keys from phone number validation, describe the 400 as a failed phone number lookup or SMS send, and add the 401 returned when the workspace can't use the feature. Applies to 2.17 and Preview. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 102 ++++++++++++++++++++++--- descriptions/2.17/api.intercom.io.yaml | 102 ++++++++++++++++++++++--- 2 files changed, 184 insertions(+), 20 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 987e5099..f98b767d 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -16711,6 +16711,20 @@ paths: deleted: true schema: "$ref": "#/components/schemas/conversation_deleted" + '400': + description: Side conversation + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: 44656d97-2081-44b1-b5f7-c14d0bb1b894 + errors: + - code: side_conversation + message: action can not be performed on a side conversation + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -18125,6 +18139,20 @@ paths: id: 6762f19b1bb69f9f2193bbd4 schema: "$ref": "#/components/schemas/conversation_participants_response" + '400': + description: Side conversation + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: af2cd450-2764-402c-a0e0-cae08a72647b + errors: + - code: side_conversation + message: action can not be performed on a side conversation + schema: + "$ref": "#/components/schemas/error" '404': description: Not found content: @@ -18230,6 +18258,20 @@ paths: id: 6762f1b41bb69f9f2193bbe0 schema: "$ref": "#/components/schemas/conversation_participants_response" + '400': + description: Side conversation + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: 83b5ee5b-1971-4594-a6fd-581ee7c56adb + errors: + - code: side_conversation + message: action can not be performed on a side conversation + schema: + "$ref": "#/components/schemas/error" '404': description: Contact not found content: @@ -19130,6 +19172,13 @@ paths: errors: - code: parameter_invalid message: Ticket type is not a customer ticket type + Side conversation: + value: + type: error.list + request_id: 2c105a05-72f9-4b5d-a01b-4b0c84f6e466 + errors: + - code: side_conversation + message: action can not be performed on a side conversation schema: "$ref": "#/components/schemas/error" requestBody: @@ -24648,9 +24697,11 @@ paths: examples: missing ruleset_id: value: - type: error - request_id: "req_123" - message: "ruleset_id is required" + type: error.list + request_id: 71c45f21-af71-4b0a-a3c6-ef5e2b55740c + errors: + - code: parameter_not_found + message: ruleset_id is required schema: "$ref": "#/components/schemas/error" '401': @@ -24688,9 +24739,11 @@ paths: examples: server error: value: - type: error + type: error.list request_id: 591a0c2f-78b3-41bb-bfa7-f1fae15107b2 - message: "Request failed due to an internal error. Please reach out to support" + errors: + - code: server_error + message: Request failed due to an internal error. Please reach out to support schema: "$ref": "#/components/schemas/error" "/messages/whatsapp/status": @@ -24752,9 +24805,11 @@ paths: examples: missing message_id: value: - type: error - request_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" - message: "message_id is required" + type: error.list + request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + errors: + - code: parameter_not_found + message: message_id is required schema: "$ref": "#/components/schemas/error" '401': @@ -24771,6 +24826,20 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + '403': + description: API plan restricted + content: + application/json: + examples: + API plan restricted: + value: + type: error.list + request_id: 76d8344a-bd94-424c-937b-cc19de8215bb + errors: + - code: api_plan_restricted + message: Active subscription needed. + schema: + "$ref": "#/components/schemas/error" '404': description: WhatsApp message not found content: @@ -26297,7 +26366,7 @@ paths: schema: "$ref": "#/components/schemas/phone_switch" '400': - description: bad request - invalid number + description: Phone number lookup or SMS send failed content: application/json: examples: @@ -26314,9 +26383,15 @@ paths: content: application/json: examples: + Invalid phone number: + value: + error_key: invalid_phone_number unprocessable entity: value: - error_key: some_error + error_key: landline_phone + Twilio account not found: + value: + error_key: twilio_settings '401': description: Unauthorized content: @@ -26329,6 +26404,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Feature not available: + value: + type: error.list + request_id: 79b635fd-f1f6-4404-aa83-5782675987fb + errors: + - code: unauthorized + message: App does not have access to this feature schema: "$ref": "#/components/schemas/error" requestBody: diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 8675690f..a59fef88 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -17168,6 +17168,20 @@ paths: deleted: true schema: "$ref": "#/components/schemas/conversation_deleted" + '400': + description: Side conversation + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: 44656d97-2081-44b1-b5f7-c14d0bb1b894 + errors: + - code: side_conversation + message: action can not be performed on a side conversation + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -18330,6 +18344,20 @@ paths: id: 6762f19b1bb69f9f2193bbd4 schema: "$ref": "#/components/schemas/conversation_participants_response" + '400': + description: Side conversation + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: af2cd450-2764-402c-a0e0-cae08a72647b + errors: + - code: side_conversation + message: action can not be performed on a side conversation + schema: + "$ref": "#/components/schemas/error" '404': description: Not found content: @@ -18435,6 +18463,20 @@ paths: id: 6762f1b41bb69f9f2193bbe0 schema: "$ref": "#/components/schemas/conversation_participants_response" + '400': + description: Side conversation + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: 83b5ee5b-1971-4594-a6fd-581ee7c56adb + errors: + - code: side_conversation + message: action can not be performed on a side conversation + schema: + "$ref": "#/components/schemas/error" '404': description: Contact not found content: @@ -19251,6 +19293,13 @@ paths: errors: - code: parameter_invalid message: Ticket type is not a customer ticket type + Side conversation: + value: + type: error.list + request_id: 2c105a05-72f9-4b5d-a01b-4b0c84f6e466 + errors: + - code: side_conversation + message: action can not be performed on a side conversation schema: "$ref": "#/components/schemas/error" requestBody: @@ -23095,9 +23144,11 @@ paths: examples: missing message_id: value: - type: error - request_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" - message: "message_id is required" + type: error.list + request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + errors: + - code: parameter_not_found + message: message_id is required schema: "$ref": "#/components/schemas/error" '401': @@ -23114,6 +23165,20 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + '403': + description: API plan restricted + content: + application/json: + examples: + API plan restricted: + value: + type: error.list + request_id: 76d8344a-bd94-424c-937b-cc19de8215bb + errors: + - code: api_plan_restricted + message: Active subscription needed. + schema: + "$ref": "#/components/schemas/error" '404': description: WhatsApp message not found content: @@ -23211,9 +23276,11 @@ paths: examples: missing ruleset_id: value: - type: error - request_id: "req_123" - message: "ruleset_id is required" + type: error.list + request_id: 71c45f21-af71-4b0a-a3c6-ef5e2b55740c + errors: + - code: parameter_not_found + message: ruleset_id is required schema: "$ref": "#/components/schemas/error" '401': @@ -23251,9 +23318,11 @@ paths: examples: server error: value: - type: error + type: error.list request_id: 591a0c2f-78b3-41bb-bfa7-f1fae15107b2 - message: "Request failed due to an internal error. Please reach out to support" + errors: + - code: server_error + message: Request failed due to an internal error. Please reach out to support schema: "$ref": "#/components/schemas/error" "/news/news_items": @@ -24222,7 +24291,7 @@ paths: schema: "$ref": "#/components/schemas/phone_switch" '400': - description: bad request - invalid number + description: Phone number lookup or SMS send failed content: application/json: examples: @@ -24239,9 +24308,15 @@ paths: content: application/json: examples: + Invalid phone number: + value: + error_key: invalid_phone_number unprocessable entity: value: - error_key: some_error + error_key: landline_phone + Twilio account not found: + value: + error_key: twilio_settings '401': description: Unauthorized content: @@ -24254,6 +24329,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Feature not available: + value: + type: error.list + request_id: 79b635fd-f1f6-4404-aa83-5782675987fb + errors: + - code: unauthorized + message: App does not have access to this feature schema: "$ref": "#/components/schemas/error" requestBody: