> ## 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.

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

Call [Resume Conversation](https://docs.bland.ai/api-v1/post/sms-conversations-resume.md) 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

**authorization** `string` *required*

Your API key for authentication.

### Path Parameters

**conversation\_id** `string` *required*

The conversation to hand off.

### Body Parameters

**reason** `string`

Why the thread was handed off. Returned as `reason` on the `human_handoff` status webhook and shown in the dashboard.

**metadata** `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.

**actor** `string`

Who took the thread, for the audit trail (an email, a rep id).

**webhook** `string`

Replace the conversation's webhook URL at handoff time, for example to route relayed messages to your live-agent service.

**notify\_number** `string`

E.164 number to text a heads-up to, from the agent number, with the conversation ID and reason.

### Response

**data.already\_active** `boolean`

`true` when the conversation was already handed off. The call is idempotent.

**data.conversation** `object`

`id`, `is_active`, `current_node_id`, `human_handoff_at`, `human_handoff_reason`, `human_handoff_metadata`, `updated_at`.

```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
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.