Pular para o conteúdo principal

​
Status de uma mensagem

Cada mensagem enviada pela Zapster passa por um ciclo de vida com status bem definidos. A tabela abaixo mostra todos os status possíveis:
StatusDescriçãoQuando acontece
pendingMensagem imediata sendo processadaAo enviar sem send_at
scheduledAgendada, aguardando o horário de envioAo enviar com send_at
sentEnviada com sucesso ao WhatsAppEnvio confirmado pela instância
failedFalha no envioApós 3 tentativas sem sucesso
canceledCancelada pelo usuárioAo chamar DELETE /v1/wa/messages/:id
Quando uma mensagem chega em sent, failed ou canceled, o status é final. Não muda mais.

​
Timestamps

Além do status, cada mensagem carrega timestamps que indicam o que aconteceu e quando. Nem todos são preenchidos em todas as mensagens — depende do tipo de envio e do que aconteceu depois.
CampoPreenchido quandoObservação
created_atA mensagem é criadaSempre preenchido
send_atDefinido pelo usuárioSó existe em mensagens agendadas
sent_atMensagem enviada com sucessoPreenchido quando o WhatsApp aceita o envio
delivered_atEntrega confirmada no aparelhoQuando a mensagem chega no celular do destinatário
read_atDestinatário leu a mensagemQuando o destinatário abre a conversa
canceled_atMensagem canceladaQuando o usuário chama DELETE antes do envio

​
Sobre entrega e leitura

Os campos delivered_at e read_at dependem de fatores que estão fora do controle da Zapster:
  • Se o destinatário desativou a confirmação de leitura nas configurações do WhatsApp, read_at nunca vai ser preenchido
  • Se o celular do destinatário está sem internet, delivered_at pode demorar até ele ficar online de novo
  • Esses campos não alteram o status da mensagem. Uma vez que o status é sent, ele permanece sent. Entrega e leitura são informações extras, registradas apenas nos timestamps
Na prática, você pode usar delivered_at e read_at para montar relatórios de entrega e leitura, mas não conte com eles para fluxos críticos. Nem todo destinatário vai gerar esses eventos.

​
Quando uma mensagem falha

Se o status de uma mensagem é failed, o campo errors traz uma lista com os detalhes do que deu errado. A estrutura do erro varia um pouco dependendo do tipo de instância. Para instâncias oficiais (WABA), o errors inclui o código de erro da Meta e um link direto para a documentação deles: 
{
  "errors": [
    {
      "code": 131047,
      "title": "Re-engagement message",
      "details": "Mais de 24 horas se passaram desde a última resposta do destinatário.",
      "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
    }
  ]
}
Alguns erros comuns em instâncias WABA:
  • 131047: Janela de 24 horas expirada. O destinatário não respondeu nas últimas 24h e você tentou enviar uma mensagem que não é template.
  • 132000: Template não encontrado. Verifique se o nome e o idioma do template estão corretos.
  • 131026: Número não está no WhatsApp ou é inválido.
Para instâncias não oficiais (QR code), os erros mais comuns são:
  • Instância offline (o celular perdeu conexão ou a sessão expirou)
  • Número bloqueado ou inexistente no WhatsApp
  • Limite de envio atingido pelo WhatsApp
Em todos os casos, o campo errors traz informações suficientes para você entender o que aconteceu e decidir se vale tentar novamente.