> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hand Off Conversation to a Human

> Pause the agent on a conversation so a human can take over the thread.

<Info>
  **Enterprise Feature** - SMS is only available on Enterprise plans.
</Info>

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](/tutorials/post-call-webhooks#sms-webhooks) 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](/api-v1/post/sms-conversations-messages).
* A `status: "human_handoff"` webhook fires once at the transition.

Call [Resume Conversation](/api-v1/post/sms-conversations-resume) 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

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

### Path Parameters

<ParamField path="conversation_id" type="string" required>
  The conversation to hand off.
</ParamField>

### Body Parameters

<ParamField body="reason" type="string" required={false}>
  Why the thread was handed off. Returned as `reason` on the `human_handoff` status webhook and shown in the dashboard.
</ParamField>

<ParamField body="metadata" type="object" required={false}>
  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.
</ParamField>

<ParamField body="actor" type="string" required={false}>
  Who took the thread, for the audit trail (an email, a rep id).
</ParamField>

<ParamField body="webhook" type="string" required={false}>
  Replace the conversation's webhook URL at handoff time, for example to route relayed messages to your live-agent service.
</ParamField>

<ParamField body="notify_number" type="string" required={false}>
  E.164 number to text a heads-up to, from the agent number, with the conversation ID and reason.
</ParamField>

### Response

<ResponseField name="data.already_active" type="boolean">
  `true` when the conversation was already handed off. The call is idempotent.
</ResponseField>

<ResponseField name="data.conversation" type="object">
  `id`, `is_active`, `current_node_id`, `human_handoff_at`, `human_handoff_reason`, `human_handoff_metadata`, `updated_at`.
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "message": "Conversation handed off to a human",
      "already_active": false,
      "conversation": {
        "id": "8f1c2a4e-1b7d-4f2a-9c1e-2d3f4a5b6c7d",
        "is_active": true,
        "current_node_id": "transfer-to-human",
        "human_handoff_at": "2026-09-02T18:04:11.000Z",
        "human_handoff_reason": "Final rate negotiation",
        "human_handoff_metadata": { "source": "api", "actor": "broker@example.com", "load_id": "L-77" },
        "updated_at": "2026-09-02T18:04:11.000Z"
      }
    },
    "errors": null
  }
  ```
</ResponseExample>