Escalate an agent conversation to a human
Hand an in-progress agent conversation to a live human operator by marking it as escalated. This is what the agent’s transfer-to-human tool and the operator “Escalate” action call: it flips the conversation status, records the reason and category, attaches the AI transcript for whoever picks it up, fires the agent.handoff.requested and agent.conversation.ended webhooks, and — when the agent is configured for email delivery — forwards the transcript to the configured address. A conversation already in a terminal state returns 409. Requires an owner, admin, or developer role.
Authorizations
Dashboard JWT token from Clerk
Path Parameters
Agent conversation identifier.
Body
Free-text reason shown to the operator who receives the handoff.
1000Machine-readable handoff category for analytics. Inferred from the reason when omitted.
cant_understand, policy_block, customer_request, tool_failed, escalation_threshold, manual