Erros da API oficial do WhatsApp: separar o que é problema seu do que é recusa da Meta

Erros de base e de destinatário

Esses aparecem espalhados pelo disparo, em proporção parecida de uma campanha para outra, e falam sobre o cadastro da empresa — não sobre o envio.

• Número sem conta no WhatsApp. O telefone existe, mas não usa o aplicativo. Não há o que reenviar. O valor está em marcar o contato para não pagar por ele todo mês.
• Número em formato inválido. Falta o código do país, sobra um caractere, o campo veio de uma planilha com máscara. É recusado antes de sair.
• Grafia do celular brasileiro. Caso particular e traiçoeiro: números antigos guardados sem o nono dígito, ou com um dígito que aquela região não usa. Quem decide qual grafia existe é o próprio WhatsApp, e a única forma correta é consultar antes de enviar em vez de adivinhar pelos dígitos.
• Expiração. A mensagem esperou o aparelho aparecer e o prazo acabou. Não é número inválido — é aparelho ausente. Reenvio em outro horário costuma recuperar boa parte.
• Bloqueio pelo destinatário. Aquela pessoa bloqueou a empresa. É definitivo e precisa marcar o cadastro, sob pena de a lista seguir pagando e degradando qualidade.

Recusas da plataforma

Aqui está o grupo que mais gera decisão errada, porque a mensagem devolvida parece um defeito e não é.

• Mensagem não pôde ser entregue. Recusa genérica, sem motivo detalhado. Pode ser filtro antifraude, comportamento do destinatário ou critério interno. Não se reenvia.
• Número em experimento da plataforma. A Meta separa parcelas de usuários para testes internos e recusa envios para eles. Não tem relação com a empresa nem com a base, e não muda por insistência.
• Template pausado por qualidade. Aquele modelo específico acumulou bloqueios e foi suspenso. O número segue saudável e os outros templates funcionam — trocar de número não resolve, reescrever a mensagem resolve.
• Restrição por política. Conteúdo que a plataforma não aceita, mesmo com template aprovado.

A confusão típica: a equipe vê muitas dessas recusas, conclui que "o número está queimado" e migra o disparo para outro número. O disparo recomeça, as mesmas recusas aparecem, e agora são dois números com qualidade pior. O caminho certo é conferir o que a plataforma está recusando, aceitar a parcela que não depende da empresa e olhar o conteúdo quando a proporção sobe.

A janela e o template: a confusão mais cara

Boa parte das falhas de operação nova vem de um mal-entendido único sobre quando cada tipo de mensagem pode ser usado.

Quando o cliente escreve para a empresa, abre-se uma janela de atendimento — comumente de 24 horas — em que a empresa responde com mensagem livre, do jeito que quiser. Fora dessa janela, mensagem livre é recusada, e o único caminho é um template aprovado.

Os dois erros espelhados:

• Tentar mensagem livre fora da janela. Acontece quando a automação responde a um contato antigo, ou quando o atendente abre uma conversa arquivada e escreve. A recusa fala em janela, e a correção é usar template.
• Usar template com a janela aberta. Não falha, mas custa dinheiro à toa e soa robótico para quem acabou de escrever.

Existe uma variação que confunde ainda mais: no Instagram Direct e no Messenger a lógica de janela também existe, com regras próprias. Uma trava escrita pensando só no WhatsApp acaba bloqueando resposta legítima nos outros canais — o cliente escreveu, a janela está aberta, e o sistema recusa porque aplicou a regra errada. Quem manda é o canal daquela conversa.

Limite, cota e qualidade

Três coisas diferentes que a equipe costuma chamar pelo mesmo nome.

O limite de conversas iniciadas é o teto de quantos contatos novos aquele número pode abrir em um período. Ele sobe conforme a operação demonstra volume e qualidade. Quando é atingido, a falha aparece no meio do disparo — começa bem e degrada.

A qualidade do número é um indicador da plataforma, baseado em bloqueios e denúncias. Qualidade baixa não impede envio por si só, mas costuma vir acompanhada de restrição de limite e é o alarme que antecede problema sério.

A pendência financeira é a mais silenciosa: conta comercial com fatura em aberto pode ter envios barrados mesmo com número verde e template aprovado. A falha não diz "fatura em aberto" — diz algo genérico —, e a equipe passa horas procurando defeito técnico. Vale a conferência antes de qualquer investigação longa.

Erros de mídia e cabeçalho

Template com imagem, vídeo ou documento no cabeçalho tem uma categoria própria de falhas, e elas costumam ser mal diagnosticadas porque a frase devolvida fala de parâmetro.

