/v1/conversations/{id}/handoff
Handoff do agente para a equipe (lead ou paciente; somente token de serviço)
Somente token de serviço com leads:handoff (exclusiva de agente: Lívia, knowledge). Transfere a conversa para a equipe qualquer que seja o contato (lead, paciente ou sem cadastro): active_agent_key null e sem responsável (fila da equipe, filtro agent=equipe). A próxima resposta do agente recebe 409 conversation_not_with_agent / conversation_taken_over.
Registro visível para a equipe (uma vez por handoff): mensagem de sistema na conversa ("Conversa transferida para a equipe por …", sem envio ao contato) e uma entrada handoff na timeline do paciente e/ou do lead vinculados. Nenhum webhook novo; o funil do lead não muda (para mover o lead use POST /v1/leads/{id}/stage com HUMAN_HANDOFF, que também libera a conversa).
Idempotência: cabeçalho Idempotency-Key obrigatório (ex.: handoff:<request_id>), escopo da clínica. Repetição da mesma chave → 200 com meta.idempotent = true, sem 2ª entrada (completa a liberação se o pedido original caiu no meio). Conversa já sem agente (handoff anterior ou assumida por alguém da equipe) → 200 com meta.released = false, nada é alterado. Mesma chave usada em outra conversa → 409 idempotency_key_reused.
Conversa conduzida por outro agente que não inclui o chamador em agentReplyKeys → 409 conversation_not_with_agent / conversation_other_agent. Agent Preview → 403 preview_no_handoff. Pessoa (token de usuário) → 403. Conversa de outra clínica → 404. reason opcional é um código (sem texto livre) gravado só no evento.
leads:handoffAutenticação
Envie o token de acesso do usuário no cabeçalho Authorization e, se ele tiver mais de uma clínica, o X-Clinic-Id. Integrações servidor a servidor usam o token de serviço com X-Clinic-Id e X-Agent-Key. Como autenticar
Authorization: Bearer <TOKEN>X-Clinic-Id: <clinic_id>Parâmetros
Parâmetros de caminho
idstringObrigatórioId do recurso. · Entre 1 e 64 caracteres · Padrão (regex):
^[A-Za-z0-9._-]+$
Cabeçalhos
X-Clinic-IdstringOpcionalClínica ativa. Obrigatório só para quem tem acesso a mais de uma clínica (ou token de serviço). Validado contra o vínculo do usuário. · Padrão (regex):
^[A-Za-z0-9._-]{1,64}$Idempotency-KeystringOpcionalObrigatória. Ex.:
handoff:<request_id>. · Entre 1 e 255 caracteres · Padrão (regex):^[\x21-\x7E]+$
Corpo da requisição
application/json · obrigatório
reasonstringOpcionalCódigo do motivo (ex.:
LIVIA_KNOWLEDGE_HOLD). Sem texto livre nem dado pessoal. · Padrão (regex):^[A-Za-z0-9_]{1,64}$
Exemplo de requisição
Gerado do contrato. Troque os marcadores entre < > pelos seus valores.
const res = await fetch("https://myclinc.leadpoint.com.br/v1/conversations/<id>/handoff", { method: "POST", headers: { Authorization: "Bearer <TOKEN>", "X-Clinic-Id": "<clinic_id>", "X-Agent-Key": "<agent_key>", "Content-Type": "application/json", }, body: JSON.stringify({ "reason": "<reason>" }),})if (!res.ok) { const { error } = await res.json() throw new Error(`${error.code}: ${error.message} (${error.requestId})`)}const { data } = await res.json()Resposta
{ "data": { "id": "<id>", "name": "<name>", "channel": "whatsapp", "preview": "<preview>", "lastMessageAt": "2026-09-18T14:00:00.000Z", "unread": 1, "mine": true, "assignedTo": { "id": "<id>", "name": "<name>" }, "archived": true, "activeAgent": { "key": "<key>", "name": "<name>", "image": "<image>" }, "agentReplyKeys": [ "<agentReplyKey>" ], "patientId": "<patientId>", "leadId": "<leadId>", "tags": [ "<tag>" ], "audience": "contact", "isPreview": true }, "meta": { "released": true, "idempotent": true }}Exemplo gerado do esquema da resposta; valores entre < > são ilustrativos.
Códigos de erro
Corpo no formato padrão { error: { code, message, requestId } }. Veja todos os códigos.
Bad Request — Requisição malformada (JSON inválido, cursor inválido ou clínica ativa não informada).
Unauthorized — Token ausente, inválido ou expirado.
Forbidden — Autenticado, mas sem permissão (perfil ou clínica).
Not Found — Recurso não encontrado na clínica ativa.
Conflict — Conflito de estado (duplicidade, transição inválida, conflito de agenda).
Unprocessable Entity — Dados semanticamente inválidos (erros por campo em details).
Too Many Requests — Limite de requisições excedido (veja Retry-After).
Internal Server Error — Erro interno (sem detalhes expostos).
Service Unavailable — Banco de dados indisponível ou não configurado.
Limites
Limite padrão: 120 requisições a cada 60 segundos por token. Sobre limites