From 82730578f99be2eacea26c4bc20a7bad3102a7dd Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Wed, 25 Mar 2026 15:20:21 +0000 Subject: [PATCH 1/3] fix: Mark conversation_id as required in message schema The conversation_id field was missing from the required array in the message schema, making it appear optional in rendered API docs. This confused customers into thinking the Create Conversation endpoint might not always return a conversation ID. Added conversation_id to the required array across all versions (2.11 already had it). Co-Authored-By: Claude Opus 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 1 + descriptions/2.10/api.intercom.io.yaml | 1 + descriptions/2.12/api.intercom.io.yaml | 1 + descriptions/2.13/api.intercom.io.yaml | 1 + descriptions/2.14/api.intercom.io.yaml | 1 + descriptions/2.15/api.intercom.io.yaml | 1 + descriptions/2.7/api.intercom.io.yaml | 1 + descriptions/2.8/api.intercom.io.yaml | 1 + descriptions/2.9/api.intercom.io.yaml | 1 + 9 files changed, 9 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 6b1623cf..a04a8e73 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -24664,6 +24664,7 @@ components: - created_at - body - message_type + - conversation_id whatsapp_message_status_list: type: object required: diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml index 6a98a0a9..644caa17 100644 --- a/descriptions/2.10/api.intercom.io.yaml +++ b/descriptions/2.10/api.intercom.io.yaml @@ -15190,6 +15190,7 @@ components: - created_at - body - message_type + - conversation_id multiple_or_single_filter_search_request: title: Multiple or Single Filter Search Request oneOf: diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml index 5db6e137..a7702828 100644 --- a/descriptions/2.12/api.intercom.io.yaml +++ b/descriptions/2.12/api.intercom.io.yaml @@ -16487,6 +16487,7 @@ components: - created_at - body - message_type + - conversation_id multiple_or_single_filter_search_request: title: Multiple or Single Filter Search Request oneOf: diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml index 557df5c1..e6af8521 100644 --- a/descriptions/2.13/api.intercom.io.yaml +++ b/descriptions/2.13/api.intercom.io.yaml @@ -18190,6 +18190,7 @@ components: - created_at - body - message_type + - conversation_id multiple_filter_search_request: title: Multiple Filter Search Request description: Search using Intercoms Search APIs with more than one filter. diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 35ed2d9e..65dd4315 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -20019,6 +20019,7 @@ components: - created_at - body - message_type + - conversation_id whatsapp_message_status_list: type: object required: diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 0ce48194..36aea13f 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -20847,6 +20847,7 @@ components: - created_at - body - message_type + - conversation_id whatsapp_message_status_list: type: object required: diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml index d364e4e2..4a1f338f 100644 --- a/descriptions/2.7/api.intercom.io.yaml +++ b/descriptions/2.7/api.intercom.io.yaml @@ -13106,6 +13106,7 @@ components: - created_at - body - message_type + - conversation_id multiple_or_single_filter_search_request: title: Multiple or Single Filter Search Request oneOf: diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml index 090d56c4..8a851bbf 100644 --- a/descriptions/2.8/api.intercom.io.yaml +++ b/descriptions/2.8/api.intercom.io.yaml @@ -13131,6 +13131,7 @@ components: - created_at - body - message_type + - conversation_id multiple_or_single_filter_search_request: title: Multiple or Single Filter Search Request oneOf: diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml index d08d972c..f5111a2f 100644 --- a/descriptions/2.9/api.intercom.io.yaml +++ b/descriptions/2.9/api.intercom.io.yaml @@ -14483,6 +14483,7 @@ components: - created_at - body - message_type + - conversation_id multiple_or_single_filter_search_request: title: Multiple or Single Filter Search Request oneOf: From 31df6b773eb6984b31690f3a916b1dd4cf12decd Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Thu, 26 Mar 2026 09:31:49 +0000 Subject: [PATCH 2/3] fix: Use allOf to require conversation_id only on createConversation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous approach added conversation_id to the shared message schema's required array, which would incorrectly enforce it on all endpoints using that schema (including createMessage, where admin messages don't include conversation_id). Instead, use allOf at the createConversation endpoint level to extend the message schema with conversation_id as required — matching the established pattern used elsewhere in these specs. Co-Authored-By: Claude Opus 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 6 ++++-- descriptions/2.10/api.intercom.io.yaml | 6 ++++-- descriptions/2.12/api.intercom.io.yaml | 6 ++++-- descriptions/2.13/api.intercom.io.yaml | 6 ++++-- descriptions/2.14/api.intercom.io.yaml | 6 ++++-- descriptions/2.15/api.intercom.io.yaml | 6 ++++-- descriptions/2.7/api.intercom.io.yaml | 6 ++++-- descriptions/2.8/api.intercom.io.yaml | 6 ++++-- descriptions/2.9/api.intercom.io.yaml | 6 ++++-- 9 files changed, 36 insertions(+), 18 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a04a8e73..d56254b4 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -6707,7 +6707,10 @@ paths: message_type: inapp conversation_id: '499' schema: - "$ref": "#/components/schemas/message" + allOf: + - "$ref": "#/components/schemas/message" + required: + - conversation_id '404': description: Contact Not Found content: @@ -24664,7 +24667,6 @@ components: - created_at - body - message_type - - conversation_id whatsapp_message_status_list: type: object required: diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml index 644caa17..5e6499c2 100644 --- a/descriptions/2.10/api.intercom.io.yaml +++ b/descriptions/2.10/api.intercom.io.yaml @@ -4373,7 +4373,10 @@ paths: message_type: inapp conversation_id: '483' schema: - "$ref": "#/components/schemas/message" + allOf: + - "$ref": "#/components/schemas/message" + required: + - conversation_id '404': description: Contact Not Found content: @@ -15190,7 +15193,6 @@ components: - created_at - body - message_type - - conversation_id multiple_or_single_filter_search_request: title: Multiple or Single Filter Search Request oneOf: diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml index a7702828..e2afe89b 100644 --- a/descriptions/2.12/api.intercom.io.yaml +++ b/descriptions/2.12/api.intercom.io.yaml @@ -4989,7 +4989,10 @@ paths: message_type: inapp conversation_id: '33' schema: - "$ref": "#/components/schemas/message" + allOf: + - "$ref": "#/components/schemas/message" + required: + - conversation_id '404': description: Contact Not Found content: @@ -16487,7 +16490,6 @@ components: - created_at - body - message_type - - conversation_id multiple_or_single_filter_search_request: title: Multiple or Single Filter Search Request oneOf: diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml index e6af8521..1e29d166 100644 --- a/descriptions/2.13/api.intercom.io.yaml +++ b/descriptions/2.13/api.intercom.io.yaml @@ -5660,7 +5660,10 @@ paths: message_type: inapp conversation_id: '33' schema: - "$ref": "#/components/schemas/message" + allOf: + - "$ref": "#/components/schemas/message" + required: + - conversation_id '404': description: Contact Not Found content: @@ -18190,7 +18193,6 @@ components: - created_at - body - message_type - - conversation_id multiple_filter_search_request: title: Multiple Filter Search Request description: Search using Intercoms Search APIs with more than one filter. diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 65dd4315..6c74b43b 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -6120,7 +6120,10 @@ paths: message_type: inapp conversation_id: '499' schema: - "$ref": "#/components/schemas/message" + allOf: + - "$ref": "#/components/schemas/message" + required: + - conversation_id '404': description: Contact Not Found content: @@ -20019,7 +20022,6 @@ components: - created_at - body - message_type - - conversation_id whatsapp_message_status_list: type: object required: diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 36aea13f..98cb824b 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -6191,7 +6191,10 @@ paths: message_type: inapp conversation_id: '499' schema: - "$ref": "#/components/schemas/message" + allOf: + - "$ref": "#/components/schemas/message" + required: + - conversation_id '404': description: Contact Not Found content: @@ -20847,7 +20850,6 @@ components: - created_at - body - message_type - - conversation_id whatsapp_message_status_list: type: object required: diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml index 4a1f338f..66b64038 100644 --- a/descriptions/2.7/api.intercom.io.yaml +++ b/descriptions/2.7/api.intercom.io.yaml @@ -4582,7 +4582,10 @@ paths: message_type: inapp conversation_id: '33' schema: - "$ref": "#/components/schemas/message" + allOf: + - "$ref": "#/components/schemas/message" + required: + - conversation_id '404': description: Contact Not Found content: @@ -13106,7 +13109,6 @@ components: - created_at - body - message_type - - conversation_id multiple_or_single_filter_search_request: title: Multiple or Single Filter Search Request oneOf: diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml index 8a851bbf..5ebe4e01 100644 --- a/descriptions/2.8/api.intercom.io.yaml +++ b/descriptions/2.8/api.intercom.io.yaml @@ -4582,7 +4582,10 @@ paths: message_type: inapp conversation_id: '181' schema: - "$ref": "#/components/schemas/message" + allOf: + - "$ref": "#/components/schemas/message" + required: + - conversation_id '404': description: Contact Not Found content: @@ -13131,7 +13134,6 @@ components: - created_at - body - message_type - - conversation_id multiple_or_single_filter_search_request: title: Multiple or Single Filter Search Request oneOf: diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml index f5111a2f..8aac0546 100644 --- a/descriptions/2.9/api.intercom.io.yaml +++ b/descriptions/2.9/api.intercom.io.yaml @@ -4583,7 +4583,10 @@ paths: message_type: inapp conversation_id: '329' schema: - "$ref": "#/components/schemas/message" + allOf: + - "$ref": "#/components/schemas/message" + required: + - conversation_id '404': description: Contact Not Found content: @@ -14483,7 +14486,6 @@ components: - created_at - body - message_type - - conversation_id multiple_or_single_filter_search_request: title: Multiple or Single Filter Search Request oneOf: From c8f5d07b94f2d65dfdd9dafecc34b6c6c0946c28 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Thu, 26 Mar 2026 13:28:36 +0000 Subject: [PATCH 3/3] fix: Apply allOf pattern to v2.11 createConversation response MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Missed in the initial update — v2.11 inherits AddConversationIdToUserMessageResponse from v2.2 and its example already includes conversation_id: '363'. Co-Authored-By: Claude Opus 4.6 (1M context) --- descriptions/2.11/api.intercom.io.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml index 39331f6f..58f983b8 100644 --- a/descriptions/2.11/api.intercom.io.yaml +++ b/descriptions/2.11/api.intercom.io.yaml @@ -4474,7 +4474,10 @@ paths: message_type: inapp conversation_id: '363' schema: - "$ref": "#/components/schemas/message" + allOf: + - "$ref": "#/components/schemas/message" + required: + - conversation_id '404': description: Contact Not Found content: