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. Configure an escalation Operator Workflow to change this default. Escalation closes the original agent conversation if it is open.
  • user — escalate on behalf of a user with no prior agent conversation. Fin creates an agent conversation for the escalation and closes it once the handoff completes. On the Intercom Helpdesk, the teammate works in a separate new Helpdesk conversation. 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. The conversation is closed, as on the Intercom Helpdesk, and your platform hands the user off to a human.

You are notified via webhooks with an escalated status followed by complete. The complete status signals that Fin is done. By then the original agent conversation has been closed. An escalation Operator Workflow may act on it afterwards, but it is closed again once the workflow's first steps have run, so only steps that run later (for example after a wait) can reopen it. On the Intercom Helpdesk, the new human conversation remains open.

To request access to the Fin Agent API, go to Settings > Integrations > Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent > Deploy.

Security
bearerAuth
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

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. When you escalate an existing conversation by conversation_id, this echoes the ID you sent. When you escalate a user, Fin creates an agent conversation for the escalation and generates this ID for it.

Example:"ext-123"
intercom_conversation_idstring

The internal Intercom ID of the agent conversation created for the escalation. Returned only when escalating on behalf of a user. Fin closes this conversation once the handoff completes; the teammate works in a separate Helpdesk conversation.

Example:"987654321"
statusstring

The resulting status of the conversation.

Value:"escalated"
Example:"escalated"
Response
{
  "conversation_id": "ext-123",
  "status": "escalated"
}