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 6b1623c..a04a8e7 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 6a98a0a..644caa1 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 5db6e13..a770282 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 557df5c..e6af852 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 35ed2d9..65dd431 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 0ce4819..36aea13 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 d364e4e..4a1f338 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 090d56c..8a851bb 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 d08d972..f5111a2 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 a04a8e7..d56254b 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 644caa1..5e6499c 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 a770282..e2afe89 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 e6af852..1e29d16 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 65dd431..6c74b43 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 36aea13..98cb824 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 4a1f338..66b6403 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 8a851bb..5ebe4e0 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 f5111a2..8aac054 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 39331f6..58f983b 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: