API oficial

Status de entrega no WhatsApp: o que cada estado significa e o que ele não prova

Por VeyloCRM · · 14 min de leitura

Quem sai do aplicativo comum para a API oficial ganha uma informação que antes não existia: cada mensagem passa a ter um histórico de estados, devolvido pela própria Meta ao sistema da empresa. É a diferença entre olhar dois tiques na tela e ter um relatório do que aconteceu com trinta mil mensagens. O problema é que esses estados são lidos errado com frequência, e uma leitura errada leva a decisões caras — reenviar o que já chegou, trocar de número que estava saudável, culpar a base de contatos por um problema de janela. Este texto trata de ler o relatório certo.

O caminho de uma mensagem

No aplicativo comum, a única informação sobre uma mensagem são os tiques ao lado dela. Na API oficial, a mesma mensagem percorre um caminho com etapas separadas, e o sistema da empresa recebe um aviso a cada mudança.

O percurso é este: a empresa pede o envio; a Meta responde se aceitou o pedido e devolve um identificador; a mensagem sai para a rede do WhatsApp; o aparelho do destinatário a recebe; a pessoa abre a conversa. Cada uma dessas etapas pode falhar por um motivo diferente, e o valor da API está justamente em saber em qual delas parou.

A confusão mais comum começa aqui: a resposta imediata da Meta ao pedido de envio não é um status de entrega. Ela diz apenas que a solicitação foi aceita e entrou na fila. Tratar essa resposta como "mensagem enviada com sucesso" é o erro que produz relatórios de disparo com 100% de sucesso e nenhuma venda.

Os quatro estados e o que cada um diz

Um quinto evento aparece quando a mensagem tem botão ou lista: a resposta do destinatário chega como um evento próprio, identificando qual opção foi escolhida. Ele não é status, mas entra pelo mesmo caminho e costuma ser o dado mais valioso do conjunto.

Aceito não é entregue

Vale insistir nesse ponto porque ele contamina relatórios inteiros. Quando o sistema pede o envio, a Meta responde na hora com um identificador de mensagem. Essa resposta significa: recebi o pedido, ele é válido, vou processar.

Entre esse instante e a entrega existem várias razões para a mensagem morrer no caminho. O número pode não ter conta no WhatsApp. O aparelho pode estar desligado ou sem rede por dias. A pessoa pode ter bloqueado a empresa. O template pode ser pausado no meio do disparo. A cota do número pode se esgotar. Nenhuma dessas situações reverte a resposta que já foi dada.

É por isso que um painel de disparo honesto separa três colunas: solicitadas, entregues e falhas — e usa a segunda como denominador de qualquer taxa. Relatório que mostra "3.000 mensagens enviadas" sem dizer quantas chegaram não está medindo nada.

Leitura liberada

Continue lendo de graça

Preencha uma vez e libere este e todos os outros artigos do blog. Não cobramos nada — só queremos saber para quem estamos escrevendo.

Leva 20 segundos. Prefere falar direto no WhatsApp?

Por que o entregue demora

Uma dúvida recorrente: o disparo terminou, o painel mostra tudo processado, mas a coluna de entregues continua subindo horas depois. Isso não é atraso do sistema — é como a rede funciona.

A mensagem fica retida aguardando o aparelho do destinatário aparecer. Celular desligado, sem sinal, em modo avião ou com o aplicativo sem conexão faz a mensagem esperar. Quando o aparelho volta, a entrega acontece e o evento chega. Em uma base grande é normal que uma parcela das entregas ocorra várias horas depois, e uma fração menor no dia seguinte.

Duas consequências práticas. A primeira: não se avalia um disparo pela taxa de entrega da primeira hora. A leitura correta é feita depois de um período de acomodação, e comparar disparos exige comparar a mesma janela. A segunda: mensagem que não é entregue dentro do prazo de validade da rede é descartada, e o sistema recebe uma falha por expiração — que não significa número inválido, e sim aparelho ausente por tempo demais.

Existe ainda um caso que engana: quem tem o WhatsApp aberto no computador pode receber a mensagem no navegador antes de o celular sincronizar. A entrega é real, mas a leitura pode demorar a aparecer.

