Document that ticket comments are not supported on internal ticket types (#671)

* Document that ticket comments are not supported on internal ticket types

POST /tickets/{id}/reply does not support message_type: comment on tracker
tickets, or on back-office tickets that are not shared with the customer. Both
are internal ticket types with no customer to send a comment to, but the
reference did not say so.

The same wording is added to every version that documents an admin reply:
Preview (descriptions/0) and 2.10 through 2.16. Earlier versions define no
admin reply schema.

* Document the 400 returned when a ticket reply is rejected

The reply endpoint's 400 response was described as "User reply" and carried a
single example, so it covered only a user reply on a back-office ticket. It now
also describes the rejections for an admin comment on a back-office ticket that
is not shared with the customer, and on a tracker ticket.

Version 2.10 declared no 400 on this operation at all, so the response is added
there.

Author: dan0505

descriptions/0/api.intercom.io.yaml

@@ -23512,7 +23512,7 @@ paths:
       - Tickets
       responses:
         '400':
-          description: User reply
+          description: Bad Request
           content:
             application/json:
               examples:
@@ -23523,6 +23523,21 @@ paths:
                     errors:
                     - code: parameter_mismatch
                       message: User replies are not allowed on Backoffice tickets
+                Admin comment on a back-office ticket:
+                  value:
+                    type: error.list
+                    request_id: 7a1c9f02-5d3e-4b8a-9c21-6f0d84e5b713
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Backoffice tickets not
+                        shared with user
+                Admin comment on a tracker ticket:
+                  value:
+                    type: error.list
+                    request_id: c4e2a980-31bf-4d76-8a05-2e9cb17f4d6a
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Tracker tickets
               schema:
                 "$ref": "#/components/schemas/error"
         '200':
@@ -28207,6 +28222,9 @@ components:
       properties:
         message_type:
           type: string
+          description: The type of reply. Tracker tickets and back-office tickets
+            that are not shared with the customer do not support `comment`; use
+            `note` instead.
           enum:
           - comment
           - note

descriptions/2.10/api.intercom.io.yaml

@@ -9445,6 +9445,35 @@ paths:
       tags:
       - Tickets
       responses:
+        '400':
+          description: Bad Request
+          content:
+            application/json:
+              examples:
+                User reply:
+                  value:
+                    type: error.list
+                    request_id: b8b42c55-347c-4704-b4c1-92220c01f4ac
+                    errors:
+                    - code: parameter_mismatch
+                      message: User replies are not allowed on Backoffice tickets
+                Admin comment on a back-office ticket:
+                  value:
+                    type: error.list
+                    request_id: 7a1c9f02-5d3e-4b8a-9c21-6f0d84e5b713
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Backoffice tickets not
+                        shared with user
+                Admin comment on a tracker ticket:
+                  value:
+                    type: error.list
+                    request_id: c4e2a980-31bf-4d76-8a05-2e9cb17f4d6a
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Tracker tickets
+              schema:
+                "$ref": "#/components/schemas/error"
         '200':
           description: Admin quick_reply reply
           content:
@@ -11248,6 +11277,9 @@ components:
       properties:
         message_type:
           type: string
+          description: The type of reply. Tracker tickets and back-office tickets
+            that are not shared with the customer do not support `comment`; use
+            `note` instead.
           enum:
           - comment
           - note

descriptions/2.11/api.intercom.io.yaml

@@ -9534,7 +9534,7 @@ paths:
       - Tickets
       responses:
         '400':
-          description: User reply
+          description: Bad Request
           content:
             application/json:
               examples:
@@ -9545,6 +9545,21 @@ paths:
                     errors:
                     - code: parameter_mismatch
                       message: User replies are not allowed on Backoffice tickets
+                Admin comment on a back-office ticket:
+                  value:
+                    type: error.list
+                    request_id: 7a1c9f02-5d3e-4b8a-9c21-6f0d84e5b713
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Backoffice tickets not
+                        shared with user
+                Admin comment on a tracker ticket:
+                  value:
+                    type: error.list
+                    request_id: c4e2a980-31bf-4d76-8a05-2e9cb17f4d6a
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Tracker tickets
               schema:
                 "$ref": "#/components/schemas/error"
         '200':
@@ -11364,6 +11379,9 @@ components:
       properties:
         message_type:
           type: string
+          description: The type of reply. Tracker tickets and back-office tickets
+            that are not shared with the customer do not support `comment`; use
+            `note` instead.
           enum:
           - comment
           - note

descriptions/2.12/api.intercom.io.yaml

@@ -10247,7 +10247,7 @@ paths:
       - Tickets
       responses:
         '400':
-          description: User reply
+          description: Bad Request
           content:
             application/json:
               examples:
@@ -10258,6 +10258,21 @@ paths:
                     errors:
                     - code: parameter_mismatch
                       message: User replies are not allowed on Backoffice tickets
+                Admin comment on a back-office ticket:
+                  value:
+                    type: error.list
+                    request_id: 7a1c9f02-5d3e-4b8a-9c21-6f0d84e5b713
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Backoffice tickets not
+                        shared with user
+                Admin comment on a tracker ticket:
+                  value:
+                    type: error.list
+                    request_id: c4e2a980-31bf-4d76-8a05-2e9cb17f4d6a
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Tracker tickets
               schema:
                 "$ref": "#/components/schemas/error"
         '200':
@@ -12089,6 +12104,9 @@ components:
       properties:
         message_type:
           type: string
+          description: The type of reply. Tracker tickets and back-office tickets
+            that are not shared with the customer do not support `comment`; use
+            `note` instead.
           enum:
           - comment
           - note

descriptions/2.13/api.intercom.io.yaml

@@ -11475,7 +11475,7 @@ paths:
       - Tickets
       responses:
         '400':
-          description: User reply
+          description: Bad Request
           content:
             application/json:
               examples:
@@ -11486,6 +11486,21 @@ paths:
                     errors:
                     - code: parameter_mismatch
                       message: User replies are not allowed on Backoffice tickets
+                Admin comment on a back-office ticket:
+                  value:
+                    type: error.list
+                    request_id: 7a1c9f02-5d3e-4b8a-9c21-6f0d84e5b713
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Backoffice tickets not
+                        shared with user
+                Admin comment on a tracker ticket:
+                  value:
+                    type: error.list
+                    request_id: c4e2a980-31bf-4d76-8a05-2e9cb17f4d6a
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Tracker tickets
               schema:
                 "$ref": "#/components/schemas/error"
         '200':
@@ -13459,6 +13474,9 @@ components:
       properties:
         message_type:
           type: string
+          description: The type of reply. Tracker tickets and back-office tickets
+            that are not shared with the customer do not support `comment`; use
+            `note` instead.
           enum:
           - comment
           - note

descriptions/2.14/api.intercom.io.yaml

@@ -12883,7 +12883,7 @@ paths:
       - Tickets
       responses:
         '400':
-          description: User reply
+          description: Bad Request
           content:
             application/json:
               examples:
@@ -12894,6 +12894,21 @@ paths:
                     errors:
                     - code: parameter_mismatch
                       message: User replies are not allowed on Backoffice tickets
+                Admin comment on a back-office ticket:
+                  value:
+                    type: error.list
+                    request_id: 7a1c9f02-5d3e-4b8a-9c21-6f0d84e5b713
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Backoffice tickets not
+                        shared with user
+                Admin comment on a tracker ticket:
+                  value:
+                    type: error.list
+                    request_id: c4e2a980-31bf-4d76-8a05-2e9cb17f4d6a
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Tracker tickets
               schema:
                 "$ref": "#/components/schemas/error"
         '200':
@@ -15076,6 +15091,9 @@ components:
       properties:
         message_type:
           type: string
+          description: The type of reply. Tracker tickets and back-office tickets
+            that are not shared with the customer do not support `comment`; use
+            `note` instead.
           enum:
           - comment
           - note

descriptions/2.15/api.intercom.io.yaml

@@ -12866,7 +12866,7 @@ paths:
       - Tickets
       responses:
         '400':
-          description: User reply
+          description: Bad Request
           content:
             application/json:
               examples:
@@ -12877,6 +12877,21 @@ paths:
                     errors:
                     - code: parameter_mismatch
                       message: User replies are not allowed on Backoffice tickets
+                Admin comment on a back-office ticket:
+                  value:
+                    type: error.list
+                    request_id: 7a1c9f02-5d3e-4b8a-9c21-6f0d84e5b713
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Backoffice tickets not
+                        shared with user
+                Admin comment on a tracker ticket:
+                  value:
+                    type: error.list
+                    request_id: c4e2a980-31bf-4d76-8a05-2e9cb17f4d6a
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Tracker tickets
               schema:
                 "$ref": "#/components/schemas/error"
         '200':
@@ -15709,6 +15724,9 @@ components:
       properties:
         message_type:
           type: string
+          description: The type of reply. Tracker tickets and back-office tickets
+            that are not shared with the customer do not support `comment`; use
+            `note` instead.
           enum:
           - comment
           - note

descriptions/2.16/api.intercom.io.yaml

@@ -19506,7 +19506,7 @@ paths:
       - Tickets
       responses:
         '400':
-          description: User reply
+          description: Bad Request
           content:
             application/json:
               examples:
@@ -19517,6 +19517,21 @@ paths:
                     errors:
                     - code: parameter_mismatch
                       message: User replies are not allowed on Backoffice tickets
+                Admin comment on a back-office ticket:
+                  value:
+                    type: error.list
+                    request_id: 7a1c9f02-5d3e-4b8a-9c21-6f0d84e5b713
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Backoffice tickets not
+                        shared with user
+                Admin comment on a tracker ticket:
+                  value:
+                    type: error.list
+                    request_id: c4e2a980-31bf-4d76-8a05-2e9cb17f4d6a
+                    errors:
+                    - code: parameter_mismatch
+                      message: Comments are not allowed on Tracker tickets
               schema:
                 "$ref": "#/components/schemas/error"
         '200':
@@ -22959,6 +22974,9 @@ components:
       properties:
         message_type:
           type: string
+          description: The type of reply. Tracker tickets and back-office tickets
+            that are not shared with the customer do not support `comment`; use
+            `note` instead.
           enum:
           - comment
           - note