Por que a Meta recusa seus templates do WhatsApp (erros 131009 e 190) e como resolver

Poucas coisas travam tanto uma equipe quanto preparar uma campanha, clicar em enviar e receber uma recusa de template do WhatsApp que nao explica nada. A Meta devolve um codigo numerico, sua plataforma mostra um erro cru e a conversa para. A boa noticia e que quase toda recusa cai em um punhado de causas conhecidas, e os dois codigos que voce mais vera (131009 e 190) tem solucoes concretas. Neste guia detalhamos cada um e damos um metodo para voltar a operar rapido.

Recusa na aprovacao ou falha no envio: saiba qual e a sua

A recusa pode acontecer em dois momentos bem diferentes, e misturar os dois faz voce perder horas:

• Na aprovacao do template: a Meta revisa o conteudo antes de liberar o uso. Se o texto viola politicas, tem variaveis mal formadas ou parece spam, fica no status Rejected.
• No envio da mensagem: o template ja esta aprovado, mas a chamada a API falha. E aqui que surgem codigos como 131009 e 190.

Um 190 nunca se resolve editando o texto do template, e uma recusa de conteudo nunca se resolve renovando um token. Diagnostique o momento primeiro.

Erro 131009: valor de parametro invalido

O 131009 ("Parameter value is not valid") e a maior dor de cabeca porque a mensagem e generica e a causa real quase sempre esta escondida. Os gatilhos mais comuns:

1. IDs ou titulos duplicados em botoes e listas. A Meta exige que titulos de Reply Buttons, IDs de linhas de List e SKUs de catalogo sejam unicos dentro da mesma mensagem. Dois botoes com o mesmo titulo, ou duas linhas com o mesmo id, disparam um 131009 sem dizer qual.
2. Numero de variaveis que nao bate. Se o template tem {{1}} {{2}} {{3}} e voce envia dois parametros, a validacao falha.
3. Numero do destinatario mal formatado. O wa_id precisa estar em formato internacional. Prefixar com "+" e interpretar sem assumir um pais padrao evita erros no Brasil, Mexico ou Colombia.
4. Componentes fora de ordem (header, body, buttons) ou um botao de URL dinamico sem o parametro.

O atalho: ao receber um 131009, verifique primeiro a unicidade de botoes e linhas, depois a contagem de variaveis. Isso cobre cerca de 80% dos casos.

Erro 190: o token de acesso expirou

O 190 (OAuthException) e mais facil de diagnosticar: se todos os seus envios falham de uma vez com esse codigo, nao e o template, e o token de acesso do canal que expirou. Tokens de System User podem expirar por rotacao de credenciais, mudanca de permissoes no app da Meta ou revogacao manual.

A solucao nao e o template, e reconectar o canal:

• Rode novamente o Embedded Signup do WhatsApp para gerar um novo token.
• Confirme que o System User do seu app Business tem as permissoes whatsapp_business_messaging e whatsapp_business_management.
• Se usa tokens de longa duracao, agende a rotacao antes da data de expiracao em vez de esperar a falha.

Por que o conteudo e recusado na aprovacao

Quando a Meta marca o template como Rejected na revisao, geralmente e por:

• Categoria errada. Uma mensagem promocional enviada como Utility e recusada. Escolha Marketing, Utility ou Authentication conforme a intencao real.
• Variaveis no comeco ou no fim sem texto ao redor, ou duas variaveis seguidas.
• Linguagem de spam ou pressao exagerada ("COMPRE JA", excesso de maiusculas ou emojis).
• Placeholders enviados sem valores de exemplo.

Como corrigir e reenviar

Um fluxo que funciona:

1. Use o codigo para decidir se e falha de aprovacao ou de envio.
2. Para 131009, corrija unicidade e variaveis; envie um teste para um unico numero antes da campanha em massa.
3. Para 190, reconecte o canal e tente de novo.
4. Para recusa de conteudo, ajuste categoria e texto e reenvie para revisao (geralmente de minutos a 24 horas).

Uma plataforma bem construida evita boa parte disso. No Omnifox a caixa de entrada valida a unicidade de botoes e a contagem de variaveis antes de tocar na API, e avisa quando um canal precisa de reconexao por token vencido, para voce nunca descobrir um 190 no meio da campanha.

Como prevenir recusas futuras

• Mantenha uma biblioteca de templates ja aprovados e reutilize.
• Nomeie botoes e linhas com um esquema unico (por exemplo, prefixo por secao).
• Teste cada template novo com um envio real antes de escalar.
• Acompanhe a nota de qualidade do seu numero; uma nota baixa aumenta as recusas.

Conclusao

A recusa de template do WhatsApp deixa de ser um misterio quando voce separa o momento da falha e le o codigo certo: 131009 quase sempre e unicidade ou variaveis, 190 e token expirado. Com o habito de testar antes de escalar e uma plataforma que valida por voce, os bloqueios ficam raros. Se quer uma caixa de entrada que pega esses erros antes da Meta, experimente o Omnifox e envie seus templates com rede de seguranca.