O que a ausência de lido não prova

O status de leitura é o mais requisitado pelos times comerciais e o menos confiável para tomar decisão. A confirmação de leitura é uma configuração do destinatário, e quem a desliga nunca gera o evento — mesmo tendo lido a mensagem inteira.

Ou seja: "não leu" não é sinônimo de "não viu". Em bases grandes há sempre uma parcela relevante de contatos com a confirmação desativada, e tratar todos como desinteressados leva a duas decisões erradas: reenviar para quem já leu, o que irrita e gera bloqueio, e descartar contato que estava respondendo por outro caminho.

A leitura útil do status de lido é agregada e comparativa, nunca individual. Se um template costuma ter 60% de leitura sobre entregues e cai para 30% de um dia para o outro, algo mudou — horário, assunto, imagem, público. O número absoluto de uma pessoa específica não sustenta conclusão nenhuma.

Há um efeito colateral que vale conhecer: quando a empresa marca as mensagens recebidas como lidas pela API, o cliente vê os tiques azuis do lado dela. Isso muda a expectativa de resposta — sinalizar leitura e demorar a responder é pior do que não sinalizar.

Falha: os padrões que importam

Toda falha vem com um código e uma descrição, e agrupá-las é o que transforma um disparo em diagnóstico. Os padrões que mais aparecem:

  • Número sem conta no WhatsApp. A base tem telefone que não usa o aplicativo, ou o número está errado. É problema de cadastro, não de envio.
  • Expiração. O aparelho não apareceu a tempo. Reenviar depois de um intervalo costuma resolver, e reenviar imediatamente costuma falhar igual.
  • Template inválido, pausado ou inexistente naquele número. A falha é de configuração e atinge o disparo inteiro, não contatos isolados. É a mais fácil de identificar porque a taxa de falha bate perto de 100%.
  • Fora da janela sem template. Tentativa de mandar mensagem livre para quem não escreveu nas últimas horas. Erro de fluxo, não da base.
  • Limite atingido. A conta bateu o teto de conversas iniciadas no período. A fila precisa desacelerar ou distribuir entre números.
  • Bloqueio pelo destinatário. A pessoa bloqueou a empresa. É definitivo para aquele contato e deve marcar o cadastro.
  • Restrição da plataforma. Recusas que não têm relação com a base — inclusive números que a própria Meta separa para testes internos. Reenviar não muda o resultado.

A regra que vale para todas: falha da Meta não se reenvia em laço. Insistir em mensagem recusada é uma das formas mais rápidas de derrubar a qualidade de um número. Falha nossa — configuração, rede, tempo esgotado — pode e deve ser reenviada depois de corrigida.

Como ler a curva de entrega de um disparo

Um disparo saudável tem uma assinatura reconhecível: entregas concentradas nos primeiros minutos, uma cauda que continua por horas e uma taxa de falha baixa e distribuída entre motivos variados.

Três desenhos indicam problema, cada um com uma causa diferente:

  • Falha alta desde a primeira mensagem. Configuração. Template, número, permissão ou janela. Parar o disparo, corrigir e recomeçar — insistir só queima o número.
  • Começa bem e degrada no meio. Limite ou qualidade. A conta bateu o teto do período, ou um template foi pausado com o disparo em andamento.
  • Entrega alta e leitura muito baixa. A mensagem chegou e não interessou. Aqui o problema é conteúdo ou horário, não infraestrutura — e é o único dos três que se resolve reescrevendo.

Que decisão tomar diante de cada padrão

O relatório só vale se produzir ação. Um roteiro curto:

  • Muitos "sem conta no WhatsApp". Limpar a base e revisar como o telefone é coletado no cadastro. Nenhuma mudança de disparo resolve isso.
  • Muitas expirações. Reprogramar o reenvio para outro horário, com intervalo de horas, e não reenviar em sequência.
  • Falha de template. Conferir se o modelo existe e está ativo naquele número. É a causa clássica quando a operação usa rodízio de números.
  • Limite atingido. Reduzir o ritmo, distribuir entre números e planejar a subida de tier em vez de forçar volume.
  • Bloqueios subindo. Parar e reescrever. Bloqueio é o sinal que a plataforma mais leva a sério, e ele antecede a queda de qualidade do número.

