# Escalate to a human

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.

Endpoint: POST /fin/escalate
Version: Preview
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)
    Intercom API version.By default, it's equal to the version set in the app package.
    Enum: "1.0", "1.1", "1.2", "1.3", "1.4", "2.0", "2.1", "2.2", "2.3", "2.4", "2.5", "2.6", "2.7", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13", "2.14", "2.15", "Preview"

## Request fields (application/json):

  - `conversation_id` (string)
    The external ID of the conversation to escalate. Provide this or user.
    Example: "ext-123"

  - `user` (object)
    A user object representing the user in a Fin Agent conversation.

  - `user.id` (string, required)
    The ID of the user. This value will be used to uniquely identify the user
during a conversation with Fin. Maps to the user_id field on the Intercom User object.
    Example: "123456"

  - `user.name` (string)
    The name of the user.
    Example: "John Doe"

  - `user.email` (string)
    The email of the user.
    Example: "john.doe@example.com"

  - `user.attributes` (object)
    A hash of attributes associated with the user.
Attributes can be used by Fin to target content and responses.
Limit to 10 attributes.
    Example: {"plan_type":"Pro","subscription_status":"active"}

  - `message` (string)
    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` (string)
    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."

## Response 200 fields (application/json):

  - `conversation_id` (string)
    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` (string)
    The internal Intercom conversation ID. Returned when a new conversation was created for the escalation.
    Example: "987654321"

  - `sse_subscription_url` (string)
    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` (string)
    The resulting status of the conversation.
    Enum: "escalated"

## Response 400 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: "error.list"

  - `request_id` (string,null)
    Example: "f93ecfa8-d08a-4325-8694-89aeb89c8f85"

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code
    Example: "unauthorized"

  - `errors.message` (string,null)
    Optional. Human readable description of the error.
    Example: "Access Token Invalid"

  - `errors.field` (string,null)
    Optional. Used to identify a particular field or query parameter that was in error.
    Example: "email"