Publish POST /fin/escalate in the Preview spec and clarify /fin/ask escalation wording (#608)

Author: rahulgdsouza

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,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.
+        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.
@@ -25280,6 +25282,161 @@ 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. 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
+          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
@@ -40606,7 +40763,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).