Intercom API (unofficial showcase)
POST/fin/escalate

Escalate a Fin conversation to a human

Escalates an existing Fin conversation or a user without a prior agent conversation to a human teammate. Provide either conversation_id or user; the conversation remains open after Fin signals that the handoff is complete.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 3 body fields
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted; use a supported version.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Escalation details. Provide either conversation_id or user, but not both.

conversation_idstringrequired
The external ID of the conversation to escalate. Provide this or `user`. Required on Fin for Platforms, where `user` is not supported.
userobjectoptional
The user to escalate on behalf of, creating a new conversation. Not supported on Fin for Platforms.
contextstringoptional
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.

3 status codes
200Returns the escalated status and conversation identifiers when available. A new conversation created for a user escalation includes its internal Intercom conversation ID; an existing conversation escalation echoes its external ID.
conversation_idstringoptional
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.
intercom_conversation_idstringoptional
The internal Intercom conversation ID. Returned when a new conversation was created for the escalation.
sse_subscription_urlstringoptional
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.
statusstringoptional
The resulting status of the conversation.
Allowed:escalated
400Returned when the request is invalid, including when neither or both of `conversation_id` and `user` are provided, or when `user` is used on Fin for Platforms.

One documented failure

  • parameter_invalid

    Either conversation_id or user must be provided

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 400 is returned when the request does not provide exactly one of conversation_id or user, or when the request is invalid; on Fin for Platforms, provide conversation_id because user is not supported. A 401 is returned when the request is unauthorized. If supplied, context must not exceed 10,000 characters.