From b75c0c5097235f25d6cf5bd7e9a3401d55c388f8 Mon Sep 17 00:00:00 2001 From: cox512 Date: Wed, 2 Sep 2026 13:48:39 -0500 Subject: [PATCH 1/4] Correct the 200 response schema for attach and detach contact Both endpoints declared a 200 body of `conversation`, but each returns only the conversation's remaining contacts: an object with a `customers` array of `{ type, id }`. The inline 200 examples already showed that shape, so the examples were right and the schema was wrong. Adds a shared `conversation_customers_response` schema describing the real body and points both operations' 200 at it, across Preview and v2.7-v2.16. `type` is documented in prose rather than as an enum so a future contact role does not become a breaking SDK change. This changes the generated SDK return type for both operations from `Conversation` to `ConversationCustomersResponse`. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YXXKa8L8m446cLYBiqtsWF --- descriptions/0/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- descriptions/2.10/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- descriptions/2.11/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- descriptions/2.12/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- descriptions/2.13/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- descriptions/2.14/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- descriptions/2.15/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- descriptions/2.16/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- descriptions/2.7/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- descriptions/2.8/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- descriptions/2.9/api.intercom.io.yaml | 29 ++++++++++++++++++++++++-- 11 files changed, 297 insertions(+), 22 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index eb33e06..cd4cf99 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -14556,7 +14556,7 @@ paths: - type: user id: 6762f19b1bb69f9f2193bbd4 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -14661,7 +14661,7 @@ paths: - type: user id: 6762f1b41bb69f9f2193bbe0 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -28972,6 +28972,31 @@ components: "$ref": "#/components/schemas/customer_request" required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers team_metric: type: object description: Per-admin activity metrics within a team. diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml index c56ac40..87e7b0e 100644 --- a/descriptions/2.10/api.intercom.io.yaml +++ b/descriptions/2.10/api.intercom.io.yaml @@ -5971,7 +5971,7 @@ paths: - type: user id: 6657accd6abd0166b52ae296 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -6076,7 +6076,7 @@ paths: - type: user id: 6657acdb6abd0166b52ae2a2 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -11937,6 +11937,31 @@ components: "$ref": "#/components/schemas/customer_request" required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers close_conversation_request: title: Close Conversation Request type: object diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml index eaa4631..ce656f0 100644 --- a/descriptions/2.11/api.intercom.io.yaml +++ b/descriptions/2.11/api.intercom.io.yaml @@ -6081,7 +6081,7 @@ paths: - type: user id: 667d61168a68186f43bafe0d schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -6186,7 +6186,7 @@ paths: - type: user id: 667d61228a68186f43bafe19 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -12179,6 +12179,31 @@ components: nullable: true required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers button_component: title: Button Component type: object diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml index 2091593..8231547 100644 --- a/descriptions/2.12/api.intercom.io.yaml +++ b/descriptions/2.12/api.intercom.io.yaml @@ -6491,7 +6491,7 @@ paths: - type: user id: 677c55ef6abd011ad17ff541 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -6596,7 +6596,7 @@ paths: - type: user id: 677c56016abd011ad17ff54d schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -12843,6 +12843,31 @@ components: "$ref": "#/components/schemas/customer_request" required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers close_conversation_request: title: Close Conversation Request type: object diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml index 2f42b47..f37eeff 100644 --- a/descriptions/2.13/api.intercom.io.yaml +++ b/descriptions/2.13/api.intercom.io.yaml @@ -7476,7 +7476,7 @@ paths: - type: user id: 677c55ef6abd011ad17ff541 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -7581,7 +7581,7 @@ paths: - type: user id: 677c56016abd011ad17ff54d schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -14294,6 +14294,31 @@ components: "$ref": "#/components/schemas/customer_request" required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers close_conversation_request: title: Close Conversation Request type: object diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 62c76f9..2beb602 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -8459,7 +8459,7 @@ paths: - type: user id: 6762f19b1bb69f9f2193bbd4 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -8564,7 +8564,7 @@ paths: - type: user id: 6762f1b41bb69f9f2193bbe0 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -15951,6 +15951,31 @@ components: "$ref": "#/components/schemas/customer_request" required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers away_status_reason: type: object properties: diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index dbc8d6c..778e160 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -8382,7 +8382,7 @@ paths: - type: user id: 6762f19b1bb69f9f2193bbd4 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -8487,7 +8487,7 @@ paths: - type: user id: 6762f1b41bb69f9f2193bbe0 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -16636,6 +16636,31 @@ components: "$ref": "#/components/schemas/customer_request" required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers brand: type: object title: Brand diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 76e8733..1513d8e 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -12697,7 +12697,7 @@ paths: - type: user id: 6762f19b1bb69f9f2193bbd4 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -12802,7 +12802,7 @@ paths: - type: user id: 6762f1b41bb69f9f2193bbe0 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -24380,6 +24380,31 @@ components: "$ref": "#/components/schemas/customer_request" required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers brand: type: object title: Brand diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml index dafa8b0..ee8554f 100644 --- a/descriptions/2.7/api.intercom.io.yaml +++ b/descriptions/2.7/api.intercom.io.yaml @@ -6103,7 +6103,7 @@ paths: - type: user id: 6657a89e6abd0160d35d1ef2 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -6208,7 +6208,7 @@ paths: - type: user id: 6657a8ab6abd0160d35d1efe schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -10047,6 +10047,31 @@ components: "$ref": "#/components/schemas/customer_request" required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers close_conversation_request: title: Close Conversation Request type: object diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml index d1ced05..d4cdc43 100644 --- a/descriptions/2.8/api.intercom.io.yaml +++ b/descriptions/2.8/api.intercom.io.yaml @@ -6103,7 +6103,7 @@ paths: - type: user id: 6657a9f76abd01639cc9e9f3 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -6208,7 +6208,7 @@ paths: - type: user id: 6657aa036abd01639cc9e9ff schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -10071,6 +10071,31 @@ components: "$ref": "#/components/schemas/customer_request" required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers close_conversation_request: title: Close Conversation Request type: object diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml index b7f626a..373cc8a 100644 --- a/descriptions/2.9/api.intercom.io.yaml +++ b/descriptions/2.9/api.intercom.io.yaml @@ -6115,7 +6115,7 @@ paths: - type: user id: 6657ab566abd0164c24b0d7d schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Not found content: @@ -6220,7 +6220,7 @@ paths: - type: user id: 6657ab636abd0164c24b0d89 schema: - "$ref": "#/components/schemas/conversation" + "$ref": "#/components/schemas/conversation_customers_response" '404': description: Contact not found content: @@ -11251,6 +11251,31 @@ components: "$ref": "#/components/schemas/customer_request" required: - email + conversation_customers_response: + title: Conversation Customers Response + type: object + description: The contacts participating in the conversation, returned after + attaching or detaching a contact + properties: + customers: + type: array + description: The contacts participating in the conversation after the change + items: + type: object + properties: + type: + type: string + description: The role of the contact. Can be "user", "lead", or "visitor" + example: 'user' + id: + type: string + description: The unique identifier for the contact + example: '6762f1a61bb69f9f2193bbd8' + required: + - type + - id + required: + - customers close_conversation_request: title: Close Conversation Request type: object From 9bffc514d1cf566be26aafbeca5107a5771ff148 Mon Sep 17 00:00:00 2001 From: cox512 Date: Wed, 2 Sep 2026 13:54:23 -0500 Subject: [PATCH 2/4] Address review: add customers example, drop visitor from contact roles A visitor cannot be a conversation participant -- the spec states a visitor is converted to a contact with a lead role when a conversation is created -- so documenting it here would promise clients a category these endpoints never return. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YXXKa8L8m446cLYBiqtsWF --- descriptions/0/api.intercom.io.yaml | 5 ++++- descriptions/2.10/api.intercom.io.yaml | 5 ++++- descriptions/2.11/api.intercom.io.yaml | 5 ++++- descriptions/2.12/api.intercom.io.yaml | 5 ++++- descriptions/2.13/api.intercom.io.yaml | 5 ++++- descriptions/2.14/api.intercom.io.yaml | 5 ++++- descriptions/2.15/api.intercom.io.yaml | 5 ++++- descriptions/2.16/api.intercom.io.yaml | 5 ++++- descriptions/2.7/api.intercom.io.yaml | 5 ++++- descriptions/2.8/api.intercom.io.yaml | 5 ++++- descriptions/2.9/api.intercom.io.yaml | 5 ++++- 11 files changed, 44 insertions(+), 11 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index cd4cf99..b4d3616 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -28986,7 +28986,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -28995,6 +28995,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers team_metric: diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml index 87e7b0e..a9a0a09 100644 --- a/descriptions/2.10/api.intercom.io.yaml +++ b/descriptions/2.10/api.intercom.io.yaml @@ -11951,7 +11951,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -11960,6 +11960,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers close_conversation_request: diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml index ce656f0..6f6d0fb 100644 --- a/descriptions/2.11/api.intercom.io.yaml +++ b/descriptions/2.11/api.intercom.io.yaml @@ -12193,7 +12193,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -12202,6 +12202,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers button_component: diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml index 8231547..511566f 100644 --- a/descriptions/2.12/api.intercom.io.yaml +++ b/descriptions/2.12/api.intercom.io.yaml @@ -12857,7 +12857,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -12866,6 +12866,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers close_conversation_request: diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml index f37eeff..60f1499 100644 --- a/descriptions/2.13/api.intercom.io.yaml +++ b/descriptions/2.13/api.intercom.io.yaml @@ -14308,7 +14308,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -14317,6 +14317,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers close_conversation_request: diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 2beb602..5a5bc12 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -15965,7 +15965,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -15974,6 +15974,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers away_status_reason: diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 778e160..67e0559 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -16650,7 +16650,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -16659,6 +16659,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers brand: diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 1513d8e..05cb3a3 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -24394,7 +24394,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -24403,6 +24403,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers brand: diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml index ee8554f..32a6377 100644 --- a/descriptions/2.7/api.intercom.io.yaml +++ b/descriptions/2.7/api.intercom.io.yaml @@ -10061,7 +10061,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -10070,6 +10070,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers close_conversation_request: diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml index d4cdc43..c216c22 100644 --- a/descriptions/2.8/api.intercom.io.yaml +++ b/descriptions/2.8/api.intercom.io.yaml @@ -10085,7 +10085,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -10094,6 +10094,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers close_conversation_request: diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml index 373cc8a..5fa69a8 100644 --- a/descriptions/2.9/api.intercom.io.yaml +++ b/descriptions/2.9/api.intercom.io.yaml @@ -11265,7 +11265,7 @@ components: properties: type: type: string - description: The role of the contact. Can be "user", "lead", or "visitor" + description: The role of the contact. Can be "user" or "lead" example: 'user' id: type: string @@ -11274,6 +11274,9 @@ components: required: - type - id + example: + - type: user + id: '6762f1a61bb69f9f2193bbd8' required: - customers close_conversation_request: From f6732f320bcb75e83578d40575853cfa71f6f407 Mon Sep 17 00:00:00 2001 From: cox512 Date: Wed, 2 Sep 2026 14:49:31 -0500 Subject: [PATCH 3/4] Name the response schema after participants, not customers These operations are grouped under Conversation Participants, and participant is the term used for a conversation's contacts. The JSON field stays customers because that is what the endpoints actually send. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YXXKa8L8m446cLYBiqtsWF --- descriptions/0/api.intercom.io.yaml | 22 +++++++++++----------- descriptions/2.10/api.intercom.io.yaml | 18 +++++++++--------- descriptions/2.11/api.intercom.io.yaml | 18 +++++++++--------- descriptions/2.12/api.intercom.io.yaml | 18 +++++++++--------- descriptions/2.13/api.intercom.io.yaml | 18 +++++++++--------- descriptions/2.14/api.intercom.io.yaml | 18 +++++++++--------- descriptions/2.15/api.intercom.io.yaml | 18 +++++++++--------- descriptions/2.16/api.intercom.io.yaml | 18 +++++++++--------- descriptions/2.7/api.intercom.io.yaml | 18 +++++++++--------- descriptions/2.8/api.intercom.io.yaml | 18 +++++++++--------- descriptions/2.9/api.intercom.io.yaml | 18 +++++++++--------- 11 files changed, 101 insertions(+), 101 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index b4d3616..f76d5d5 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -14556,7 +14556,7 @@ paths: - type: user id: 6762f19b1bb69f9f2193bbd4 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -14661,7 +14661,7 @@ paths: - type: user id: 6762f1b41bb69f9f2193bbe0 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -28972,25 +28972,25 @@ components: "$ref": "#/components/schemas/customer_request" required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type @@ -29714,7 +29714,7 @@ components: properties: id: type: string - description: The unique identifier for the contact. + description: The unique identifier for the participant. example: abc123 job: type: object @@ -29743,7 +29743,7 @@ components: properties: id: type: string - description: The unique identifier for the contact. + description: The unique identifier for the participant. example: abc123 external_id: type: string diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml index a9a0a09..b6d1ec0 100644 --- a/descriptions/2.10/api.intercom.io.yaml +++ b/descriptions/2.10/api.intercom.io.yaml @@ -5971,7 +5971,7 @@ paths: - type: user id: 6657accd6abd0166b52ae296 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -6076,7 +6076,7 @@ paths: - type: user id: 6657acdb6abd0166b52ae2a2 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -11937,25 +11937,25 @@ components: "$ref": "#/components/schemas/customer_request" required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml index 6f6d0fb..b261ba5 100644 --- a/descriptions/2.11/api.intercom.io.yaml +++ b/descriptions/2.11/api.intercom.io.yaml @@ -6081,7 +6081,7 @@ paths: - type: user id: 667d61168a68186f43bafe0d schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -6186,7 +6186,7 @@ paths: - type: user id: 667d61228a68186f43bafe19 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -12179,25 +12179,25 @@ components: nullable: true required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml index 511566f..264fda6 100644 --- a/descriptions/2.12/api.intercom.io.yaml +++ b/descriptions/2.12/api.intercom.io.yaml @@ -6491,7 +6491,7 @@ paths: - type: user id: 677c55ef6abd011ad17ff541 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -6596,7 +6596,7 @@ paths: - type: user id: 677c56016abd011ad17ff54d schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -12843,25 +12843,25 @@ components: "$ref": "#/components/schemas/customer_request" required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml index 60f1499..d1a0800 100644 --- a/descriptions/2.13/api.intercom.io.yaml +++ b/descriptions/2.13/api.intercom.io.yaml @@ -7476,7 +7476,7 @@ paths: - type: user id: 677c55ef6abd011ad17ff541 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -7581,7 +7581,7 @@ paths: - type: user id: 677c56016abd011ad17ff54d schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -14294,25 +14294,25 @@ components: "$ref": "#/components/schemas/customer_request" required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 5a5bc12..fe030b3 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -8459,7 +8459,7 @@ paths: - type: user id: 6762f19b1bb69f9f2193bbd4 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -8564,7 +8564,7 @@ paths: - type: user id: 6762f1b41bb69f9f2193bbe0 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -15951,25 +15951,25 @@ components: "$ref": "#/components/schemas/customer_request" required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 67e0559..06dd3ed 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -8382,7 +8382,7 @@ paths: - type: user id: 6762f19b1bb69f9f2193bbd4 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -8487,7 +8487,7 @@ paths: - type: user id: 6762f1b41bb69f9f2193bbe0 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -16636,25 +16636,25 @@ components: "$ref": "#/components/schemas/customer_request" required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 05cb3a3..2af1dba 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -12697,7 +12697,7 @@ paths: - type: user id: 6762f19b1bb69f9f2193bbd4 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -12802,7 +12802,7 @@ paths: - type: user id: 6762f1b41bb69f9f2193bbe0 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -24380,25 +24380,25 @@ components: "$ref": "#/components/schemas/customer_request" required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml index 32a6377..853c4ef 100644 --- a/descriptions/2.7/api.intercom.io.yaml +++ b/descriptions/2.7/api.intercom.io.yaml @@ -6103,7 +6103,7 @@ paths: - type: user id: 6657a89e6abd0160d35d1ef2 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -6208,7 +6208,7 @@ paths: - type: user id: 6657a8ab6abd0160d35d1efe schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -10047,25 +10047,25 @@ components: "$ref": "#/components/schemas/customer_request" required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml index c216c22..4a248b2 100644 --- a/descriptions/2.8/api.intercom.io.yaml +++ b/descriptions/2.8/api.intercom.io.yaml @@ -6103,7 +6103,7 @@ paths: - type: user id: 6657a9f76abd01639cc9e9f3 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -6208,7 +6208,7 @@ paths: - type: user id: 6657aa036abd01639cc9e9ff schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -10071,25 +10071,25 @@ components: "$ref": "#/components/schemas/customer_request" required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml index 5fa69a8..a643e16 100644 --- a/descriptions/2.9/api.intercom.io.yaml +++ b/descriptions/2.9/api.intercom.io.yaml @@ -6115,7 +6115,7 @@ paths: - type: user id: 6657ab566abd0164c24b0d7d schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Not found content: @@ -6220,7 +6220,7 @@ paths: - type: user id: 6657ab636abd0164c24b0d89 schema: - "$ref": "#/components/schemas/conversation_customers_response" + "$ref": "#/components/schemas/conversation_participants_response" '404': description: Contact not found content: @@ -11251,25 +11251,25 @@ components: "$ref": "#/components/schemas/customer_request" required: - email - conversation_customers_response: - title: Conversation Customers Response + conversation_participants_response: + title: Conversation Participants Response type: object - description: The contacts participating in the conversation, returned after - attaching or detaching a contact + description: The participants of the conversation, returned after attaching + or detaching a contact properties: customers: type: array - description: The contacts participating in the conversation after the change + description: The conversation participants after the change items: type: object properties: type: type: string - description: The role of the contact. Can be "user" or "lead" + description: The role of the participant. Can be "user" or "lead" example: 'user' id: type: string - description: The unique identifier for the contact + description: The unique identifier for the participant example: '6762f1a61bb69f9f2193bbd8' required: - type From 5d6515b8c6eea886f322e72f6b9335118daea607 Mon Sep 17 00:00:00 2001 From: cox512 Date: Wed, 2 Sep 2026 14:54:51 -0500 Subject: [PATCH 4/4] Revert two unrelated contact-ID descriptions The participant rename matched as a prefix of an unrelated bulk-contact description, so those two lines now read contact again. Bulk contact operations act on any contact, not only conversation participants. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YXXKa8L8m446cLYBiqtsWF --- descriptions/0/api.intercom.io.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index f76d5d5..10dfcba 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -29714,7 +29714,7 @@ components: properties: id: type: string - description: The unique identifier for the participant. + description: The unique identifier for the contact. example: abc123 job: type: object @@ -29743,7 +29743,7 @@ components: properties: id: type: string - description: The unique identifier for the participant. + description: The unique identifier for the contact. example: abc123 external_id: type: string