Skip to content

Remove /fin/escalate from Fin Agent API Preview spec #547

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
ailishmccarthy merged 1 commit into from
Jun 10, 2026
Merged

Remove /fin/escalate from Fin Agent API Preview spec #547

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
145 changes: 2 additions & 143 deletions descriptions/0/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21588,7 +21588,7 @@ paths:
properties:
type:
type: string
description: The kind of capability — `procedure` for a runnable procedure, or a static action such as `reply`, `ask`, or `escalate`.
description: The kind of capability — `procedure` for a runnable procedure, or a static action such as `reply` or `ask`.
example: procedure
id:
type: string
Expand Down Expand Up @@ -22210,147 +22210,6 @@ 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
conversation is routed to your team inbox.

Provide either `conversation_id` or `user`. This choice changes what the teammate sees:

- `conversation_id` — the existing conversation is reassigned to the human inbox. The
teammate sees the full conversation, including Fin's exchange with the user.
- `user` — a new, separate conversation is created for the teammate. Use this when you
want the human to start from a clean conversation rather than the agent's working
history. 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).

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`. 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.
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 @@ -36356,7 +36215,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 hand off 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`, and continue a conversation with `/fin/reply`. Fin notifies your application of its status and responses through a set of events, delivered via webhooks or Server-Sent Events (SSE).

 

Expand Down