---
title: "Hand a chat to a human"
method: POST
path: "/api/v1/ai-agents/{id}/chat/handoff"
tags: ["ai_agents"]
---

# Hand a chat to a human

`POST /api/v1/ai-agents/{id}/chat/handoff`

## Request

- Base URL: `https://app.blueticked.com`
- URL: `https://app.blueticked.com/api/v1/ai-agents/{id}/chat/handoff`
- Auth: HTTP bearer

The chat visitor leaves their details and becomes a lead, with the transcript attached.

This is the ONE place in the agent channel where anything personal is stored, and only because the visitor asked: `consent` must be literally true (a ticked checkbox), and at least one of `phone` / `email` must be present. Otherwise 400 and nothing is written.

The result is a LEAD in the Leads pipeline (source `agent_chat`) with the transcript on its answer card, linked to a deduped contact. The visitor's ticked box is consent to being contacted about this enquiry, kept on the lead; it never subscribes them to marketing. The team follows up on real channels, so there is no new inbox to watch.

No model runs and nothing is metered here: it would be absurd to charge for receiving a lead.

A PAUSED agent still hands off (a visitor mid-conversation deserves a human, not a wall); only a draft agent answers 404.

The ready-made widget does all of this itself: the visitor types "agent" or clicks the handoff link, fills the inline form, done.

## Path parameters

- `id` string, required

## Request body

- object
  - `session_id` string, required
  - `name` string
  - `phone` string
  - `email` string
  - `message` string
  - `transcript` object[]
    - `role` 'customer' | 'agent', required
    - `body` string, required
  - `consent` true, required

## Response `200`

Success

- object
  - `ok` boolean, required
  - `lead_created` boolean, required
  - `reply` string, required

## Other responses

- `400`: Validation failed
- `401`: Unauthorized: missing or invalid API key
- `402`: Insufficient wallet balance
- `403`: Forbidden: scope, plan limit, or suspension
- `404`: Not found
- `409`: Conflict (idempotency-key reuse or resource in use)
- `413`: Request body above the endpoint's size limit
- `422`: Understood but refused: the request is well-formed, the action is not permitted for this resource
- `429`: Rate limited
- `500`: Internal error
- `502`: An upstream provider refused or failed the request
- `503`: Channel or send queue unavailable

---

[API](https://skmtc.dev/blueticked/apis/blueticked-api.md) · [All operations](https://skmtc.dev/blueticked/apis/blueticked-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blueticked/apis/blueticked-api/revisions/07132284f4ff?raw)