Onde o status chega e por que ele some

Os eventos de status não são consultados: eles são entregues. A Meta envia cada mudança para um endereço da empresa, configurado na conta. Isso tem duas implicações que derrubam operações inteiras e quase nunca aparecem como erro visível.

A primeira: se o endereço deixa de responder — servidor fora do ar, certificado vencido, troca de máquina, mudança de endereço sem atualizar a configuração —, os eventos param de chegar. O disparo continua funcionando, as mensagens continuam sendo entregues, e o painel simplesmente para de atualizar. O sintoma é um relatório congelado, não uma mensagem de erro.

A segunda: os eventos podem chegar fora de ordem ou repetidos. Um sistema que assume ordem cronológica acaba registrando "entregue" depois de "lido" e sobrescrevendo o estado mais avançado com o mais antigo. A regra correta é só avançar: uma mensagem que já está como lida não volta para entregue.

Vale ainda saber que o histórico de status não fica guardado indefinidamente do lado da plataforma. Quem quer relatório histórico precisa gravar os eventos quando eles chegam — não há como pedir depois.

Uma leitura em números

Um disparo de exemplo, com 10.000 contatos, ilustra a diferença entre ler e não ler o relatório.

O painel ingênuo diz: 10.000 enviadas, disparo concluído. O painel correto, medido seis horas depois, diz:

  • 9.980 aceitas pela Meta; 20 recusadas por formato de número inválido
  • 8.900 entregues — 89,2% das aceitas
  • 640 falhas por número sem conta no WhatsApp — 6,4%
  • 390 expiradas por aparelho ausente — 3,9%
  • 50 bloqueios — 0,5%
  • 4.700 leituras — 52,8% das entregues
  • 760 respostas por botão — 8,5% das entregues

Três decisões saem daí, e nenhuma delas apareceria no painel ingênuo. Os 640 números sem conta são um problema de cadastro que custa dinheiro em todo disparo e se resolve uma vez. As 390 expiradas viram um reenvio programado para outro horário, com expectativa realista de recuperar boa parte. E os 50 bloqueios, em 0,5%, estão em patamar aceitável — mas se o próximo disparo levar esse número para 2%, a reação certa é parar e reescrever a mensagem, não trocar de número.

Cinco erros de leitura

  • Chamar de "entregue" o que a Meta apenas aceitou. Produz relatório com 100% de sucesso e nenhum resultado.
  • Avaliar o disparo na primeira hora. A cauda de entrega dura horas; comparar disparos exige comparar a mesma janela.
  • Tratar "não leu" como "não viu". A confirmação de leitura é opcional para o destinatário, e uma parcela relevante da base a mantém desligada.
  • Reenviar o que a Meta recusou. É a maneira mais rápida de derrubar a qualidade do número, e o resultado do reenvio é o mesmo.
  • Confiar em relatório sem checar se os eventos ainda chegam. Painel congelado por endereço fora do ar parece disparo perfeito.

Os números para acompanhar

Cinco indicadores resumem a saúde de entrega de uma operação. A taxa de entrega sobre aceitas, medida sempre na mesma janela de horas, que é o indicador mestre. A composição das falhas por motivo, que separa problema de base, de configuração e de conteúdo — sem ela toda falha vira "erro do WhatsApp". A taxa de leitura sobre entregues por template, lida de forma comparativa, que mostra desgaste de mensagem antes de o bloqueio aparecer. A taxa de bloqueio, que é o sinal mais sensível de todos e o que antecede a queda de qualidade do número. E o tempo até a primeira resposta humana entre quem respondeu, porque toda a operação de entrega existe para produzir conversa, e conversa que espera esfria.

Perguntas frequentes

Mensagem "enviada" é o mesmo que entregue no WhatsApp?

