Skip to content
Home/
REST API Reference
/
/
Escalate to a human

Escalate to a human

Request

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. Escalation does not change the original agent conversation's assignment or open/closed state. 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. Not supported on Fin for Platforms — see below.

In both cases, pass the optional context to give the receiving teammate background your orchestrating agent has and Fin does not. On the Intercom Helpdesk, it appears above the summary in the internal note of the new conversation the teammate picks up. It is never shown to the end user.

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, conversation_id is required — user is not supported and is rejected, because there is no Intercom Helpdesk in which to create a conversation. There is no Intercom inbox either, so an escalation that no workflow handles does not open a Helpdesk conversation for a teammate. context is not surfaced, and the conversation is left open for your platform to hand off and continue driving.

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, the new human conversation remains open; on Fin for Platforms, the conversation remains open for whoever handles it on your platform.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"Preview"
Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:Preview
Bodyapplication/jsonrequired
One of:
conversation_idstring

The external ID of the conversation to escalate. Provide this or user. Required on Fin for Platforms, where user is not supported.

Example:"ext-123"
userobject(Fin Agent User)

A user object representing the user in a Fin Agent conversation.

contextstring, <= 10000 characters

Optional background for the receiving teammate, valid with either conversation_id or user. On the Intercom Helpdesk, it appears above the summary in the internal note of the new conversation the teammate picks up, and is never shown to the end user. Not surfaced on Fin for Platforms. Avoid including credentials or unnecessary personal data — it is visible to any teammate with access to the conversation.

Example:"Customer is requesting a refund and is frustrated."
curl -i -X POST \
  https://api.intercom.io/fin/escalate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "conversation_id": "ext-123",
    "context": "Customer is requesting a refund and is frustrated."
  }'

Responses

Conversation escalated successfully

Bodyapplication/json
conversation_idstring

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_idstring

The internal Intercom conversation ID. Returned when a new conversation was created for the escalation.

Example:"987654321"
sse_subscription_urlstring

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. When CSAT is enabled and a survey will follow the resolution, complete revocation is deferred until the csat_requested event is delivered or the token expires. 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"
statusstring

The resulting status of the conversation.

Value:"escalated"
Example:"escalated"
Response
{
  "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"
}