• Formato não aceito. Imagem em formato exótico, PNG com transparência ou perfil de cor incomum, arquivo com extensão que não corresponde ao conteúdo.
• Tamanho acima do limite. Cada tipo de mídia tem um teto próprio.
• Identificador de mídia de outro número. Arquivo enviado para a plataforma fica associado ao número que o enviou. Usar esse identificador em outro número falha — de novo, o rodízio esbarra nisso.
• Endereço de mídia expirado. Links de arquivos hospedados pela própria plataforma têm validade curta e não servem para reenvio posterior.

Um princípio de projeto vale ouro aqui: a preparação da mídia não deveria derrubar o envio. Se a conversão de uma imagem falha mas o arquivo original já está em formato aceito e dentro do limite, o certo é seguir com o original e deixar a plataforma decidir — não interromper o disparo inteiro por causa de uma etapa auxiliar.

O que pode e o que não pode ser reenviado

A tabela mental que evita a maior parte dos estragos:

• Reenviar depois de corrigir: template errado, parâmetro inválido, idioma trocado, permissão ausente, token expirado, falha de rede do próprio servidor.
• Reenviar depois de um intervalo, em outro horário: expiração por aparelho ausente.
• Nunca reenviar: recusa genérica da plataforma, número em experimento, bloqueio pelo destinatário, número sem conta no WhatsApp, restrição por política.

E uma regra de ouro para automação: reenvio automático em laço é proibido. Um sistema que tenta de novo sozinho, sem classificar o motivo, transforma uma recusa isolada em centenas de tentativas contra o mesmo destinatário — que é exatamente o padrão que a plataforma pune.

Como montar um painel de erros que decide

Um painel útil tem quatro características, e nenhuma delas é técnica.

Primeiro: mensagem em português. Código numérico e frase em inglês não dizem nada a quem opera. "Failed to send message because this user's phone number is part of an experiment" precisa aparecer como "a Meta bloqueou este número por estar em um teste interno dela". O texto original pode ficar guardado para investigação, mas não é o que a tela mostra.

Segundo: agrupamento por motivo, com contagem. Trinta linhas iguais não são trinta problemas; são um problema com trinta ocorrências.

Terceiro: classificação por grupo — configuração, base ou plataforma — para que a decisão saia do próprio painel.

Quarto: ação sugerida por grupo. Reenviar, limpar cadastro, corrigir configuração ou aceitar. Sem isso, todo erro vira chamado.

Um disparo em números

Um disparo de exemplo, com 3.173 contatos, mostra como a classificação muda a leitura.

O painel sem agrupamento mostra 130 linhas vermelhas e a conclusão da equipe é "o disparo falhou". Agrupado, o quadro é outro:

• 62 números sem conta no WhatsApp — 2,0% da base
• 34 recusas genéricas da plataforma — 1,1%
• 19 expirações por aparelho ausente — 0,6%
• 11 números em experimento da plataforma — 0,3%
• 4 bloqueios — 0,1%

São 130 falhas em 3.173, ou 4,1% — patamar normal. E as decisões são três, não uma: 62 contatos saem da base e param de custar; 19 entram em um reenvio programado para outro horário; e os 49 restantes são recusas da plataforma que não têm ação nenhuma. Nenhuma linha desse relatório justifica trocar de número, reescrever o template ou abrir chamado — que é exatamente o que teria acontecido diante das 130 linhas vermelhas soltas.

Cinco erros ao lidar com erros

• Reenviar o que a plataforma recusou. O resultado é o mesmo e a qualidade do número cai a cada tentativa.
• Trocar de número diante de recusa da plataforma. Leva o problema para o número novo e agora são dois com histórico ruim.
• Deixar o disparo rodar com falha alta desde o início. Falha de configuração não se descobre insistindo; descobre-se parando.
• Mostrar o texto da Meta na tela do operador. Erro em inglês não produz decisão — produz chamado.
• Procurar defeito técnico antes de conferir a conta. Fatura em aberto e permissão ausente causam falhas que parecem bug e se resolvem no painel da Meta.

Os números para acompanhar

Cinco indicadores mantêm a operação sob controle. A taxa de falha total por disparo, comparada com a média histórica da empresa, que é o alarme mais simples. A composição das falhas por grupo — configuração, base e plataforma —, que diz quem precisa agir. O percentual de contatos inválidos na base, que só cai com trabalho de cadastro e que custa dinheiro em toda campanha. A taxa de bloqueio, o indicador mais sensível de todos, que antecede a queda de qualidade do número. E a quantidade de reenvios automáticos disparados, que deveria ser próxima de zero para recusas da plataforma — quando esse número cresce, o sistema está trabalhando contra a própria operação.