Ciclo de Vida das Mensagens

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:

Status	Descrição	Quando acontece
`pending`	Mensagem imediata sendo processada	Ao enviar sem `send_at`
`scheduled`	Agendada, aguardando o horário de envio	Ao enviar com `send_at`
`sent`	Enviada com sucesso ao WhatsApp	Envio confirmado pela instância
`failed`	Falha no envio	Após 3 tentativas sem sucesso
`canceled`	Cancelada pelo usuário	Ao 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.

Campo	Preenchido quando	Observação
`created_at`	A mensagem é criada	Sempre preenchido
`send_at`	Definido pelo usuário	Só existe em mensagens agendadas
`sent_at`	Mensagem enviada com sucesso	Preenchido quando o WhatsApp aceita o envio
`delivered_at`	Entrega confirmada no aparelho	Quando a mensagem chega no celular do destinatário
`read_at`	Destinatário leu a mensagem	Quando o destinatário abre a conversa
`canceled_at`	Mensagem cancelada	Quando 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.

Introdução

Conceitos

Webhooks

Integrações

Guias

Número 555 da Meta

Ciclo de Vida das Mensagens

Status de uma mensagem

Timestamps

Sobre entrega e leitura

Quando uma mensagem falha

​Status de uma mensagem

​Timestamps

​Sobre entrega e leitura

​Quando uma mensagem falha

Status de uma mensagem

Timestamps

Sobre entrega e leitura

Quando uma mensagem falha