Erro 131026 no WhatsApp: Message undeliverable — causas e soluções

O 131026 é o erro mais frustrante da Cloud API: a mensagem sai como accepted, e a falha só aparece depois, no webhook, sem um motivo específico. Este guia organiza o diagnóstico.

O que é o erro 131026

Ele costuma chegar no webhook de status, como failed:

{
  "statuses": [{
    "id": "wamid.XXXX",
    "status": "failed",
    "errors": [{
      "code": 131026,
      "title": "Message undeliverable",
      "error_data": {
        "details": "Unable to deliver message. Reasons can include: The recipient phone number is not a WhatsApp phone number. Recipient has not accepted our new Terms of Service and Privacy Policy. Recipient using an old WhatsApp version..."
      }
    }]
  }]
}

As causas — oficiais e reais

As três documentadas pela Meta:

1. O número do destinatário não é uma conta de WhatsApp (inexistente, desativado, ou dígito errado)
2. O destinatário não aceitou os novos termos de serviço do WhatsApp
3. O destinatário usa uma versão muito antiga do app

As que o ecossistema aprendeu na prática:

4. Filtros de proteção da Meta ("healthy ecosystem") segurando templates de marketing para usuários que nunca conversaram com seu número ou que recebem marketing demais — a causa mais comum em campanhas frias, com sobreposição do código 131049
5. Formato do número errado — o campo to exige E.164 sem sinal de mais, sem zeros à esquerda (ex.: 5511999999999)
6. Restrições regionais — por exemplo, a pausa de templates de marketing para números dos EUA (relacionada ao erro 130497)

Diagnóstico passo a passo

1. Confirme o número. Abra wa.me/5511999999999 ou procure o contato — o número tem WhatsApp ativo?
2. Confira o formato E.164 no seu payload (código do país + DDD + número, sem símbolos).
3. Teste com um template de utilidade para o mesmo destinatário. Se a utilidade entrega e o marketing falha, não é o número — é filtro da Meta sobre a categoria marketing.
4. Não faça retry imediato. Se a causa for filtro ou limite de frequência, repetir na hora devolve o mesmo erro e piora seus sinais. Espaçe as tentativas em intervalos crescentes (horas, não segundos).
5. Peça o primeiro contato ao cliente. Se o destinatário mandar qualquer mensagem para o seu número, abre-se a janela de 24 horas — e a entregabilidade fica garantida.
6. Olhe o padrão, não o caso. Um 131026 isolado é ruído (número inexistente acontece). Uma taxa alta numa campanha é sinal de base fria ou filtro — pare e reveja a segmentação, como num cenário de erro 131048.

Como reduzir o 131026 em campanhas

• Higienize a base — remova números que já falharam repetidamente; insistir só suja seus sinais
• Priorize quem já interagiu — a entregabilidade de marketing é muito maior para quem já conversou com o número
• Colete opt-in dentro do WhatsApp quando possível (anúncio click-to-WhatsApp, link wa.me) — o primeiro contato do cliente elimina a categoria inteira de filtros
• Monitore os status failed por código de erro — sem isso, mensagens somem em silêncio e você só percebe na queda de conversão

Esse monitoramento é justamente o que uma plataforma sobre a API oficial entrega pronto: a Wizebot mostra relatórios de entrega por campanha e contato, separa falhas por causa e mantém a higiene da base com tags e engajamento — o jeito de manter a taxa de entrega perto dos 99%.

Perguntas frequentes

O 131026 não se "conserta" com força bruta — se lê com método: número válido? categoria filtrada? base fria? Com diagnóstico certo, ele vira métrica de higiene da base. Para operar campanhas com essa visibilidade nativa, a Wizebot acompanha cada envio da API oficial do disparo à entrega.