From 835107bd8973f46e27f85def09f1402d8e0a736f Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Thu, 27 Aug 2026 13:43:34 +0100 Subject: [PATCH 1/6] Document AI insights attributes in a conversation's custom_attributes Co-Authored-By: Claude Fable 5 --- descriptions/0/api.intercom.io.yaml | 51 ++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index de71fc0..2f14c33 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -34115,19 +34115,61 @@ components: example: 0 pages: "$ref": "#/components/schemas/cursor_pages" + ai_topic_subtopic_list: + title: AI Topic and Subtopic + type: array + description: The topics Fin detected in a conversation, returned under the "AI + Topic and Subtopic" key of a conversation's custom attributes. + 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 + description: The reasons behind a conversation's CX Score, returned under the + "CX Score reasons" key of a conversation's custom attributes. + 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. + such as "CX Score rating" and "CX Score explanation" may also be included, + as may the AI insights attributes "AI Topic and Subtopic" and "CX Score reasons", + whose values are lists of objects. additionalProperties: anyOf: - type: string - type: integer - $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 +34179,13 @@ 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_object_instance: title: Custom Object Instance type: object From 978ea6ba4e8611c38444f4e6f5eff33695395b8e Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Thu, 27 Aug 2026 15:07:02 +0100 Subject: [PATCH 2/6] Mark the AI insights attribute values as response-only The custom_attributes schema is shared by request bodies (update_conversation_request, create_phone_switch_request) as well as the conversation responses, so adding the two AI insight array types to its anyOf advertised server-generated values as valid input. Flag both schemas readOnly, following the convention already used in this spec, and say so in the descriptions. Co-Authored-By: Claude Fable 5 --- descriptions/0/api.intercom.io.yaml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 2f14c33..5aadce9 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -34118,8 +34118,10 @@ components: 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. + 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: @@ -34140,8 +34142,10 @@ components: 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. + "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: @@ -34161,7 +34165,8 @@ components: 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, as may the AI insights attributes "AI Topic and Subtopic" and "CX Score reasons", - whose values are lists of objects. + whose values are lists of objects. The AI insights attributes are generated + by Fin and appear in responses only; they cannot be set on a request. additionalProperties: anyOf: - type: string From f16528e3584b59d223d32a32987a2287588a9612 Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Thu, 27 Aug 2026 17:51:15 +0100 Subject: [PATCH 3/6] Split custom_attributes into request and response variants The two AI insights array shapes are response-only, but readOnly is not honoured on additionalProperties value schemas, so write request bodies inherited them. Request bodies now point at custom_attributes_request. Also reword the schema description so the two documented attributes are not framed as the only AI insights attributes. Co-Authored-By: Claude Fable 5 --- descriptions/0/api.intercom.io.yaml | 34 +++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 7 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 5aadce9..03675e9 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/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: @@ -34162,11 +34162,12 @@ components: 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, - as may the AI insights attributes "AI Topic and Subtopic" and "CX Score reasons", - whose values are lists of objects. The AI insights attributes are generated - by Fin and appear in responses only; they cannot be set on a request. + will be a list of custom object instance models. AI insights 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 @@ -34191,6 +34192,25 @@ components: CX Score reasons: - name: Resolution speed value: Fast + custom_attributes_request: + title: Custom Attributes (write) + type: object + description: An object containing the custom attributes to set on the conversation + 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 + - $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 @@ -41074,7 +41094,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. From 25bd4b61835a0e71fb39fff9926b2a04213d5a10 Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Thu, 27 Aug 2026 18:06:25 +0100 Subject: [PATCH 4/6] Accept boolean and decimal custom attribute values Both custom_attributes and custom_attributes_request declared only string and integer scalars, while their examples use paid_subscriber: true and monthly_spend: 155.5. Generated request types would have rejected valid updates. Adds number and boolean to both so the write variant stays a strict subset of the response variant, matching the ordering used by ticket_custom_attributes. Co-Authored-By: Claude Fable 5 --- descriptions/0/api.intercom.io.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 03675e9..df58fbe 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -34172,6 +34172,8 @@ components: 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" @@ -34203,6 +34205,8 @@ components: anyOf: - type: string - type: integer + - type: number + - type: boolean - $ref: "#/components/schemas/datetime" - "$ref": "#/components/schemas/custom_object_instance_list" example: From 824c5961ce5943946afd77163286f66d10162fc0 Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Thu, 27 Aug 2026 18:10:32 +0100 Subject: [PATCH 5/6] Make custom_attributes_request description resource-generic The write variant is shared by update_conversation_request and create_phone_switch_request, which sets attributes on a user or lead, so saying the attributes are set "on the conversation" misstated the target resource in the generated phone-switch docs. The response variant stays conversation-specific; all of its consumers are conversation responses. Co-Authored-By: Claude Fable 5 --- descriptions/0/api.intercom.io.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index df58fbe..86af4d0 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -34197,10 +34197,10 @@ components: custom_attributes_request: title: Custom Attributes (write) type: object - description: An object containing the custom attributes to set on the conversation - 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. + 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 From 0b2c3814b05d0a5e7499dada198e5c42197c53d2 Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Fri, 28 Aug 2026 14:50:40 +0100 Subject: [PATCH 6/6] Use customer-facing feature names instead of 'AI insights' 'AI insights' is internal naming; the help center refers to these features as Topics and CX Score under the Analyze section. Co-Authored-By: Claude Fable 5 --- 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 86af4d0..d5dd899 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -34162,8 +34162,8 @@ components: 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. AI insights attributes that - Intercom generates — such as "CX Score rating", "CX Score explanation", "AI + 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