# Take the conversation over (stops the AI agent)

`POST https://app.whatsetter.com/api/v1/leads/{id}/handoff`

Hands the conversation to a human: the AI agent stops replying to this
lead immediately, and stays silent until you call `/resume`.

This is the exact same mechanism as the dashboard's "prendre la main"
toggle — same workflow, same flags — so the two never disagree. The
conversation appears as *Manual Control* in the dashboard and the agent
is gated before it can compose a reply.

The lead's business status is **preserved**: handing over does not mark
the lead as stopped, qualified, or anything else. Only who is driving
changes.

Idempotent: calling it on a lead already handed over is a no-op that
answers `200`.

On an Instagram or Messenger lead, the flags their engines read are
written on the lead itself, as the dashboard's « Prendre la main »
does (no workflow involved). Requires scope `leads:write`.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | The WhatSetter lead id — the `id` from `GET /leads`, and the `contact.id` you receive on webhooks. |

## Example request

```bash
curl --request POST \
  --url 'https://app.whatsetter.com/api/v1/leads/{id}/handoff' \
  --header 'Authorization: Bearer ws_live_…'
```

## Responses

### 200: The agent is now stopped on this conversation

```json
{
  "data": {
    "id": "",
    "external_reference": "",
    "agent_active": false,
    "manual_override": false,
    "status": "",
    "dashboard_synced": false,
    "updated_at": ""
  }
}
```

### 401: Missing, unknown or revoked API key

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 404: Resource not found in this workspace

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 409: `invalid_state`: the lead has no conversation to hand over — it has not been contacted yet (queued or pending), or the workflow found no conversation row for it.

```json
{
  "error": {
    "code": "invalid_state",
    "message": "Handoff applies to leads the agent has already engaged. This one is \"queued\" — it has not been contacted yet."
  }
}
```

### 500: Agent control is not configured on this deployment (`internal_error`)

```json
{
  "error": {
    "code": "",
    "message": ""
  }
}
```

### 502: `upstream_error`: the agent-control workflow was unreachable or refused the change. Safe to retry.

```json
{
  "error": {
    "code": "upstream_error",
    "message": "The agent-control workflow is unreachable. Try again in a moment."
  }
}
```


Source: https://docs.whatsetter.com/api-reference/operations/handofflead/
