Símbolo da AmivuSímbolo da AmivuDevelopers

Mensagens

O ciclo de vida de uma mensagem, do envio ao recibo — e o que é `null`.

Uma mensagem pertence a uma conversa e tem uma direção: inbound quando veio do contato, outbound quando saiu de você.

Enviar

Uma rota, todos os canais. A conversa determina por onde a mensagem sai — e as capacidades do canal são conferidas antes de qualquer coisa ser gravada.

Terminal
curl https://api.amivu.com.br/v1/messages \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8291-entrega" \
  -d '{
    "conversation_id": "conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "type": "text",
    "text": "Seu pedido saiu para entrega."
  }'

Imagem, vídeo, áudio e documento

Mídia são duas chamadas: suba o arquivo em POST /v1/uploads e envie o attachment_id que voltou, com o type do arquivo e, se quiser, uma legenda em text. O envio é o mesmo que o atendente faz pelo painel — mesma fila, mesmos recibos. Tipos aceitos, limite de tamanho e validade do anexo estão em Anexos e mídia.

Terminal
curl https://api.amivu.com.br/v1/messages \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-8291-catalogo" \
  -d '{
    "conversation_id": "conv_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "type": "document",
    "attachment_id": "att_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "text": "Segue o catálogo."
  }'
Modelo aprovado ainda não
type: "template" faz parte do schema, mas é recusado com 422 unsupported_message_type em qualquer canal. Não é falha passageira: retentar não adianta. Quando isso mudar, entra no changelog.
Nada é gravado quando o canal não aceita
Um canal sem suporte ao tipo — mídia no chat do site, por exemplo — recusa com 422 unsupported_message_type e a conversa fica intacta. Gravar primeiro e descobrir depois deixaria um balão na tela do atendente que o cliente nunca recebeu.

Para um grupo do WhatsApp

Um grupo é uma conversa como outra qualquer, só que o contato dela é o grupo: em GET /v1/conversations ela vem com is_group: true e um group_id (grp_…), e ?is_group=true traz só os grupos. Os grupos de um número também saem de GET /v1/channels/{channel_id}/groups, com o nome e quantas pessoas estão em cada um — ver Canais.

Para escrever no grupo, mande o conversation_id da conversa dele ou o group_id, nunca os dois. O group_id leva à conversa mais recente do grupo, e o resto é o envio de sempre: texto, ou mídia com legenda.

Terminal
curl https://api.amivu.com.br/v1/messages \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: torneio-aviso-20h" \
  -d '{
    "group_id": "grp_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "type": "text",
    "text": "Torneio hoje às 20h. Confirmem presença!",
    "mention_all": true
  }'
Só o WhatsApp pareado por QR Code
Grupo existe onde capabilities.groups é verdadeiro. No número oficial não há conversa de grupo, e listar os grupos dele volta 422 channel_without_groups.

Marcar pessoas no grupo

No WhatsApp a menção tem duas metades: o @ escrito no texto, que é só texto, e a lista de quem foi marcado, que vai junto e é o que faz o aparelho de cada um avisar. A API separa as duas:

  • "mention_all": true marca todos os participantes sem escrever nenhum @: o texto chega como você mandou, e todos recebem o aviso de menção. É o exemplo acima.
  • mentions marca as pessoas destes telefones, com DDI e no formato que você tiver (+55 11 99999-8888 serve). Para o nome aparecer destacado no texto, escreva @ e o mesmo número: a Amivu troca pela forma que o WhatsApp reconhece naquele grupo, que nem sempre é o telefone.
Terminal
curl https://api.amivu.com.br/v1/messages \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: torneio-vez-ana" \
  -d '{
    "group_id": "grp_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
    "type": "text",
    "text": "@5511999998888, sua vez de confirmar.",
    "mentions": ["+5511999998888"]
  }'

Os dois juntos valem, e ninguém é marcado duas vezes. Na mídia, a marcação vai com a legenda — por isso áudio, que não tem legenda, recusa. Quem confere é a lista de participantes que o canal leu do grupo, e qualquer recusa acontece antes de gravar a mensagem:

  • 422 mentions_not_allowed — a conversa não é de grupo, ou a mensagem é áudio.
  • 422 mention_not_in_group — um número de mentions não está no grupo, e param diz qual (mentions.1 é o segundo). Também é o caso de quem esconde o número no grupo: essa pessoa só é marcada por mention_all.
  • 409 group_participants_unavailable — o canal ainda não leu quem está no grupo. Ele lê quando o número conecta e quando o grupo recebe mensagem; tente de novo em instantes.

O ciclo de vida

queued ──▶ sent ──▶ delivered ──▶ read
   │         │
   └─────────┴──▶ failed
  • queued — aceita por nós. Ainda não entregue ao canal.
  • sent — o canal aceitou a mensagem.
  • delivered — o canal confirmou que chegou ao aparelho.
  • read — o contato leu.
  • failed — o canal recusou. O motivo vem em error.

A resposta de POST /v1/messages devolve queued, e isso é deliberado: o retorno síncrono do provedor confirma apenas o enfileiramento na ponta dele. A falha real chega depois, por webhook de status. Tratar o 201 como “entregue” é o erro de integração mais comum com qualquer API de mensageria.

Quando status é null

Duas situações, e as duas são informação:

  • Mensagem recebida — quem entregou foi o outro lado; não há estado nosso a reportar.
  • Canal sem recibo — a conversa não passa por um transporte que confirme entrega. É o caso do registro manual.

A Amivu não fabrica estado. Preencher delivered porque “provavelmente chegou” seria mentir num campo em que integrações tomam decisões — inclusive a de cobrar alguém.

Para saber o que um canal específico reporta, leia capabilities.delivery_receipts e capabilities.read_receipts em GET /v1/channels/{id}.

Quando falha

{
  "object": "message",
  "id": "msg_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "status": "failed",
  "error": {
    "code": "130497",
    "message": "Conta sem verificação de negócio para enviar a este destino."
  }
}

O code é o do provedor, repassado sem tradução. Ele pede ação humana com muito mais frequência do que uma retentativa resolveria — e é por isso que a Amivu não reenvia sozinha: um número bloqueado continua bloqueado na décima tentativa.

Receber

Não pergunte de tempos em tempos. Assine message.received e a Amivu faz um POST assinado no seu endpoint com a mensagem e a conversa dentro.

Mensagem com mídia traz o arquivo em attachment.url, baixável com a mesma chave — ver Anexos e mídia.

Se precisar mesmo ler o histórico — para montar uma tela, por exemplo — GET /v1/conversations/{id}/messages devolve da mais nova para a mais velha, com cursor.

Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.