Conversas

A conversa é a unidade de atendimento: um contato, um canal, e tudo que foi dito entre os dois. É ela que a API endereça quando você envia uma mensagem — e é por isso que POST /v1/messages não pede canal.

O objeto

{
  "object": "conversation",
  "id": "conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "status": "open",
  "contact_id": "cnt_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "channel": {
    "id": "chn_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "type": "whatsapp",
    "provider": "meta"
  },
  "assigned_user_id": "usr_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "team_id": null,
  "external_id": "pedido-8291",
  "last_message_at": "2026-08-26T21:42:19.238Z",
  "closed_at": null,
  "metadata": {},
  "created_at": "2026-08-26T20:10:00.000Z",
  "updated_at": "2026-08-26T21:42:19.238Z"
}

channel é null quando a conversa não passa por canal externo — é o caso de um atendimento registrado à mão, como o log de uma ligação.

Os três estados

• open — aberta, sem ninguém trabalhando nela necessariamente.
• pending — em andamento; alguém está cuidando.
• closed — resolvida. closed_at diz quando.

São os mesmos três estados que a equipe vê no painel — a API não inventou uma segunda nomenclatura. Uma conversa encerrada volta para open sozinha quando o contato escreve de novo.

Ações têm rota própria

Encerrar é POST /v1/conversations/{id}/close, e não PATCH { "status": "closed" }. A diferença aparece no log e no webhook: a rota semântica diz o que aconteceu, e um PATCH genérico diria apenas que a linha mudou.

curl -X POST https://api.amivu.com.br/v1/conversations/conv_01K7.../assign \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "usr_01K7ZFA5X8Q2M4N6P8R0T2V4W6" }'

As rotas disponíveis: /close, /reopen, /assign e /unassign. Atribuir aceita user_id ou team_id — exatamente um dos dois.

Abrir sem duplicar

Passe external_id — o número do pedido, do chamado, do ticket. Se já houver conversa com aquele identificador, ela é devolvida em vez de uma segunda ser criada. Sem isso, um reprocessamento partiria o histórico do pedido em duas telas.

curl https://api.amivu.com.br/v1/conversations \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "cnt_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "channel_id": "chn_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "external_id": "pedido-8291"
  }'

Notas internas

Uma nota é uma entidade diferente de mensagem, e essa separação é a garantia que importa: nota não tem caminho de envio, não tem estado de entrega e não passa por canal nenhum. Não existe o acidente “a nota interna foi para o cliente” — não porque alguém lembrou de filtrar, mas porque não há código que a mande.

curl https://api.amivu.com.br/v1/conversations/conv_01K7.../notes \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Cliente pediu segunda via da nota fiscal." }'

Veja também Mensagens.