diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 059cb111..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. + 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. + 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. + 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. 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 @@ -25437,6 +25437,156 @@ 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, 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 + 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 + Invalid rating: + value: + errors: + rating: Rating isn't an option + schema: + type: object + properties: + 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: + 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 @@ -25525,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 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 @@ -36165,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 + - 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 @@ -36327,6 +36477,97 @@ 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. + 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: + 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 +41004,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 +41019,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..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. + 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. + 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 @@ -2158,6 +2158,160 @@ 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, 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. + {% /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 + Invalid rating: + value: + errors: + rating: Rating isn't an option + schema: + type: object + properties: + 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: + 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 +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 + - 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 @@ -20140,6 +20294,97 @@ 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. + 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: + 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 @@ -23291,7 +23536,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`.   @@ -23302,6 +23547,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..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. + 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. + 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 @@ -14934,6 +14934,160 @@ 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, 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. + {% /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 + Invalid rating: + value: + errors: + rating: Rating isn't an option + schema: + type: object + properties: + 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: + 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 +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 + - 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 @@ -21052,6 +21206,97 @@ 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. + 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: + 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 @@ -24405,7 +24650,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`.   @@ -24416,6 +24661,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..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. + 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. + 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 @@ -4303,6 +4303,160 @@ 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, 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. + {% /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 + Invalid rating: + value: + errors: + rating: Rating isn't an option + schema: + type: object + properties: + 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: + 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 +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 + - 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 @@ -31488,6 +31642,97 @@ 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. + 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: + 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 @@ -35363,7 +35608,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`.   @@ -35374,6 +35619,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