Skip to content

Add /fin/escalate endpoint to Preview spec #553

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

Open
mckenna wants to merge 3 commits into
base: main
Choose a base branch
from
+152 −3
Open

Add /fin/escalate endpoint to Preview spec #553

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9b48edb
Add /fin/escalate endpoint to Preview spec
mckenna Jun 17, 2026
cd118ca
Note escalate message field is shown to the end-user
mckenna Jun 18, 2026
e91f447
Warn against credentials/personal data in escalate context
mckenna Jun 18, 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
155 changes: 152 additions & 3 deletions descriptions/0/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22344,7 +22344,7 @@ paths:
properties:
type:
type: string
description: The kind of capability — `procedure` for a runnable procedure, or a static action such as `reply` or `ask`.
description: The kind of capability — `procedure` for a runnable procedure, or a static action such as `reply`, `ask`, or `escalate`.
example: procedure
id:
type: string
Expand Down Expand Up @@ -22966,6 +22966,149 @@ paths:
order_id: '98765'
settings:
email: true
"/fin/escalate":
post:
summary: Escalate to a human
parameters:
- name: Intercom-Version
in: header
schema:
"$ref": "#/components/schemas/intercom_version"
tags:
- Fin Agent
operationId: escalateFinConversation
description: |
Hand a conversation off to a human teammate. If you use the Intercom Helpdesk, the
handoff lands in your team inbox.

Provide either `conversation_id` or `user`:

- `conversation_id` — escalate an existing agent conversation. By default, Fin summarises
the conversation and opens a new Helpdesk conversation that carries the summary as an
internal note; the original agent conversation is not reassigned. Configure an escalation
Operator Workflow to change this default.
- `user` — escalate on behalf of a user with no prior agent conversation. A new Helpdesk
conversation is created for the teammate. Include an optional `message` for its first
message.

In both cases the optional `context` is attached as an internal note (supplied by your
orchestrating agent, not generated by Fin) alongside any summary.

You are notified over the existing webhook or SSE channel with an `escalated` status
followed by `complete`. The `complete` status signals that Fin is done; it does not close
the conversation, which remains open in the human inbox.
responses:
'200':
description: Conversation escalated successfully
content:
application/json:
examples:
Existing conversation:
value:
conversation_id: ext-123
status: escalated
sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
New conversation:
value:
intercom_conversation_id: '987654321'
status: escalated
schema:
type: object
properties:
conversation_id:
type: string
description: The external ID of the conversation. Returned when you escalate an existing conversation by `conversation_id` (echoed back). When you escalate a `user`, a new conversation is created and only `intercom_conversation_id` is returned.
example: ext-123
intercom_conversation_id:
type: string
description: The internal Intercom conversation ID. Returned when a new conversation was created for the escalation.
example: '987654321'
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.
example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
status:
type: string
enum:
- escalated
description: The resulting status of the conversation.
example: escalated
'400':
description: Bad Request
content:
application/json:
examples:
Neither identifier provided:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: parameter_invalid
message: Either conversation_id or user must be provided
Conversation not found:
value:
type: error.list
request_id: b68959ea-6328-4f70-83cb-e7913dba1542
errors:
- code: parameter_invalid
message: Conversation not found
schema:
"$ref": "#/components/schemas/error"
'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"
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
conversation_id:
type: string
description: The external ID of the conversation to escalate. Provide this or `user`.
example: ext-123
user:
"$ref": "#/components/schemas/fin_agent_user"
message:
type: string
maxLength: 10000
description: Optional first message for the new conversation, used only when escalating on behalf of a `user`. Shown to the end-user (unlike `context`, which is an internal note), so don't include sensitive orchestration data. Defaults to "Requesting human support".
example: I'd like to speak to a human about my refund.
context:
type: string
maxLength: 10000
description: Optional context for the receiving teammate explaining why the conversation is being escalated. Attached as an internal note, never shown to the user. Avoid including credentials or unnecessary personal data — the note is visible to any teammate with access to the conversation.
example: Customer is requesting a refund and is frustrated.
oneOf:
- required:
- conversation_id
- required:
- user
examples:
Escalate an existing conversation:
value:
conversation_id: ext-123
context: Customer is requesting a refund and is frustrated.
Escalate on behalf of a user:
value:
user:
id: '123456'
name: John Doe
email: john.doe@example.com
message: I need help with my billing issue
"/fin/start":
post:
summary: Start a conversation with Fin
Expand Down Expand Up @@ -32926,13 +33069,19 @@ components:
description: |
Optional. A human-readable explanation of why the conversation was escalated.
Only present when status is 'escalated'.
Possible values include:

When you escalate deterministically with `/fin/escalate`, the reason is always
"Escalation requested via API".

The following reasons are legacy — they apply to Fin-decided escalations in
conversational mode (`/fin/start`, and `/fin/reply` on a conversation that was
started conversationally):
- "Escalation requested by user"
- "Escalation rule: {rule_name}"
- "Escalation rule matched"
- "Routed to team"
- "Conversation finished without resolution"
example: Escalation requested by user
example: Escalation requested via API
created_at_ms:
type: string
format: date-time
Expand Down