Correct the 200 response schema for attaching and detaching a contact (#655)

* 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YXXKa8L8m446cLYBiqtsWF

* 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YXXKa8L8m446cLYBiqtsWF

* 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YXXKa8L8m446cLYBiqtsWF

* 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YXXKa8L8m446cLYBiqtsWF

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: cox512

descriptions/0/api.intercom.io.yaml

@@ -14556,7 +14556,7 @@ paths:
                     - type: user
                       id: 6762f19b1bb69f9f2193bbd4
               schema:
-                "$ref": "#/components/schemas/conversation"
+                "$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"
+                "$ref": "#/components/schemas/conversation_participants_response"
         '404':
           description: Contact not found
           content:
@@ -29100,6 +29100,34 @@ components:
                 "$ref": "#/components/schemas/customer_request"
             required:
             - email
+    conversation_participants_response:
+      title: Conversation Participants Response
+      type: object
+      description: The participants of the conversation, returned after attaching
+        or detaching a contact
+      properties:
+        customers:
+          type: array
+          description: The conversation participants after the change
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                description: The role of the participant. Can be "user" or "lead"
+                example: 'user'
+              id:
+                type: string
+                description: The unique identifier for the participant
+                example: '6762f1a61bb69f9f2193bbd8'
+            required:
+            - type
+            - id
+          example:
+          - type: user
+            id: '6762f1a61bb69f9f2193bbd8'
+      required:
+      - customers
     team_metric:
       type: object
       description: Per-admin activity metrics within a team.

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_participants_response"
         '404':
           description: Not found
           content:
@@ -6076,7 +6076,7 @@ paths:
                     - type: user
                       id: 6657acdb6abd0166b52ae2a2
               schema:
-                "$ref": "#/components/schemas/conversation"
+                "$ref": "#/components/schemas/conversation_participants_response"
         '404':
           description: Contact not found
           content:
@@ -11937,6 +11937,34 @@ components:
                 "$ref": "#/components/schemas/customer_request"
             required:
             - email
+    conversation_participants_response:
+      title: Conversation Participants Response
+      type: object
+      description: The participants of the conversation, returned after attaching
+        or detaching a contact
+      properties:
+        customers:
+          type: array
+          description: The conversation participants after the change
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                description: The role of the participant. Can be "user" or "lead"
+                example: 'user'
+              id:
+                type: string
+                description: The unique identifier for the participant
+                example: '6762f1a61bb69f9f2193bbd8'
+            required:
+            - type
+            - id
+          example:
+          - type: user
+            id: '6762f1a61bb69f9f2193bbd8'
+      required:
+      - customers
     close_conversation_request:
       title: Close Conversation Request
       type: object

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_participants_response"
         '404':
           description: Not found
           content:
@@ -6186,7 +6186,7 @@ paths:
                     - type: user
                       id: 667d61228a68186f43bafe19
               schema:
-                "$ref": "#/components/schemas/conversation"
+                "$ref": "#/components/schemas/conversation_participants_response"
         '404':
           description: Contact not found
           content:
@@ -12179,6 +12179,34 @@ components:
                 nullable: true
             required:
             - email
+    conversation_participants_response:
+      title: Conversation Participants Response
+      type: object
+      description: The participants of the conversation, returned after attaching
+        or detaching a contact
+      properties:
+        customers:
+          type: array
+          description: The conversation participants after the change
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                description: The role of the participant. Can be "user" or "lead"
+                example: 'user'
+              id:
+                type: string
+                description: The unique identifier for the participant
+                example: '6762f1a61bb69f9f2193bbd8'
+            required:
+            - type
+            - id
+          example:
+          - type: user
+            id: '6762f1a61bb69f9f2193bbd8'
+      required:
+      - customers
     button_component:
       title: Button Component
       type: object

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_participants_response"
         '404':
           description: Not found
           content:
@@ -6596,7 +6596,7 @@ paths:
                     - type: user
                       id: 677c56016abd011ad17ff54d
               schema:
-                "$ref": "#/components/schemas/conversation"
+                "$ref": "#/components/schemas/conversation_participants_response"
         '404':
           description: Contact not found
           content:
@@ -12843,6 +12843,34 @@ components:
                 "$ref": "#/components/schemas/customer_request"
             required:
             - email
+    conversation_participants_response:
+      title: Conversation Participants Response
+      type: object
+      description: The participants of the conversation, returned after attaching
+        or detaching a contact
+      properties:
+        customers:
+          type: array
+          description: The conversation participants after the change
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                description: The role of the participant. Can be "user" or "lead"
+                example: 'user'
+              id:
+                type: string
+                description: The unique identifier for the participant
+                example: '6762f1a61bb69f9f2193bbd8'
+            required:
+            - type
+            - id
+          example:
+          - type: user
+            id: '6762f1a61bb69f9f2193bbd8'
+      required:
+      - customers
     close_conversation_request:
       title: Close Conversation Request
       type: object

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_participants_response"
         '404':
           description: Not found
           content:
@@ -7581,7 +7581,7 @@ paths:
                     - type: user
                       id: 677c56016abd011ad17ff54d
               schema:
-                "$ref": "#/components/schemas/conversation"
+                "$ref": "#/components/schemas/conversation_participants_response"
         '404':
           description: Contact not found
           content:
@@ -14294,6 +14294,34 @@ components:
                 "$ref": "#/components/schemas/customer_request"
             required:
             - email
+    conversation_participants_response:
+      title: Conversation Participants Response
+      type: object
+      description: The participants of the conversation, returned after attaching
+        or detaching a contact
+      properties:
+        customers:
+          type: array
+          description: The conversation participants after the change
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                description: The role of the participant. Can be "user" or "lead"
+                example: 'user'
+              id:
+                type: string
+                description: The unique identifier for the participant
+                example: '6762f1a61bb69f9f2193bbd8'
+            required:
+            - type
+            - id
+          example:
+          - type: user
+            id: '6762f1a61bb69f9f2193bbd8'
+      required:
+      - customers
     close_conversation_request:
       title: Close Conversation Request
       type: object

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_participants_response"
         '404':
           description: Not found
           content:
@@ -8564,7 +8564,7 @@ paths:
                     - type: user
                       id: 6762f1b41bb69f9f2193bbe0
               schema:
-                "$ref": "#/components/schemas/conversation"
+                "$ref": "#/components/schemas/conversation_participants_response"
         '404':
           description: Contact not found
           content:
@@ -15951,6 +15951,34 @@ components:
                 "$ref": "#/components/schemas/customer_request"
             required:
             - email
+    conversation_participants_response:
+      title: Conversation Participants Response
+      type: object
+      description: The participants of the conversation, returned after attaching
+        or detaching a contact
+      properties:
+        customers:
+          type: array
+          description: The conversation participants after the change
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                description: The role of the participant. Can be "user" or "lead"
+                example: 'user'
+              id:
+                type: string
+                description: The unique identifier for the participant
+                example: '6762f1a61bb69f9f2193bbd8'
+            required:
+            - type
+            - id
+          example:
+          - type: user
+            id: '6762f1a61bb69f9f2193bbd8'
+      required:
+      - customers
     away_status_reason:
       type: object
       properties:

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_participants_response"
         '404':
           description: Not found
           content:
@@ -8487,7 +8487,7 @@ paths:
                     - type: user
                       id: 6762f1b41bb69f9f2193bbe0
               schema:
-                "$ref": "#/components/schemas/conversation"
+                "$ref": "#/components/schemas/conversation_participants_response"
         '404':
           description: Contact not found
           content:
@@ -16636,6 +16636,34 @@ components:
                 "$ref": "#/components/schemas/customer_request"
             required:
             - email
+    conversation_participants_response:
+      title: Conversation Participants Response
+      type: object
+      description: The participants of the conversation, returned after attaching
+        or detaching a contact
+      properties:
+        customers:
+          type: array
+          description: The conversation participants after the change
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                description: The role of the participant. Can be "user" or "lead"
+                example: 'user'
+              id:
+                type: string
+                description: The unique identifier for the participant
+                example: '6762f1a61bb69f9f2193bbd8'
+            required:
+            - type
+            - id
+          example:
+          - type: user
+            id: '6762f1a61bb69f9f2193bbd8'
+      required:
+      - customers
     brand:
       type: object
       title: Brand