Skip to content

Add POST /fin/csat and the csat_requested event #612

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rahulgdsouza merged 5 commits into from
Jul 31, 2026
+999 −19
Merged

Add POST /fin/csat and the csat_requested event #612

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9fd16d7
Add POST /fin/csat and the csat_requested event
rahulgdsouza Jul 31, 2026
e59aa8f
Qualify the no-op condition and mention /fin/csat in the tag description
rahulgdsouza Jul 31, 2026
bba9601
Soften the CSAT-follows-complete claim and add missing examples
rahulgdsouza Jul 31, 2026
ce6d5d5
Align SSE token-revocation wording with CSAT and add an invalid-ratin…
rahulgdsouza Jul 31, 2026
bf43c18
Qualify CSAT deferral of SSE token revocation
rahulgdsouza Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
256 changes: 249 additions & 7 deletions descriptions/0/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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).

 

Expand All @@ -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
Expand Down
Loading