From 5eb73ee870ee0ae05c00bfb695d8f160fb72a1be Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Thu, 27 Aug 2026 13:43:34 +0100 Subject: [PATCH 1/7] 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 a2e39ee5..c637a03e 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -37103,19 +37103,61 @@ components: type: string description: The text of the matched guidance rule. example: If the customer asks about pricing, ask which plan they're interested in before answering + 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 @@ -37125,6 +37167,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 c380715f55f4950feb775178594265229a52af70 Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Thu, 27 Aug 2026 15:07:02 +0100 Subject: [PATCH 2/7] 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 c637a03e..27ce85d4 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -37106,8 +37106,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: @@ -37128,8 +37130,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: @@ -37149,7 +37153,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 e7d5591032087ffd32c1ced38ae783ee17b0a78b Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Thu, 27 Aug 2026 17:51:15 +0100 Subject: [PATCH 3/7] 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 27ce85d4..9e6a559a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -36670,7 +36670,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: @@ -37150,11 +37150,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 @@ -37179,6 +37180,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 @@ -44768,7 +44788,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 12c11d2121fc0e8efbf1fee98c8e719aba6a81e4 Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Thu, 27 Aug 2026 18:06:25 +0100 Subject: [PATCH 4/7] 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 9e6a559a..f76f26cf 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -37160,6 +37160,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" @@ -37191,6 +37193,8 @@ components: anyOf: - type: string - type: integer + - type: number + - type: boolean - $ref: "#/components/schemas/datetime" - "$ref": "#/components/schemas/custom_object_instance_list" example: From b3e5a88f4116f48b6d646d9cb073210d21979b10 Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Thu, 27 Aug 2026 18:10:32 +0100 Subject: [PATCH 5/7] 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 f76f26cf..59f80670 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -37185,10 +37185,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 fc70c4a1938cfc155e15e7355d6db73630d9994d Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Fri, 28 Aug 2026 14:50:40 +0100 Subject: [PATCH 6/7] 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 59f80670..59717643 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -37150,8 +37150,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 From 2c247dfdd5c0de49517085740162ed27f18f47a7 Mon Sep 17 00:00:00 2001 From: anubhav-intercom Date: Tue, 13 Oct 2026 18:34:36 +0100 Subject: [PATCH 7/7] Document AI Topic and Subtopic and CX Score reasons in 2.17 conversation custom_attributes Co-Authored-By: Claude Opus 5.5 --- descriptions/2.17/api.intercom.io.yaml | 86 ++++++++++++++++++++++++-- 1 file changed, 82 insertions(+), 4 deletions(-) diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 730ddd78..d88fc8f1 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -33267,7 +33267,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: @@ -33599,19 +33599,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 @@ -33621,6 +33671,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 @@ -40312,7 +40390,7 @@ components: description: The title given to the conversation example: Conversation Title 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.