Pular para o conteúdo principal

Mensagem não foi entregue

Resumo: Uma mensagem ficou com status FAILED ou nunca apareceu para o cliente. Veja a causa pela tela de detalhes da mensagem. As causas mais comuns são: número sem WhatsApp, bloqueio do cliente, janela de 24h fechada (WABA), ou canal desconectado.

Quando usar isso​

A mensagem que você enviou:

  • Aparece com status FAILED no painel.
  • Tem o erro failedReason preenchido.
  • O cliente diz que não recebeu nada.

Como diagnosticar​

  1. No painel, abra a conversa.
  2. Clique na mensagem que falhou.
  3. Veja o campo Motivo da falha (failedReason).
  4. Use a tabela abaixo para entender e resolver.

Causas mais comuns e como resolver​

O número não tem WhatsApp​

O que aparece:

  • Mensagens de erro Meta: Recipient phone number not registered on WhatsApp, WhatsApp Business API: Phone number not on WhatsApp
  • No Baileys: erro de envio para JID inválido

O que aconteceu: O número que você tentou enviar não existe no WhatsApp. Pode ser um número fixo, número antigo, errado, ou de país onde o WhatsApp não opera.

Como resolver:

  • Confirme o número com o cliente (talvez tenha um dígito errado).
  • Use o endpoint de lookup (POST /v1/lookup) antes de disparos em massa para validar quem tem WhatsApp.
  • Para números fixos: ofereça outro canal (SMS, ligação).

Cliente bloqueou seu número​

O que aparece:

  • Mensagem fica como SENT no WABA, mas nunca chega em DELIVERED. Ou erro Receiver has blocked you.
  • No Baileys, pode falhar silenciosamente (sem ✓✓).

O que aconteceu: O cliente bloqueou seu número no WhatsApp dele.

Como resolver: Não há nada que você possa fazer pelo gateway. Você não tem forma técnica de saber se foi bloqueado (a Meta não expõe). Tente um canal alternativo (e-mail, SMS, ligação). Se for cliente importante, considere o que pode ter motivado o bloqueio (excesso de marketing, mensagens irrelevantes).

Janela de 24h fechada (WABA)​

O que aparece:

  • RE_ENGAGEMENT_MESSAGE_REQUIRED
  • (#131047) Re-engagement message: Cannot send free-form messages outside the 24 hour customer service window

O que aconteceu: Você tentou enviar texto livre para um contato fora da janela de 24h (o cliente não te respondeu nas últimas 24h).

Como resolver: Envie um template aprovado em vez de mensagem livre. Veja Quando preciso usar template vs mensagem livre.

Canal desconectado​

O que aparece:

  • PHONE_NOT_CONNECTED
  • Status do canal aparece como DISCONNECTED, TOKEN_EXPIRED ou FAILED

O que aconteceu: O canal perdeu conexão com WhatsApp/Meta/Instagram.

Como resolver: Veja Meu número desconectou — o que fazer.

Conta WABA suspensa pela Meta​

O que aparece:

  • Business has been suspended
  • Phone number is in PENALTY status
  • Quality rating do canal caiu para RED

O que aconteceu: A Meta suspendeu seu número WABA por queda de qualidade (muitos clientes marcaram como spam, denúncias, ou política violada).

Como resolver:

  1. Acesse WhatsApp Manager → veja o motivo da suspensão.
  2. Aguarde o período de penalidade (24h a alguns dias).
  3. Avalie o que causou: usou Marketing demais? Mandou para opt-outs? Mensagens irrelevantes?
  4. Após reativação, reduza volume e melhore qualidade do conteúdo.

Limite de envio do tier WABA estourado​

O que aparece:

  • Rate limit hit
  • (#80007) Rate limit
  • Reached daily limit for customer service messages

O que aconteceu: Sua conta WABA tem um tier de envio (250/dia, 1k/dia, 10k/dia, 100k/dia, ilimitado). Você passou do limite diário.

Como resolver:

  • Aguarde o reset (no próximo dia UTC).
  • Para subir de tier, mantenha qualidade alta e volume estável por semanas. A Meta sobe automaticamente.

Conta gateway suspensa por inadimplência​

O que aparece:

  • HTTP 402 PAYMENT_REQUIRED
  • ACCOUNT_SUSPENDED

Como resolver: Pague as faturas em aberto. Veja Inadimplência e suspensão.

Mídia inválida​

O que aparece:

  • (#131026) Message Undeliverable: Media format not supported
  • File too large

O que aconteceu: Arquivo grande demais (>16 MB para WABA / >100 MB Baileys) ou formato não suportado.

Como resolver:

  • Comprima ou reduza qualidade da mídia.
  • Use formato padrão: JPG para imagem, MP4 para vídeo, MP3/OGG para áudio.

Template não aprovado, pausado ou desabilitado​

O que aparece:

  • Template not approved, Template is paused, Template name does not exist

Como resolver: Acesse a tela de Templates, verifique o status, recrie ou aguarde aprovação. Veja Template rejeitado pela Meta.

Checklist rápido​

Antes de assumir que é "bug", confira:

  • O canal está conectado? (Status CONNECTED no painel?)
  • O número de destino tem WhatsApp? (Tente abrir wa.me/55... no navegador)
  • Para WABA: é texto livre fora da janela 24h? (Use template)
  • Para WABA: a Meta retornou algum erro específico no failedReason?
  • A conta gateway está ativa? (Não está em SUSPENDED?)
  • O arquivo de mídia está dentro do limite de tamanho/formato?

Dúvidas comuns​

O cliente diz que recebeu, mas o status mostra FAILED. Pode acontecer se o gateway perdeu o callback de confirmação. Geralmente é raro. Se for sistemático, contate suporte com o messageId.

Tem como reenviar mensagens que falharam? Não há retry automático para FAILED — pode ser problema persistente (número errado). Você precisa decidir caso a caso pelo seu sistema.

Por que algumas mensagens falham só em certos horários? Possíveis causas:

  • Pico de uso seu (estoura tier diário)
  • Rate limit Meta em períodos de alto tráfego globais
  • Manutenção da Meta (raríssimo, geralmente anunciado)

O cliente disse "não recebi" mas mostra DELIVERED. O WhatsApp confirmou entrega ao celular. Possíveis explicações:

  • Cliente apagou sem ler
  • Notificações desabilitadas no celular dele
  • Mensagem foi parar em "filtrados" do WhatsApp Business
  • Cliente está usando outro celular

Artigos relacionados​