Não, e essa confusão contamina relatórios inteiros. Quando o sistema pede o envio, a Meta responde na hora com um identificador — e essa resposta significa apenas que o pedido é válido e entrou na fila. Entre esse instante e a entrega existem várias razões para a mensagem morrer no caminho: o número pode não ter conta no WhatsApp, o aparelho pode estar desligado por dias, a pessoa pode ter bloqueado a empresa, o template pode ser pausado no meio do disparo, a cota do número pode se esgotar. Nenhuma dessas situações reverte a resposta já dada. Por isso um painel honesto separa três colunas — solicitadas, entregues e falhas — e usa a de entregues como denominador de qualquer taxa. Relatório que mostra "3.000 enviadas" sem dizer quantas chegaram não está medindo nada.

Por que a mensagem demora horas para aparecer como entregue?

Porque a mensagem fica retida esperando o aparelho do destinatário aparecer. Celular desligado, sem sinal, em modo avião ou com o aplicativo sem conexão faz a entrega esperar; quando o aparelho volta, a entrega acontece e o evento chega. Em uma base grande é normal que parte das entregas ocorra várias horas depois do disparo, e uma fração menor no dia seguinte. Duas consequências práticas: não se avalia um disparo pela taxa de entrega da primeira hora, e comparar disparos exige comparar a mesma janela de tempo. Vale saber também que mensagem não entregue dentro do prazo de validade da rede é descartada e gera uma falha por expiração — o que não significa número inválido, e sim aparelho ausente por tempo demais. Nesse caso, reenviar em outro horário costuma recuperar boa parte.

Se o status não mostra "lido", o cliente não viu a mensagem?

Não dá para concluir isso. A confirmação de leitura é uma configuração do destinatário, e quem a desliga nunca gera o evento, mesmo tendo lido a mensagem inteira. Em bases grandes há sempre uma parcela relevante de contatos nessa situação, e tratá-los como desinteressados leva a dois erros: reenviar para quem já leu, o que irrita e gera bloqueio, e descartar contato que estava respondendo por outro caminho. A leitura útil do status de lido é agregada e comparativa, nunca individual: se um template costuma ter 60% de leitura sobre entregues e cai para 30% de um dia para o outro, algo mudou — horário, assunto, imagem ou público. O número de uma pessoa específica não sustenta conclusão nenhuma.

Meu disparo está com quase tudo falhando. O que isso indica?

Falha alta desde a primeira mensagem quase nunca é problema da base: é configuração. As causas mais comuns são template inválido, pausado ou inexistente naquele número específico — clássico em operações com rodízio de números —, tentativa de enviar mensagem livre para quem não escreveu nas últimas horas, permissão ausente ou cota esgotada. A reação certa é parar o disparo, identificar o motivo agrupando as falhas por código e corrigir antes de recomeçar. Insistir é o pior caminho: reenviar mensagem que a Meta recusou é uma das formas mais rápidas de derrubar a qualidade do número, e o resultado do reenvio é o mesmo. Já quando o disparo começa bem e degrada no meio, a causa costuma ser outra: limite do período atingido ou template pausado com o envio em andamento.

Por que meu painel parou de atualizar os status?

Porque os eventos de status não são consultados, e sim entregues: a Meta envia cada mudança para um endereço configurado na conta da empresa. Se esse endereço deixa de responder — servidor fora do ar, certificado vencido, troca de máquina, mudança de endereço sem atualizar a configuração —, os eventos param de chegar. O disparo continua funcionando e as mensagens continuam sendo entregues; só o painel congela. O sintoma é um relatório parado, nunca uma mensagem de erro, e é por isso que essa falha costuma passar despercebida por dias. Há ainda dois cuidados de implementação: os eventos podem chegar fora de ordem ou repetidos, então o estado só deve avançar — mensagem já marcada como lida não volta para entregue —, e o histórico não fica guardado do lado da plataforma, o que significa que quem quer relatório histórico precisa gravar cada evento quando ele chega.

Relatório de disparo só vale quando separa aceito, entregue e falhou

O VeyloCRM registra cada evento de status que a Meta devolve, agrupa as falhas por motivo em português, mostra a curva de entrega do disparo em vez de um total inflado, avisa quando os eventos param de chegar e transfere para uma pessoa no instante em que o cliente responde — no WhatsApp, no Instagram Direct e no Messenger, no mesmo painel.