Enviado, entregue, lido e falhou: como ler o status de cada mensagem na API do WhatsApp

Quais são os status de uma mensagem na API do WhatsApp?

Cada mensagem enviada pela Cloud API recebe um identificador e passa por estados que a Meta comunica por webhook. Os quatro que importam em campanha são estes, com a definição da documentação oficial:

Para mensagens de voz existe ainda o status played, que marca a primeira vez que o aparelho do contato reproduz o áudio. Em disparo de texto, imagem e vídeo, você trabalha com os quatro da tabela.

O que vem dentro de cada aviso de status?

O aviso de status é um pacote de dados enviado pela Meta ao endereço que você cadastrou (o webhook). Ele traz estes campos principais:

• id: o identificador da mensagem na Meta. É a chave para cruzar o status com a linha da sua planilha.
• status: sent, delivered, read ou failed.
• timestamp: o momento em que o aviso foi gerado, em horário Unix.
• recipient_id: o telefone do contato.
• errors: só aparece na falha. Traz código, título, mensagem, detalhe e um link para a documentação. Os códigos estão em erros da API do WhatsApp.
• pricing: aparece no status sent, junto de delivered ou read, com a categoria da mensagem (marketing, utilidade etc.).

Para entender como esse pacote chega ao seu CRM e vira atendimento, veja webhook do WhatsApp API e o que é webhook.

Como ler o resultado de uma campanha com esses status?

Resultado de disparo é uma sequência de funis. De cada mil mensagens enviadas, nem todas chegam, nem todas são lidas, e só parte responde. Cada etapa mede uma coisa diferente:

Exemplo (números fictícios): numa campanha de 10.000 mensagens enviadas, 9.000 entregues e 2.700 lidas, a entrega é de 9.000 ÷ 10.000, ou 90 por cento, e a leitura é de 2.700 ÷ 9.000, ou 30 por cento. Esses valores são só para mostrar a conta, não uma referência de mercado. Compare sempre uma campanha com a anterior da mesma base. O guia métricas de campanha de WhatsApp aprofunda cada indicador. Para calcular a proporção de entregues e agir quando ela cai, veja taxa de entrega do disparo.

Leia "lido" como sinal de engajamento, não como contagem exata de quem viu. A definição oficial é mensagem exibida em conversa aberta, e isso não cobre todas as formas de uma pessoa ter visto o conteúdo.

Por que algumas mensagens ficam em sent e não viram delivered?

É a dúvida mais comum de quem lê o primeiro relatório. A mensagem saiu, mas o aparelho não confirmou o recebimento. As causas que a documentação da Meta nomeia, em geral, aparecem como falha, e não como um sent parado. Entre as mais frequentes:

• Número sem WhatsApp, termos não aceitos ou aplicativo desatualizado: a Meta agrupa essas causas no erro 131026.
• Limite de marketing por pessoa: quando o contato já recebeu mensagens de marketing demais, o envio volta com o erro 131049. Veja mensagem de marketing não entregue.
• Contato que pediu para não receber marketing da empresa: o erro é o 131050.
• Template pausado por qualidade: o envio é recusado enquanto o template está pausado. Entenda em qualidade do número no WhatsApp API.

Se a diferença entre enviados e entregues for grande, o primeiro lugar para olhar é a base. Validar e higienizar antes do envio reduz esse buraco. Veja limpeza de base para disparo.

E a cobrança: ela acompanha o status?

Sim, no sentido de que a Meta cobra por mensagem entregue, por categoria (marketing, utilidade e autenticação) e pelo país do contato. Mensagem que o cliente manda para a empresa não é cobrada. Esse é o motivo de a taxa de entrega mexer tanto no custo real por contato alcançado.

O modelo da AD PRO segue a mesma lógica: o saldo é pré-pago em quantidade de disparos, e o débito acontece conforme as mensagens entregues, comprovado no relatório. A tabela com o valor médio por faixa de volume está em quanto custa disparo em massa.

Como organizar o resultado em uma planilha simples?

Aba 1: Envios (uma linha por contato)
nome | telefone | variavel_1 | variavel_2 | id_da_mensagem | status | horario_do_status | codigo_do_erro | observacao

Aba 2: Resumo da campanha
Campanha: ____________  Template: ____________  Data do envio: ___/___/_____
Total de contatos na base: ______
Enviados (sent): ______
Entregues (delivered + read): ______
Lidos (read): ______
Falhas (failed): ______

Fórmulas (Google Planilhas ou Excel):
Taxa de entrega = entregues / enviados
Taxa de leitura = lidos / entregues
Falhas por código = contar linhas por codigo_do_erro

Aba 3: Falhas por código
codigo | titulo | quantidade | causa provável | ação feita | reenviar após (horas)

Regra de ouro: nunca reenviar a lista inteira. Reenviar só quem falhou, depois de corrigir a causa e de esperar o prazo do código.