From 9fd16d7432fb07108a80b8d9617a213ad0eb4115 Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Fri, 31 Jul 2026 14:23:18 +0100 Subject: [PATCH 1/5] Add POST /fin/csat and the csat_requested event Publish the Fin Agent API CSAT endpoint and its webhook/SSE event in the 2.14, 2.15, 2.16 and Preview specs. Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 224 +++++++++++++++++++++++- descriptions/2.14/api.intercom.io.yaml | 226 ++++++++++++++++++++++++- descriptions/2.15/api.intercom.io.yaml | 226 ++++++++++++++++++++++++- descriptions/2.16/api.intercom.io.yaml | 226 ++++++++++++++++++++++++- 4 files changed, 897 insertions(+), 5 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 059cb111..c0ce7c3a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -25437,6 +25437,149 @@ paths: name: John Doe email: john.doe@example.com message: I need help with my billing issue + "/fin/csat": + post: + summary: Submit a CSAT rating + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: submitFinCsat + description: | + Record a customer's satisfaction rating for a conversation, with an optional free-text + remark. + + Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin + workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks or + SSE carrying the rating options to show the user. Present those options, then submit the + user's choice here. + + Submitting the same rating again is a no-op and stays successful, so an at-least-once + client can safely retry. Submitting a *different* rating updates the stored rating while + the update window is still open, and a first remark can be added to an already-rated + survey. Once a remark has been recorded the rating is locked and can no longer be changed. + responses: + '200': + description: Rating recorded successfully + content: + application/json: + examples: + Successful response: + value: + conversation_id: ext-123 + rating: amazing + status: rated + schema: + type: object + properties: + conversation_id: + type: string + description: The external ID of the rated conversation. + example: ext-123 + rating: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The rating now recorded on the conversation. + example: amazing + status: + type: string + enum: + - rated + description: The result of the submission. + example: rated + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '422': + description: | + The rating could not be recorded. Common causes: no conversation exists for the given + `conversation_id`, Fin never requested a rating for it, the rating window has closed, + the rating is locked because a remark was already submitted, or `rating` is not one of + the supported values. + content: + application/json: + examples: + Conversation not found: + value: + errors: + external_conversation_id: Conversation not found for the given external_conversation_id + No rating requested: + value: + errors: + base: No rating survey found for this conversation + Rating window closed: + value: + errors: + base: The rating window for this conversation has closed + Rating locked by a remark: + value: + errors: + base: This rating can no longer be changed because a remark has already been submitted + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for conversation-level failures. + additionalProperties: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: Your external conversation ID — the same ID you started the conversation with, and the one echoed on the `csat_requested` event. + example: ext-123 + rating: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The rating the user selected — one of the `key` values from the `csat_requested` event's options. + example: amazing + remark: + type: string + description: Optional free-text comment the user left alongside the rating. Can be added to an already-rated survey, but only once — the rating locks after a remark is recorded. + example: Fin solved my problem in seconds. + required: + - conversation_id + - rating + examples: + Submit a rating: + value: + conversation_id: ext-123 + rating: amazing + Submit a rating with a remark: + value: + conversation_id: ext-123 + rating: amazing + remark: Fin solved my problem in seconds. "/fin/start": post: summary: Start a conversation with Fin @@ -36165,7 +36308,7 @@ components: - awaiting_user_reply: Fin has finished replying and is waiting for the user to respond - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event follows, and over SSE the stream is held open until it is delivered example: escalated reason: type: string @@ -36327,6 +36470,82 @@ components: - chunk_index - chunk_text - created_at_ms + fin_agent_csat_requested_event: + title: Fin Agent CSAT Requested Event + type: object + description: | + Event fired when Fin asks the user to rate the conversation. + Delivered via webhooks or SSE. Carries the rating options to present to the user; submit + the user's choice with POST /fin/csat. Unlike the reply events it has no message — a + rating survey is a set of options to choose from, not readable text. + Over SSE this event arrives after Fin reaches 'complete'. Because a survey is expected, + 'complete' does not close the stream: the connection is held open so this event can be + delivered, and the token is revoked once it is sent. + x-tags: + - Fin Agent + properties: + event_name: + type: string + enum: + - csat_requested + description: The name of the event. + example: csat_requested + conversation_id: + type: string + description: The ID of the conversation. + example: '123456' + user_id: + type: string + description: The ID of the user. + example: '7891' + csat: + type: object + description: The rating survey to present to the user. + properties: + options: + type: array + description: The ordered rating options to show the user. + items: + type: object + properties: + key: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The stable key to send back as 'rating' on POST /fin/csat. + example: amazing + emoji: + type: string + description: The emoji representing this rating. + example: "🤩" + label: + type: string + description: | + The human-readable label for this rating, localised to the conversation's + detected language. Distinct from 'key' — display the label, but send back + the key. + example: Amazing + required: + - key + - emoji + - label + required: + - options + created_at_ms: + type: string + format: date-time + description: The timestamp the event was created at, with millisecond precision. + example: '2025-01-24T10:00:00.123Z' + required: + - event_name + - conversation_id + - user_id + - csat + - created_at_ms file_attribute: title: File type: object @@ -40763,7 +40982,7 @@ tags:   - Orchestrate Fin from your own agent: discover what Fin can do with `/fin/capabilities`, ask a one-shot question with `/fin/ask`, run a specific procedure with `/fin/procedures/{procedure_id}/run`, continue a conversation with `/fin/reply`, and escalate to a human with `/fin/escalate`. Fin notifies your application of its status and responses through a set of events, delivered via webhooks or Server-Sent Events (SSE). + Orchestrate Fin from your own agent: discover what Fin can do with `/fin/capabilities`, ask a one-shot question with `/fin/ask`, run a specific procedure with `/fin/procedures/{procedure_id}/run`, continue a conversation with `/fin/reply`, escalate to a human with `/fin/escalate`, and record a satisfaction rating with `/fin/csat`. Fin notifies your application of its status and responses through a set of events, delivered via webhooks or Server-Sent Events (SSE).   @@ -40778,6 +40997,7 @@ tags: - `fin_status_updated` - Fired when Fin's status changes (awaiting_user_reply, escalated, resolved, complete) - `fin_replied` - Fired when Fin sends a reply to the user - `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled) + - `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`) All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation. - name: Help Center diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 6fcfd394..deeaaa73 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -2158,6 +2158,153 @@ paths: attachments: - type: url url: https://example.com/invoice.pdf + "/fin/csat": + post: + summary: Submit a CSAT rating + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: submitFinCsat + description: | + Record a customer's satisfaction rating for a conversation, with an optional free-text + remark. + + Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin + workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks or + SSE carrying the rating options to show the user. Present those options, then submit the + user's choice here. + + Submitting the same rating again is a no-op and stays successful, so an at-least-once + client can safely retry. Submitting a *different* rating updates the stored rating while + the update window is still open, and a first remark can be added to an already-rated + survey. Once a remark has been recorded the rating is locked and can no longer be changed. + + {% admonition type="warning" %} + Please reach out to your accounts team to discuss access. + {% /admonition %} + responses: + '200': + description: Rating recorded successfully + content: + application/json: + examples: + Successful response: + value: + conversation_id: ext-123 + rating: amazing + status: rated + schema: + type: object + properties: + conversation_id: + type: string + description: The external ID of the rated conversation. + example: ext-123 + rating: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The rating now recorded on the conversation. + example: amazing + status: + type: string + enum: + - rated + description: The result of the submission. + example: rated + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '422': + description: | + The rating could not be recorded. Common causes: no conversation exists for the given + `conversation_id`, Fin never requested a rating for it, the rating window has closed, + the rating is locked because a remark was already submitted, or `rating` is not one of + the supported values. + content: + application/json: + examples: + Conversation not found: + value: + errors: + external_conversation_id: Conversation not found for the given external_conversation_id + No rating requested: + value: + errors: + base: No rating survey found for this conversation + Rating window closed: + value: + errors: + base: The rating window for this conversation has closed + Rating locked by a remark: + value: + errors: + base: This rating can no longer be changed because a remark has already been submitted + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for conversation-level failures. + additionalProperties: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: Your external conversation ID — the same ID you started the conversation with, and the one echoed on the `csat_requested` event. + example: ext-123 + rating: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The rating the user selected — one of the `key` values from the `csat_requested` event's options. + example: amazing + remark: + type: string + description: Optional free-text comment the user left alongside the rating. Can be added to an already-rated survey, but only once — the rating locks after a remark is recorded. + example: Fin solved my problem in seconds. + required: + - conversation_id + - rating + examples: + Submit a rating: + value: + conversation_id: ext-123 + rating: amazing + Submit a rating with a remark: + value: + conversation_id: ext-123 + rating: amazing + remark: Fin solved my problem in seconds. "/help_center/collections": get: summary: List all collections @@ -19983,7 +20130,7 @@ components: Fin's current status. - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event follows, and over SSE the stream is held open until it is delivered example: escalated reason: type: string @@ -20140,6 +20287,82 @@ components: - chunk_index - chunk_text - created_at_ms + fin_agent_csat_requested_event: + title: Fin Agent CSAT Requested Event + type: object + description: | + Event fired when Fin asks the user to rate the conversation. + Delivered via webhooks or SSE. Carries the rating options to present to the user; submit + the user's choice with POST /fin/csat. Unlike the reply events it has no message — a + rating survey is a set of options to choose from, not readable text. + Over SSE this event arrives after Fin reaches 'complete'. Because a survey is expected, + 'complete' does not close the stream: the connection is held open so this event can be + delivered, and the token is revoked once it is sent. + x-tags: + - Fin Agent + properties: + event_name: + type: string + enum: + - csat_requested + description: The name of the event. + example: csat_requested + conversation_id: + type: string + description: The ID of the conversation. + example: '123456' + user_id: + type: string + description: The ID of the user. + example: '7891' + csat: + type: object + description: The rating survey to present to the user. + properties: + options: + type: array + description: The ordered rating options to show the user. + items: + type: object + properties: + key: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The stable key to send back as 'rating' on POST /fin/csat. + example: amazing + emoji: + type: string + description: The emoji representing this rating. + example: "🤩" + label: + type: string + description: | + The human-readable label for this rating, localised to the conversation's + detected language. Distinct from 'key' — display the label, but send back + the key. + example: Amazing + required: + - key + - emoji + - label + required: + - options + created_at_ms: + type: string + format: date-time + description: The timestamp the event was created at, with millisecond precision. + example: '2025-01-24T10:00:00.123Z' + required: + - event_name + - conversation_id + - user_id + - csat + - created_at_ms file_attribute: title: File type: object @@ -23302,6 +23525,7 @@ tags: - `fin_status_updated` - Fired when Fin's status changes (escalated, resolved, complete) - `fin_replied` - Fired when Fin sends a reply to the user - `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled) + - `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`) All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation. - name: Help Center diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 8e2cf9bf..960356bc 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -14934,6 +14934,153 @@ paths: application/json: schema: $ref: "#/components/schemas/error" + "/fin/csat": + post: + summary: Submit a CSAT rating + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: submitFinCsat + description: | + Record a customer's satisfaction rating for a conversation, with an optional free-text + remark. + + Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin + workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks or + SSE carrying the rating options to show the user. Present those options, then submit the + user's choice here. + + Submitting the same rating again is a no-op and stays successful, so an at-least-once + client can safely retry. Submitting a *different* rating updates the stored rating while + the update window is still open, and a first remark can be added to an already-rated + survey. Once a remark has been recorded the rating is locked and can no longer be changed. + + {% admonition type="warning" %} + Please reach out to your accounts team to discuss access. + {% /admonition %} + responses: + '200': + description: Rating recorded successfully + content: + application/json: + examples: + Successful response: + value: + conversation_id: ext-123 + rating: amazing + status: rated + schema: + type: object + properties: + conversation_id: + type: string + description: The external ID of the rated conversation. + example: ext-123 + rating: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The rating now recorded on the conversation. + example: amazing + status: + type: string + enum: + - rated + description: The result of the submission. + example: rated + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '422': + description: | + The rating could not be recorded. Common causes: no conversation exists for the given + `conversation_id`, Fin never requested a rating for it, the rating window has closed, + the rating is locked because a remark was already submitted, or `rating` is not one of + the supported values. + content: + application/json: + examples: + Conversation not found: + value: + errors: + external_conversation_id: Conversation not found for the given external_conversation_id + No rating requested: + value: + errors: + base: No rating survey found for this conversation + Rating window closed: + value: + errors: + base: The rating window for this conversation has closed + Rating locked by a remark: + value: + errors: + base: This rating can no longer be changed because a remark has already been submitted + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for conversation-level failures. + additionalProperties: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: Your external conversation ID — the same ID you started the conversation with, and the one echoed on the `csat_requested` event. + example: ext-123 + rating: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The rating the user selected — one of the `key` values from the `csat_requested` event's options. + example: amazing + remark: + type: string + description: Optional free-text comment the user left alongside the rating. Can be added to an already-rated survey, but only once — the rating locks after a remark is recorded. + example: Fin solved my problem in seconds. + required: + - conversation_id + - rating + examples: + Submit a rating: + value: + conversation_id: ext-123 + rating: amazing + Submit a rating with a remark: + value: + conversation_id: ext-123 + rating: amazing + remark: Fin solved my problem in seconds. "/export/workflows/{id}": get: summary: Export a workflow @@ -20895,7 +21042,7 @@ components: Fin's current status. - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event follows, and over SSE the stream is held open until it is delivered example: escalated reason: type: string @@ -21052,6 +21199,82 @@ components: - chunk_index - chunk_text - created_at_ms + fin_agent_csat_requested_event: + title: Fin Agent CSAT Requested Event + type: object + description: | + Event fired when Fin asks the user to rate the conversation. + Delivered via webhooks or SSE. Carries the rating options to present to the user; submit + the user's choice with POST /fin/csat. Unlike the reply events it has no message — a + rating survey is a set of options to choose from, not readable text. + Over SSE this event arrives after Fin reaches 'complete'. Because a survey is expected, + 'complete' does not close the stream: the connection is held open so this event can be + delivered, and the token is revoked once it is sent. + x-tags: + - Fin Agent + properties: + event_name: + type: string + enum: + - csat_requested + description: The name of the event. + example: csat_requested + conversation_id: + type: string + description: The ID of the conversation. + example: '123456' + user_id: + type: string + description: The ID of the user. + example: '7891' + csat: + type: object + description: The rating survey to present to the user. + properties: + options: + type: array + description: The ordered rating options to show the user. + items: + type: object + properties: + key: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The stable key to send back as 'rating' on POST /fin/csat. + example: amazing + emoji: + type: string + description: The emoji representing this rating. + example: "🤩" + label: + type: string + description: | + The human-readable label for this rating, localised to the conversation's + detected language. Distinct from 'key' — display the label, but send back + the key. + example: Amazing + required: + - key + - emoji + - label + required: + - options + created_at_ms: + type: string + format: date-time + description: The timestamp the event was created at, with millisecond precision. + example: '2025-01-24T10:00:00.123Z' + required: + - event_name + - conversation_id + - user_id + - csat + - created_at_ms file_attribute: title: File type: object @@ -24416,6 +24639,7 @@ tags: - `fin_status_updated` - Fired when Fin's status changes (escalated, resolved, complete) - `fin_replied` - Fired when Fin sends a reply to the user - `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled) + - `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`) All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation. - name: Help Center diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 2c3e6644..74a1393a 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -4303,6 +4303,153 @@ paths: attachments: - type: url url: https://example.com/invoice.pdf + "/fin/csat": + post: + summary: Submit a CSAT rating + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Fin Agent + operationId: submitFinCsat + description: | + Record a customer's satisfaction rating for a conversation, with an optional free-text + remark. + + Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin + workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks or + SSE carrying the rating options to show the user. Present those options, then submit the + user's choice here. + + Submitting the same rating again is a no-op and stays successful, so an at-least-once + client can safely retry. Submitting a *different* rating updates the stored rating while + the update window is still open, and a first remark can be added to an already-rated + survey. Once a remark has been recorded the rating is locked and can no longer be changed. + + {% admonition type="warning" %} + Please reach out to your accounts team to discuss access. + {% /admonition %} + responses: + '200': + description: Rating recorded successfully + content: + application/json: + examples: + Successful response: + value: + conversation_id: ext-123 + rating: amazing + status: rated + schema: + type: object + properties: + conversation_id: + type: string + description: The external ID of the rated conversation. + example: ext-123 + rating: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The rating now recorded on the conversation. + example: amazing + status: + type: string + enum: + - rated + description: The result of the submission. + example: rated + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: b68959ea-6328-4f70-83cb-e7913dba1542 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '422': + description: | + The rating could not be recorded. Common causes: no conversation exists for the given + `conversation_id`, Fin never requested a rating for it, the rating window has closed, + the rating is locked because a remark was already submitted, or `rating` is not one of + the supported values. + content: + application/json: + examples: + Conversation not found: + value: + errors: + external_conversation_id: Conversation not found for the given external_conversation_id + No rating requested: + value: + errors: + base: No rating survey found for this conversation + Rating window closed: + value: + errors: + base: The rating window for this conversation has closed + Rating locked by a remark: + value: + errors: + base: This rating can no longer be changed because a remark has already been submitted + schema: + type: object + properties: + errors: + type: object + description: Validation messages keyed by the field they apply to, or `base` for conversation-level failures. + additionalProperties: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + conversation_id: + type: string + description: Your external conversation ID — the same ID you started the conversation with, and the one echoed on the `csat_requested` event. + example: ext-123 + rating: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The rating the user selected — one of the `key` values from the `csat_requested` event's options. + example: amazing + remark: + type: string + description: Optional free-text comment the user left alongside the rating. Can be added to an already-rated survey, but only once — the rating locks after a remark is recorded. + example: Fin solved my problem in seconds. + required: + - conversation_id + - rating + examples: + Submit a rating: + value: + conversation_id: ext-123 + rating: amazing + Submit a rating with a remark: + value: + conversation_id: ext-123 + rating: amazing + remark: Fin solved my problem in seconds. "/help_center/help_centers/{help_center_id}/redirects": get: summary: List all redirects for a help center @@ -31327,7 +31474,7 @@ components: - awaiting_user_reply: Fin has finished replying and is waiting for the user to respond - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event follows, and over SSE the stream is held open until it is delivered example: escalated reason: type: string @@ -31488,6 +31635,82 @@ components: - chunk_index - chunk_text - created_at_ms + fin_agent_csat_requested_event: + title: Fin Agent CSAT Requested Event + type: object + description: | + Event fired when Fin asks the user to rate the conversation. + Delivered via webhooks or SSE. Carries the rating options to present to the user; submit + the user's choice with POST /fin/csat. Unlike the reply events it has no message — a + rating survey is a set of options to choose from, not readable text. + Over SSE this event arrives after Fin reaches 'complete'. Because a survey is expected, + 'complete' does not close the stream: the connection is held open so this event can be + delivered, and the token is revoked once it is sent. + x-tags: + - Fin Agent + properties: + event_name: + type: string + enum: + - csat_requested + description: The name of the event. + example: csat_requested + conversation_id: + type: string + description: The ID of the conversation. + example: '123456' + user_id: + type: string + description: The ID of the user. + example: '7891' + csat: + type: object + description: The rating survey to present to the user. + properties: + options: + type: array + description: The ordered rating options to show the user. + items: + type: object + properties: + key: + type: string + enum: + - terrible + - bad + - ok + - good + - amazing + description: The stable key to send back as 'rating' on POST /fin/csat. + example: amazing + emoji: + type: string + description: The emoji representing this rating. + example: "🤩" + label: + type: string + description: | + The human-readable label for this rating, localised to the conversation's + detected language. Distinct from 'key' — display the label, but send back + the key. + example: Amazing + required: + - key + - emoji + - label + required: + - options + created_at_ms: + type: string + format: date-time + description: The timestamp the event was created at, with millisecond precision. + example: '2025-01-24T10:00:00.123Z' + required: + - event_name + - conversation_id + - user_id + - csat + - created_at_ms file_attribute: title: File type: object @@ -35374,6 +35597,7 @@ tags: - `fin_status_updated` - Fired when Fin's status changes (awaiting_user_reply, escalated, resolved, complete) - `fin_replied` - Fired when Fin sends a reply to the user - `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled) + - `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`) All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation. - name: Help Center From e59aa8f9dda49f1faf4c6bf444809c012bfbb65c Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Fri, 31 Jul 2026 14:36:47 +0100 Subject: [PATCH 2/5] Qualify the no-op condition and mention /fin/csat in the tag description Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 9 +++++---- descriptions/2.14/api.intercom.io.yaml | 11 ++++++----- descriptions/2.15/api.intercom.io.yaml | 11 ++++++----- descriptions/2.16/api.intercom.io.yaml | 11 ++++++----- 4 files changed, 23 insertions(+), 19 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index c0ce7c3a..8c793b97 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -25457,10 +25457,11 @@ paths: SSE carrying the rating options to show the user. Present those options, then submit the user's choice here. - Submitting the same rating again is a no-op and stays successful, so an at-least-once - client can safely retry. Submitting a *different* rating updates the stored rating while - the update window is still open, and a first remark can be added to an already-rated - survey. Once a remark has been recorded the rating is locked and can no longer be changed. + Submitting the same rating again, with no new remark, is a no-op and stays successful, + so an at-least-once client can safely retry. Submitting a *different* rating updates the + stored rating while the update window is still open, and a first remark can be added to + an already-rated survey. Once a remark has been recorded the rating is locked and can no + longer be changed. responses: '200': description: Rating recorded successfully diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index deeaaa73..115f69c8 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -2178,10 +2178,11 @@ paths: SSE carrying the rating options to show the user. Present those options, then submit the user's choice here. - Submitting the same rating again is a no-op and stays successful, so an at-least-once - client can safely retry. Submitting a *different* rating updates the stored rating while - the update window is still open, and a first remark can be added to an already-rated - survey. Once a remark has been recorded the rating is locked and can no longer be changed. + Submitting the same rating again, with no new remark, is a no-op and stays successful, + so an at-least-once client can safely retry. Submitting a *different* rating updates the + stored rating while the update window is still open, and a first remark can be added to + an already-rated survey. Once a remark has been recorded the rating is locked and can no + longer be changed. {% admonition type="warning" %} Please reach out to your accounts team to discuss access. @@ -23514,7 +23515,7 @@ tags:   - Integration is centered around two endpoints (`/fin/start` and `/fin/reply`) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). + Integration is centered around two endpoints (`/fin/start` and `/fin/reply`) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`.   diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 960356bc..945b111d 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -14954,10 +14954,11 @@ paths: SSE carrying the rating options to show the user. Present those options, then submit the user's choice here. - Submitting the same rating again is a no-op and stays successful, so an at-least-once - client can safely retry. Submitting a *different* rating updates the stored rating while - the update window is still open, and a first remark can be added to an already-rated - survey. Once a remark has been recorded the rating is locked and can no longer be changed. + Submitting the same rating again, with no new remark, is a no-op and stays successful, + so an at-least-once client can safely retry. Submitting a *different* rating updates the + stored rating while the update window is still open, and a first remark can be added to + an already-rated survey. Once a remark has been recorded the rating is locked and can no + longer be changed. {% admonition type="warning" %} Please reach out to your accounts team to discuss access. @@ -24628,7 +24629,7 @@ tags:   - Integration is centered around two endpoints (`/fin/start` and `/fin/reply`) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). + Integration is centered around two endpoints (`/fin/start` and `/fin/reply`) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`.   diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 74a1393a..4f95db2e 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -4323,10 +4323,11 @@ paths: SSE carrying the rating options to show the user. Present those options, then submit the user's choice here. - Submitting the same rating again is a no-op and stays successful, so an at-least-once - client can safely retry. Submitting a *different* rating updates the stored rating while - the update window is still open, and a first remark can be added to an already-rated - survey. Once a remark has been recorded the rating is locked and can no longer be changed. + Submitting the same rating again, with no new remark, is a no-op and stays successful, + so an at-least-once client can safely retry. Submitting a *different* rating updates the + stored rating while the update window is still open, and a first remark can be added to + an already-rated survey. Once a remark has been recorded the rating is locked and can no + longer be changed. {% admonition type="warning" %} Please reach out to your accounts team to discuss access. @@ -35586,7 +35587,7 @@ tags:   - Integration is centered around two endpoints (`/fin/start` and `/fin/reply`) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). + Integration is centered around two endpoints (`/fin/start` and `/fin/reply`) and a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`.   From bba96010d971e81874c289963ef4b88c33574078 Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Fri, 31 Jul 2026 14:45:02 +0100 Subject: [PATCH 3/5] Soften the CSAT-follows-complete claim and add missing examples Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 19 ++++++++++++++++++- descriptions/2.14/api.intercom.io.yaml | 19 ++++++++++++++++++- descriptions/2.15/api.intercom.io.yaml | 19 ++++++++++++++++++- descriptions/2.16/api.intercom.io.yaml | 19 ++++++++++++++++++- 4 files changed, 72 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 8c793b97..52692230 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -25541,6 +25541,8 @@ paths: errors: type: object description: Validation messages keyed by the field they apply to, or `base` for conversation-level failures. + example: + base: The rating window for this conversation has closed additionalProperties: type: string requestBody: @@ -36309,7 +36311,7 @@ components: - awaiting_user_reply: Fin has finished replying and is waiting for the user to respond - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event follows, and over SSE the stream is held open until it is delivered + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, and over SSE the stream is held open until it is delivered or the token expires example: escalated reason: type: string @@ -36502,10 +36504,25 @@ components: csat: type: object description: The rating survey to present to the user. + example: + options: + - key: good + emoji: "😃" + label: Great + - key: amazing + emoji: "🤩" + label: Amazing properties: options: type: array description: The ordered rating options to show the user. + example: + - key: good + emoji: "😃" + label: Great + - key: amazing + emoji: "🤩" + label: Amazing items: type: object properties: diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 115f69c8..f42fde2e 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -2266,6 +2266,8 @@ paths: errors: type: object description: Validation messages keyed by the field they apply to, or `base` for conversation-level failures. + example: + base: The rating window for this conversation has closed additionalProperties: type: string requestBody: @@ -20131,7 +20133,7 @@ components: Fin's current status. - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event follows, and over SSE the stream is held open until it is delivered + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, and over SSE the stream is held open until it is delivered or the token expires example: escalated reason: type: string @@ -20319,10 +20321,25 @@ components: csat: type: object description: The rating survey to present to the user. + example: + options: + - key: good + emoji: "😃" + label: Great + - key: amazing + emoji: "🤩" + label: Amazing properties: options: type: array description: The ordered rating options to show the user. + example: + - key: good + emoji: "😃" + label: Great + - key: amazing + emoji: "🤩" + label: Amazing items: type: object properties: diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 945b111d..741d88aa 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -15042,6 +15042,8 @@ paths: errors: type: object description: Validation messages keyed by the field they apply to, or `base` for conversation-level failures. + example: + base: The rating window for this conversation has closed additionalProperties: type: string requestBody: @@ -21043,7 +21045,7 @@ components: Fin's current status. - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event follows, and over SSE the stream is held open until it is delivered + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, and over SSE the stream is held open until it is delivered or the token expires example: escalated reason: type: string @@ -21231,10 +21233,25 @@ components: csat: type: object description: The rating survey to present to the user. + example: + options: + - key: good + emoji: "😃" + label: Great + - key: amazing + emoji: "🤩" + label: Amazing properties: options: type: array description: The ordered rating options to show the user. + example: + - key: good + emoji: "😃" + label: Great + - key: amazing + emoji: "🤩" + label: Amazing items: type: object properties: diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 4f95db2e..d9e1738a 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -4411,6 +4411,8 @@ paths: errors: type: object description: Validation messages keyed by the field they apply to, or `base` for conversation-level failures. + example: + base: The rating window for this conversation has closed additionalProperties: type: string requestBody: @@ -31475,7 +31477,7 @@ components: - awaiting_user_reply: Fin has finished replying and is waiting for the user to respond - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event follows, and over SSE the stream is held open until it is delivered + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, and over SSE the stream is held open until it is delivered or the token expires example: escalated reason: type: string @@ -31667,10 +31669,25 @@ components: csat: type: object description: The rating survey to present to the user. + example: + options: + - key: good + emoji: "😃" + label: Great + - key: amazing + emoji: "🤩" + label: Amazing properties: options: type: array description: The ordered rating options to show the user. + example: + - key: good + emoji: "😃" + label: Great + - key: amazing + emoji: "🤩" + label: Amazing items: type: object properties: From ce6d5d5fe6122173501bd492dede4a5ea35ac8f1 Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Fri, 31 Jul 2026 15:07:41 +0100 Subject: [PATCH 4/5] Align SSE token-revocation wording with CSAT and add an invalid-rating example Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 14 +++++++++----- descriptions/2.14/api.intercom.io.yaml | 8 ++++++-- descriptions/2.15/api.intercom.io.yaml | 8 ++++++-- descriptions/2.16/api.intercom.io.yaml | 8 ++++++-- 4 files changed, 27 insertions(+), 11 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 52692230..a283e54e 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -24802,7 +24802,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -24977,7 +24977,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...' '400': description: Bad Request @@ -25162,7 +25162,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -25354,7 +25354,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. Includes a `rewind` window so a subscriber that connects after the escalation is processed can still receive the `escalated` and `complete` events. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. Includes a `rewind` window so a subscriber that connects after the escalation is processed can still receive the `escalated` and `complete` events. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' status: type: string @@ -25535,6 +25535,10 @@ paths: value: errors: base: This rating can no longer be changed because a remark has already been submitted + Invalid rating: + value: + errors: + rating: Rating isn't an option schema: type: object properties: @@ -25671,7 +25675,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index f42fde2e..411067b9 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -1890,7 +1890,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -2077,7 +2077,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...' '400': description: Bad Request @@ -2260,6 +2260,10 @@ paths: value: errors: base: This rating can no longer be changed because a remark has already been submitted + Invalid rating: + value: + errors: + rating: Rating isn't an option schema: type: object properties: diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 741d88aa..b6955ab4 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -1896,7 +1896,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -2083,7 +2083,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...' '400': description: Bad Request @@ -15036,6 +15036,10 @@ paths: value: errors: base: This rating can no longer be changed because a remark has already been submitted + Invalid rating: + value: + errors: + rating: Rating isn't an option schema: type: object properties: diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index d9e1738a..19094619 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -4034,7 +4034,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -4222,7 +4222,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...' '400': description: Bad Request @@ -4405,6 +4405,10 @@ paths: value: errors: base: This rating can no longer be changed because a remark has already been submitted + Invalid rating: + value: + errors: + rating: Rating isn't an option schema: type: object properties: From bf43c184c500155299c4783521a7011519ac8bcd Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Fri, 31 Jul 2026 15:19:38 +0100 Subject: [PATCH 5/5] Qualify CSAT deferral of SSE token revocation Deferral of `complete` token revocation applies when a CSAT survey will follow the resolution, not whenever CSAT is enabled. Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 12 ++++++------ descriptions/2.14/api.intercom.io.yaml | 6 +++--- descriptions/2.15/api.intercom.io.yaml | 6 +++--- descriptions/2.16/api.intercom.io.yaml | 6 +++--- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index a283e54e..2ecca2ec 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -24802,7 +24802,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -24977,7 +24977,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...' '400': description: Bad Request @@ -25162,7 +25162,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -25354,7 +25354,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. Includes a `rewind` window so a subscriber that connects after the escalation is processed can still receive the `escalated` and `complete` events. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. Includes a `rewind` window so a subscriber that connects after the escalation is processed can still receive the `escalated` and `complete` events. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' status: type: string @@ -25675,7 +25675,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -36315,7 +36315,7 @@ components: - awaiting_user_reply: Fin has finished replying and is waiting for the user to respond - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, and over SSE the stream is held open until it is delivered or the token expires + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires example: escalated reason: type: string diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 411067b9..01382ebf 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -1890,7 +1890,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -2077,7 +2077,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...' '400': description: Bad Request @@ -20137,7 +20137,7 @@ components: Fin's current status. - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, and over SSE the stream is held open until it is delivered or the token expires + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires example: escalated reason: type: string diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index b6955ab4..97dd42e6 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -1896,7 +1896,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -2083,7 +2083,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...' '400': description: Bad Request @@ -21049,7 +21049,7 @@ components: Fin's current status. - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, and over SSE the stream is held open until it is delivered or the token expires + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires example: escalated reason: type: string diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 19094619..e95e43e4 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -4034,7 +4034,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m' '400': description: Bad Request @@ -4222,7 +4222,7 @@ paths: sse_subscription_url: type: string description: | - Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled, `complete` revocation is deferred until the `csat_requested` survey is delivered. + Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...' '400': description: Bad Request @@ -31481,7 +31481,7 @@ components: - awaiting_user_reply: Fin has finished replying and is waiting for the user to respond - escalated: The conversation has been escalated to a human - resolved: The user's query has been resolved - - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, and over SSE the stream is held open until it is delivered or the token expires + - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires example: escalated reason: type: string