From 978452474eb4b339f230654832a3ce93a63f5b5a Mon Sep 17 00:00:00 2001 From: Shane Harding Date: Thu, 24 Sep 2026 17:49:20 +0200 Subject: [PATCH 1/2] Document readable evaluator fields on QA scorecards (Preview) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Evaluator ids, rating-option values, and reason ids in scorecards[].evaluators[] were unresolvable without a separate lookup — this documents the name, value_label, and reasons fields intercom/intercom#582447 adds in Preview. Co-Authored-By: Claude Opus 5.5 --- descriptions/0/api.intercom.io.yaml | 35 +++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a5e8540b..4ae179ff 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12515,8 +12515,10 @@ paths: body: Great empathy in the second reply. evaluators: - evaluator_id: '54321' + name: Tone of voice result: value: pass + value_label: Pass source: ai reasoning: The agent acknowledged the issue and resolved it within the same response. schema: @@ -13227,8 +13229,10 @@ paths: body: Great empathy in the second reply. evaluators: - evaluator_id: '54321' + name: Tone of voice result: value: pass + value_label: Pass source: ai reasoning: The agent acknowledged the issue and resolved it within the same response. schema: @@ -13969,8 +13973,10 @@ paths: body: Great empathy in the second reply. evaluators: - evaluator_id: '54321' + name: Tone of voice result: value: pass + value_label: Pass source: ai reasoning: The agent acknowledged the issue and resolved it within the same response. schema: @@ -33726,6 +33732,11 @@ components: type: string description: The unique identifier of the evaluator (criterion) within the scorecard. example: '54321' + name: + type: string + nullable: true + description: The name of the evaluator (criterion). Null if the evaluator's name could not be resolved. + example: Tone of voice result: allOf: - "$ref": "#/components/schemas/conversation_scorecard_evaluator_result" @@ -33743,6 +33754,10 @@ components: nullable: true description: The evaluator's selected value (typically a label such as `pass`, `fail`, or a category identifier). example: pass + value_label: + type: string + description: The label of the rating option matching `value` (for example `Needs improvement`). Omitted when the label could not be resolved. + example: Pass source: type: string nullable: true @@ -33762,11 +33777,31 @@ components: example: - '101' - '102' + reasons: + type: array + description: The names of the structured reasons in `reason_ids`, one entry per id, in the same order. Omitted when the result has no `reason_ids`. + items: + "$ref": "#/components/schemas/conversation_scorecard_evaluator_reason" + example: + - name: Clear and concise + - name: Empathetic tone other_text: type: string nullable: true description: Free-text entered by the reviewer to supplement or stand in for the structured `reason_ids` — typically captured when the reviewer selects an "Other" option or adds a custom note. Null when not provided. example: Agent acknowledged the issue but missed the follow-up question about billing. + conversation_scorecard_evaluator_reason: + title: Evaluator Reason + type: object + x-tags: + - Conversations + description: A single structured reason assigned to an evaluator's result. + properties: + name: + type: string + nullable: true + description: The name of the reason. Null if the reason's name could not be resolved. + example: Clear and concise conversation_channel: title: Conversation Channel type: object From 386643a015a867a187b95c4f23bbb00f9cfdb24d Mon Sep 17 00:00:00 2001 From: Shane Harding Date: Fri, 25 Sep 2026 17:03:58 +0200 Subject: [PATCH 2/2] Show reasons in the scorecard evaluator examples The examples documented name and value_label but not reasons, so readers couldn't see the new field in a response. Co-Authored-By: Claude Opus 5.5 --- descriptions/0/api.intercom.io.yaml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 4ae179ff..80e0889d 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -12521,6 +12521,12 @@ paths: value_label: Pass source: ai reasoning: The agent acknowledged the issue and resolved it within the same response. + reason_ids: + - '101' + - '102' + reasons: + - name: Clear and concise + - name: Empathetic tone schema: "$ref": "#/components/schemas/conversation_list" '401': @@ -13235,6 +13241,12 @@ paths: value_label: Pass source: ai reasoning: The agent acknowledged the issue and resolved it within the same response. + reason_ids: + - '101' + - '102' + reasons: + - name: Clear and concise + - name: Empathetic tone schema: "$ref": "#/components/schemas/conversation" '404': @@ -13979,6 +13991,12 @@ paths: value_label: Pass source: ai reasoning: The agent acknowledged the issue and resolved it within the same response. + reason_ids: + - '101' + - '102' + reasons: + - name: Clear and concise + - name: Empathetic tone schema: "$ref": "#/components/schemas/conversation_list" requestBody: