Skip to main content
POST
Hand Off Conversation to a Human
Enterprise Feature - SMS is only available on Enterprise plans.
Hands a live messaging thread to a human. After this call:
  • The agent stops replying on this conversation. Inbound messages are still stored, and each one still fires the message webhook with sender: "USER", so your system sees every reply in real time.
  • The inactivity timeout is suspended.
  • Your human replies on the same thread, from the same number, with Send Message on Conversation.
  • A status: "human_handoff" webhook fires once at the transition.
Call Resume Conversation to hand the thread back to the agent. The conversation keeps its ID throughout, unlike setting is_active: false, which makes the next inbound message start a new conversation. You can also trigger a handoff from inside a pathway with the Transfer to Human node.

Headers

string
required
Your API key for authentication.

Path Parameters

string
required
The conversation to hand off.

Body Parameters

string
Why the thread was handed off. Returned as reason on the human_handoff status webhook and shown in the dashboard.
object
Free-form data about the handoff (rep id, ticket, lane, and so on). Merged into metadata.human_handoff on every webhook for this conversation while the handoff is active.
string
Who took the thread, for the audit trail (an email, a rep id).
string
Replace the conversation’s webhook URL at handoff time, for example to route relayed messages to your live-agent service.
string
E.164 number to text a heads-up to, from the agent number, with the conversation ID and reason.

Response

boolean
true when the conversation was already handed off. The call is idempotent.
object
id, is_active, current_node_id, human_handoff_at, human_handoff_reason, human_handoff_metadata, updated_at.