Take the conversation over (stops the AI agent)

POST

/leads/{id}/handoff

curl --request POST \
  --url https://app.whatsetter.com/api/v1/leads/example/handoff \
  --header 'Authorization: Bearer <token>'

• Production

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. Requires scope leads:write.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

The WhatSetter lead id — the id from GET /leads, and the contact.id you receive on webhooks.

Responses

200

The agent is now stopped on this conversation

Media typeapplication/json

object

data

Who is driving a conversation after a handoff/resume call.

object

id

The lead id.

string

external_reference

Your own id, echoed so you can log the action against your record.

string | null

agent_active

false after /handoff, true after /resume.

boolean

manual_override

true when a human holds the conversation.

boolean

status

The lead’s business status — unchanged by these calls.

string | null

dashboard_synced

Whether the leads-list mirror was updated too. false means the agent is correctly stopped but the dashboard list may lag; the conversation view is always right.

boolean

updated_at

string format: date-time

Example^generated

{
  "data": {
    "id": "example",
    "external_reference": "example",
    "agent_active": true,
    "manual_override": true,
    "status": "example",
    "dashboard_synced": true,
    "updated_at": "2026-04-15T12:00:00Z"
  }
}

401

Missing, unknown or revoked API key

Media typeapplication/json

object

error

object

code

string

message

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

404

Resource not found in this workspace

Media typeapplication/json

object

error

object

code

string

message

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

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.

Media typeapplication/json

object

error

object

code

string

message

string

Example

{
  "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)

Media typeapplication/json

object

error

object

code

string

message

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

502

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

Media typeapplication/json

object

error

object

code

string

message

string

Example

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