From 77404a1398908d2dd727a420c432879c7d7ea7e2 Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Tue, 28 Jul 2026 16:41:15 +0100 Subject: [PATCH 1/5] Clarify /fin/ask escalation wording Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 242f691..c681b7f 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -24741,7 +24741,7 @@ paths: Ask Fin a single, self-contained question and receive one informational answer. Unlike a conversation, `/fin/ask` is non-conversational: Fin will not ask follow-up - questions, will not run procedures, and will not escalate to a human. + questions, will not run procedures, and will not escalate to a human on its own. Fin's answer is delivered asynchronously via the `fin_replied` event. The conversation ends with a `complete` status — there is no `awaiting_user_reply` cycle. From 8e90052f759785a52bb955abba457999c650f6bb Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Wed, 29 Jul 2026 15:09:55 +0100 Subject: [PATCH 2/5] Note that an /fin/ask conversation can be escalated Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index c681b7f..5c398cd 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -24741,7 +24741,9 @@ paths: Ask Fin a single, self-contained question and receive one informational answer. Unlike a conversation, `/fin/ask` is non-conversational: Fin will not ask follow-up - questions, will not run procedures, and will not escalate to a human on its own. + questions, will not run procedures, and will not escalate to a human on its own. You + can still hand an ask conversation to a human with `POST /fin/escalate`; the ask + conversation stays closed and the handoff is routed separately. Fin's answer is delivered asynchronously via the `fin_replied` event. The conversation ends with a `complete` status — there is no `awaiting_user_reply` cycle. From 3fcd12491ebbd39bd3bea598b77205be1808bbe9 Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Wed, 29 Jul 2026 15:55:52 +0100 Subject: [PATCH 3/5] Publish POST /fin/escalate in the Preview spec Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 156 +++++++++++++++++++++++++++- 1 file changed, 155 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 5c398cd..3558a80 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -25282,6 +25282,160 @@ 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, including one started + with `/fin/ask`. On the Intercom Helpdesk, Fin by default 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. On the Intercom + Helpdesk, 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. + + Escalating an existing conversation also sets its AI Agent resolution state to + `escalated`, readable as `ai_agent.resolution_state` on the Conversations API. This is a + resolution state, not a billable resolution. + + On Fin for Platforms there is no Intercom inbox, so an escalation that no workflow + handles — whether by `conversation_id` or `user` — does not open a Helpdesk + conversation for a teammate. You are notified with the `escalated` status and hand the + conversation to a human on your own platform. Escalating by `user` still creates the + Fin conversation, returned as `intercom_conversation_id`. + + 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 @@ -40608,7 +40762,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`, 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). + 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).   From 880802d5cca421e47ac76136050e5b69528a3c2c Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Wed, 29 Jul 2026 17:17:26 +0100 Subject: [PATCH 4/5] Scope escalation inbox wording, soften /fin/ask claim, add escalate capability kind Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 3558a80..7891c50 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -24658,7 +24658,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 @@ -24741,9 +24741,10 @@ paths: Ask Fin a single, self-contained question and receive one informational answer. Unlike a conversation, `/fin/ask` is non-conversational: Fin will not ask follow-up - questions, will not run procedures, and will not escalate to a human on its own. You - can still hand an ask conversation to a human with `POST /fin/escalate`; the ask - conversation stays closed and the handoff is routed separately. + questions and will not run procedures, and escalation is disabled, so Fin does not hand + the conversation to a human as part of answering. You can still escalate one yourself + with `POST /fin/escalate`; the ask conversation stays closed and the handoff is routed + separately. Fin's answer is delivered asynchronously via the `fin_replied` event. The conversation ends with a `complete` status — there is no `awaiting_user_reply` cycle. @@ -25323,7 +25324,8 @@ paths: 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. + the conversation. On the Intercom Helpdesk it remains open in the human inbox; on Fin for + Platforms it remains open for whoever handles it on your own platform. responses: '200': description: Conversation escalated successfully From 02ce916076c8aed8cb4fc5c0b8fa597244672afc Mon Sep 17 00:00:00 2001 From: Rahul D'Souza Date: Wed, 29 Jul 2026 17:24:04 +0100 Subject: [PATCH 5/5] Phrase /fin/ask escalation as behaviour, not a disabled setting Co-Authored-By: Claude --- descriptions/0/api.intercom.io.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 7891c50..8e4a4f6 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -24741,10 +24741,9 @@ paths: Ask Fin a single, self-contained question and receive one informational answer. Unlike a conversation, `/fin/ask` is non-conversational: Fin will not ask follow-up - questions and will not run procedures, and escalation is disabled, so Fin does not hand - the conversation to a human as part of answering. You can still escalate one yourself - with `POST /fin/escalate`; the ask conversation stays closed and the handoff is routed - separately. + questions, will not run procedures, and will not escalate to a human on its own. You can + still escalate one yourself with `POST /fin/escalate`; the ask conversation stays closed + and the handoff is routed separately. Fin's answer is delivered asynchronously via the `fin_replied` event. The conversation ends with a `complete` status — there is no `awaiting_user_reply` cycle.