Document Topics and CX Score reasons in a conversation's custom_attributes (Preview)

descriptions/0/api.intercom.io.yaml

@@ -33769,7 +33769,7 @@ components:
             continue the conversation in the Messenger.
           example: "+1 1234567890"
         custom_attributes:
-          "$ref": "#/components/schemas/custom_attributes"
+          "$ref": "#/components/schemas/custom_attributes_request"
       required:
       - phone
     create_ticket_reply_with_comment_request:
@@ -34115,19 +34115,69 @@ components:
           example: 0
         pages:
           "$ref": "#/components/schemas/cursor_pages"
+    ai_topic_subtopic_list:
+      title: AI Topic and Subtopic
+      type: array
+      readOnly: true
+      description: The topics Fin detected in a conversation, returned under the "AI
+        Topic and Subtopic" key of a conversation's custom attributes. Generated by
+        Fin and returned in responses only; it cannot be set on a request.
+      items:
+        type: object
+        properties:
+          topic_name:
+            type: string
+            description: The name of the topic.
+            example: Billing
+          subtopic_name:
+            type: string
+            nullable: true
+            description: The name of the subtopic, where the topic has one.
+            example: Refund request
+          id:
+            type: integer
+            nullable: true
+            description: The unique identifier for the subtopic.
+            example: 12345
+    cx_score_reason_list:
+      title: CX Score reasons
+      type: array
+      readOnly: true
+      description: The reasons behind a conversation's CX Score, returned under the
+        "CX Score reasons" key of a conversation's custom attributes. Generated by
+        Fin and returned in responses only; it cannot be set on a request.
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+            description: The name of the reason.
+            example: Resolution speed
+          value:
+            type: string
+            description: The value recorded for the reason.
+            example: Fast
     custom_attributes:
       title: Custom Attributes
       type: object
       description: An object containing the different custom attributes associated
         to the conversation as key-value pairs. For relationship attributes the value
-        will be a list of custom object instance models. System-defined attributes
-        such as "CX Score rating" and "CX Score explanation" may also be included.
+        will be a list of custom object instance models. Attributes that Intercom
+        generates — such as "CX Score rating", "CX Score explanation", "AI
+        Topic and Subtopic" and "CX Score reasons" — may also be included. Two of
+        them, "AI Topic and Subtopic" and "CX Score reasons", carry lists of objects
+        as their values, and are returned in responses only — they cannot be set on
+        a write request.
       additionalProperties:
         anyOf:
         - type: string
         - type: integer
+        - type: number
+        - type: boolean
         - $ref: "#/components/schemas/datetime"
         - "$ref": "#/components/schemas/custom_object_instance_list"
+        - "$ref": "#/components/schemas/ai_topic_subtopic_list"
+        - "$ref": "#/components/schemas/cx_score_reason_list"
       example:
         paid_subscriber: true
         monthly_spend: 155.5
@@ -34137,6 +34187,34 @@ components:
         CX Score rating: 4
         CX Score explanation: The conversation was resolved quickly and the customer
           expressed satisfaction with the outcome.
+        AI Topic and Subtopic:
+        - topic_name: Billing
+          subtopic_name: Refund request
+          id: 12345
+        CX Score reasons:
+        - name: Resolution speed
+          value: Fast
+    custom_attributes_request:
+      title: Custom Attributes (write)
+      type: object
+      description: The custom attributes which are set on this object, as key-value
+        pairs. For relationship attributes the value should be a list of custom object
+        instance models. Only attributes a caller may set are accepted here — attributes
+        Intercom generates are returned in responses only.
+      additionalProperties:
+        anyOf:
+        - type: string
+        - type: integer
+        - type: number
+        - type: boolean
+        - $ref: "#/components/schemas/datetime"
+        - "$ref": "#/components/schemas/custom_object_instance_list"
+      example:
+        paid_subscriber: true
+        monthly_spend: 155.5
+        team_mates: 9
+        start_date_iso8601: "2023-03-04T09:46:14Z"
+        end_date_timestamp: 1677923174
     custom_object_instance:
       title: Custom Object Instance
       type: object
@@ -41020,7 +41098,7 @@ components:
             Defaults to Operator when omitted, and is only used alongside priority.
           example: '394051'
         custom_attributes:
-          "$ref": "#/components/schemas/custom_attributes"
+          "$ref": "#/components/schemas/custom_attributes_request"
         company_id:
           type: string
           description: The ID of the company that the conversation is associated with.