Conversas e tickets pela API

Rotas

Passo a passo: abrir um ticket

1. Tenha o id do contato. Se só tem o telefone, use POST /v1/tickets.
2. Chame a rota. Todos os campos são opcionais:

curl -s -X POST https://http.pipebr.app/v1/contacts/b3a1c9de-0000-4000-8000-000000000010/tickets \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"queueId": "b3a1c9de-0000-4000-8000-000000000001", "reason": "Cliente pediu atendimento humano"}'

1. A resposta é 201 quando o ticket nasce:

{
  "conversationId": "b3a1c9de-0000-4000-8000-000000000100",
  "created": true,
  "state": "Waiting",
  "queueId": "b3a1c9de-0000-4000-8000-000000000001",
  "agentId": null,
  "adoptedBotExecutionId": "b3a1c9de-0000-4000-8000-000000000600"
}

Se o contato já tinha ticket ativo, a resposta é 200 com { "conversationId": "...", "created": false, "state": "Open" }, e nada é duplicado.

Se o contato estava só no bot, o ticket adota a sessão do bot: o histórico do bot entra no ticket e o bot fica em silêncio. O ticket aparece no Desk na fila escolhida.

Listar e filtrar tickets

GET /v1/conversations aceita:

Cada ticket traz state, emStandby, sequentialId, priority, datas, queue, agent e contact.

Transferir, encerrar e esperar

Transferir envia o ticket para uma fila (forQueueId) ou um atendente (forAgentId, com forAgentQueueId opcional para a fila onde o novo ticket nasce). O ticket atual é encerrado como Transferred e um novo nasce no destino:

curl -s -X POST https://http.pipebr.app/v1/conversations/b3a1c9de-0000-4000-8000-000000000100/transfer \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"forQueueId": "b3a1c9de-0000-4000-8000-000000000002", "reason": "Assunto financeiro"}'

{
  "ofConversationId": "b3a1c9de-0000-4000-8000-000000000100",
  "forConversationId": "b3a1c9de-0000-4000-8000-000000000101",
  "state": "Waiting"
}

Encerrar aceita closedBy: atendente (padrão) ou cliente, para quando o cliente desistiu em outro canal. Se houver etiquetas obrigatórias no encerramento, envie etiqueta_ids (ou etiqueta_id). A resposta traz state e reasonClosure.

Espera alterna o ticket entre em atendimento e em espera, e responde state, emStandby e pausado_seg.

Chamar transfer, close ou wait com o id de um contato (que não tem ticket) dá 404 no_active_ticket e aponta para a rota de abrir ticket.

Filas, horário e quem está online

curl -s "https://http.pipebr.app/v1/attendance-hours/status?queueId=b3a1c9de-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $PIPE_CHAVE"

{
  "queueId": "b3a1c9de-0000-4000-8000-000000000001",
  "at": "2026-10-12T14:30:00.000Z",
  "open": true,
  "agentsOnline": 2,
  "available": true
}

open segue a mesma regra de distribuição do Pipe (horário da fila, depois o regular da conta, com exceções). available exige também alguém online. Use at (ISO) para perguntar sobre outro momento. Veja como cadastrar horários em Horários e SLA.

GET /v1/queues/:id/online devolve agentsOnline e a lista agents, com id, nome, desde e conversationsActive.

POST /v1/agents/status aceita state (Online, Pause, Invisible ou Offline), userId e, para pausa, motivo_pausa_id.