/conversations

Lê conversas, as mensagens de cada uma e os eventos de conversão detectados pelo agente.

Escopo necessário: conversations:read para ler, conversations:write para agir. Escrever exige plano com o recurso de API. Limite: 120 requisições por minuto.

Endpoints

Método	Rota	Devolve
GET	`/conversations`	Lista paginada
GET	`/conversations/{id}`	Uma conversa
GET	`/conversations/{id}/messages`	Mensagens da conversa, da mais nova para a mais antiga
GET	`/conversations/{id}/events`	Eventos de conversão detectados na conversa
GET	`/conversations/{id}/export`	Transcrição completa, em json ou markdown
POST	`/conversations/{id}/assign`	Define quem atende (também aceito como `/takeover`)
POST	`/conversations/{id}/release`	Devolve para a IA
POST	`/conversations/{id}/pause-ai`	Silencia a IA por N minutos
POST	`/conversations/{id}/resume-ai`	Volta a IA
POST	`/conversations/{id}/resolve`	Encerra
POST	`/conversations/{id}/reopen`	Reabre
POST	`/conversations/{id}/handoff`	Marca pedido de atendente humano
POST, DELETE	`/conversations/{id}/tags`	Aplica ou tira etiqueta
POST	`/conversations/{id}/messages`	Responde dentro da conversa

Filtros da lista

Parâmetro	Exemplo	Descrição
`status`	`open`	`open`, `resolved` ou `archived`
`channel`	`whatsapp`	`web`, `embed` ou `whatsapp`
`agent_id`	uuid	Conversas atendidas por um agente
`connection_id`	uuid	Conversas de um número de WhatsApp
`contact_id`	uuid	Conversas de um contato
`assigned_to`	uuid	Conversas que um atendente assumiu
`handoff`	`pending`	Só quem pediu atendente humano e ainda não foi atendido
`awaiting_reply`	`true`	Só quem está esperando resposta
`sentiment`	`negative`	`positive`, `neutral` ou `negative`
`tag`	`Urgente`	Etiqueta de conversa, por nome ou id
`phone`	`5511999998888`	Número do cliente

Mais limit, cursor e updated_since, descritos em paginação.

Conversas de teste do editor de agentes não aparecem aqui, do mesmo jeito que não aparecem no inbox nem nas métricas.

Exemplo: quem está esperando atendente

curl "https://api.wevi.chat/functions/v1/conversations?handoff=pending&limit=20" \
  -H "Authorization: Bearer wevi_SUA_CHAVE"

const res = await fetch(
  "https://api.wevi.chat/functions/v1/conversations?handoff=pending&limit=20",
  { headers: { Authorization: "Bearer wevi_SUA_CHAVE" } },
);
const { data } = await res.json();

Objeto da conversa

{
  "id": "ffff0000-0000-4000-8000-0000000000f1",
  "status": "open",
  "channel": "whatsapp",
  "contact": { "id": "...", "name": "Felipe Barros", "phone": "5511987654321", "email": null },
  "agent": { "id": "...", "name": "Agente de vendas" },
  "connection_id": "...",
  "user": { "name": "Felipe Barros", "email": null, "phone": "5511987654321", "metadata": null },
  "tags": [],
  "awaiting_reply": false,
  "bot_paused_until": null,
  "takeover": null,
  "handoff": null,
  "resolved": null,
  "rating": null,
  "sentiment": null,
  "referral": {
    "source_id": "120210394857261",
    "source_type": "ad",
    "ctwa_clid": "AQAN...",
    "at": "2026-09-07T20:49:21Z",
    "raw": { "headline": "...", "body": "..." }
  },
  "created_at": "2026-09-07T20:49:21Z",
  "last_message_at": "2026-09-07T21:02:10Z",
  "last_inbound_at": "2026-09-07T21:01:40Z",
  "last_assistant_message_at": "2026-09-07T21:02:10Z"
}

Campos que vêm null quando não se aplicam: takeover (ninguém assumiu), handoff (não pediu humano), resolved (segue aberta), rating (não avaliou), sentiment (análise desligada ou ainda não rodou), referral (não veio de anúncio).

Mensagens

curl "https://api.wevi.chat/functions/v1/conversations/{id}/messages?limit=50" \
  -H "Authorization: Bearer wevi_SUA_CHAVE"

Cada mensagem traz role (user, assistant ou system), content, file quando tem anexo, wamid e o bloco delivery com o estado da entrega no WhatsApp. Veja /messages para o detalhe do objeto.

Eventos de conversão

curl "https://api.wevi.chat/functions/v1/conversations/{id}/events" \
  -H "Authorization: Bearer wevi_SUA_CHAVE"

Devolve os eventos que o agente marcou na conversa, com nome, metadados e horário. São os mesmos que aparecem nas métricas do painel.

Agir na conversa

Toda ação devolve a conversa atualizada, no mesmo formato do GET, então você não precisa de uma segunda chamada para ver como ficou.

Assumir e devolver

curl -X POST "https://api.wevi.chat/functions/v1/conversations/{id}/assign" \
  -H "Authorization: Bearer wevi_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"user_email":"joana@clinica.com"}'

Aceita user_id ou user_email de alguém da organização. /takeover faz o mesmo, com o nome que aparece no inbox.

curl -X POST "https://api.wevi.chat/functions/v1/conversations/{id}/release" \
  -H "Authorization: Bearer wevi_SUA_CHAVE"

Devolver limpa também o pedido de atendente: a fila não deve segurar uma conversa que voltou para a IA.

Pausar a IA

{ "minutes": 30 }

curl -X POST "https://api.wevi.chat/functions/v1/conversations/{id}/pause-ai" \
  -H "Authorization: Bearer wevi_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"minutes": 30}'

Sem minutes, o padrão é 60. Enquanto pausada, a IA não responde e as mensagens ficam esperando o humano. /resume-ai libera na hora.

Encerrar, reabrir e pedir atendente

curl -X POST "https://api.wevi.chat/functions/v1/conversations/{id}/resolve" \
  -H "Authorization: Bearer wevi_SUA_CHAVE"

curl -X POST "https://api.wevi.chat/functions/v1/conversations/{id}/reopen" \
  -H "Authorization: Bearer wevi_SUA_CHAVE"

curl -X POST "https://api.wevi.chat/functions/v1/conversations/{id}/handoff" \
  -H "Authorization: Bearer wevi_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"reason":"cliente pediu falar com o financeiro"}'

handoff coloca a conversa na fila de atendimento humano, com o motivo visível para quem vai atender. É o mesmo estado que o agente cria quando decide passar para uma pessoa, e dispara o webhook conversation.handoff_requested.

Etiquetas

curl -X POST "https://api.wevi.chat/functions/v1/conversations/{id}/tags" \
  -H "Authorization: Bearer wevi_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"tag":"Urgente"}'

Aceita nome ou id. Etiqueta que ainda não existe é criada, como acontece no inbox. Para tirar, o mesmo corpo com DELETE.

Responder na conversa

curl -X POST "https://api.wevi.chat/functions/v1/conversations/{id}/messages" \
  -H "Authorization: Bearer wevi_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"type":"text","text":"Confirmado para quinta às 15h."}'

Aceita os mesmos tipos de `POST /messages`, sem precisar informar destino: a conversa já diz para quem vai.

Exportar a transcrição

curl "https://api.wevi.chat/functions/v1/conversations/{id}/export?format=markdown" \
  -H "Authorization: Bearer wevi_SUA_CHAVE"

format=json (padrão) devolve a conversa e as mensagens em objeto. format=markdown devolve texto pronto para anexar num chamado, colar num documento ou mandar para o cliente.

/messages

→