Mensagem de WhatsApp não entregue: como descobrir o motivo

"A API retornou sucesso, mas o cliente diz que não recebeu."

É a reclamação mais frustrante de quem integra WhatsApp, porque as duas afirmações costumam ser verdadeiras ao mesmo tempo. A API confirma que aceitou e despachou a mensagem. Isso não é a mesma coisa que ela ter chegado ao aparelho — e muito menos que alguém a tenha lido.

Este guia separa os estágios, explica o que pode falhar em cada um e dá um roteiro de diagnóstico na ordem certa.

Os quatro estágios de uma mensagem

Entender isso resolve metade dos casos sozinho.

Estágio	O que significa	Como você sabe
Aceita	Sua requisição foi validada e despachada	Resposta 200 com messageId
Enviada	Saiu para os servidores do WhatsApp	Um traço no app
Entregue	Chegou ao aparelho do destinatário	Dois traços
Lida	O destinatário abriu a conversa	Dois traços azuis

O {"success": true, "messageId": "..."} que você recebe confirma o primeiro estágio. Entre ele e o aparelho do cliente existem três etapas que não dependem de você — e a maioria dos "não recebi" mora ali.

Para acompanhar os estágios seguintes, é preciso escutar o evento de atualização de status pelo webhook. Sem isso, você opera às cegas depois do despacho.

Roteiro de diagnóstico

Siga na ordem. Cada passo elimina uma causa inteira.

Passo 1: o envio realmente teve sucesso?

Antes de investigar o WhatsApp, confirme que a requisição não falhou. Se o seu código não trata o retorno, um erro pode estar passando despercebido:

const res = await fetch(url, opcoes);
const dados = await res.json();

// sem esta verificação, erro vira "sucesso" silencioso
if (!res.ok) {
  console.error("envio falhou", res.status, dados);
}

Cheque o log do envio específico. Se houver 502, a mensagem nunca saiu — e aí o problema é outro, tratado abaixo.

Passo 2: o número está certo?

Causa número um de "não recebeu", e a mais fácil de verificar.

O formato exigido é internacional, só dígitos: código do país + DDD + número. 5511987654321.

Os erros recorrentes:

• Sem o 55. 11987654321 não é um número brasileiro para a API — é um número de outro país, ou nada.
• Com formatação. (11) 98765-4321 não passa na validação.
• Com o zero do DDD. 55011987654321 está errado.
• Nono dígito. Alguns números antigos existem no WhatsApp sem o 9; outros só com. A normalização correta está em integrar WhatsApp com CRM.

Se o número não tiver o mínimo de dígitos, a API responde 400 antes de tentar qualquer coisa. Se tiver o formato certo mas não existir no WhatsApp, o resultado costuma ser 502 — a requisição estava correta, o destino é que não existe.

Antes de investigar mais fundo, teste o número no validador.

Passo 3: a instância está conectada?

Se a sessão caiu, os envios falham em série. O sintoma é característico: tudo parou de funcionar ao mesmo tempo, não uma mensagem isolada.

curl https://zapixo.com.br/api/v1/instances/minha-loja/status \
  -H "Authorization: Bearer SUA_CHAVE"

status: "disconnected" explica tudo. O procedimento de reconexão está em instância desconectou.

Passo 4: o destinatário bloqueou?

Aqui está o caso mais desconfortável: se o destinatário bloqueou o seu número, a mensagem é aceita normalmente e simplesmente não chega. Não há erro, não há aviso, não existe forma de detectar bloqueio pela API. Do seu lado, tudo parece perfeito.

O indício é o padrão: um contato específico nunca passa de "enviada", enquanto os outros avançam normalmente. Um contato assim, isolado, é quase sempre bloqueio.

Se muitos contatos apresentam o mesmo padrão ao mesmo tempo, a causa provavelmente é outra — veja o passo 6.

Passo 5: o aparelho do cliente está offline?

Mensagem para celular desligado, sem internet ou com o WhatsApp desinstalado fica em "enviada" e é entregue quando o aparelho voltar. Não é falha: é fila do lado de lá.

Antes de reenviar, espere. Reenviar por impaciência produz mensagem duplicada quando o cliente religa o telefone — e duplicata em aviso de cobrança gera pânico.

Passo 6: o seu número está restrito?

O cenário mais sério. Se o número foi limitado pela Meta, os envios podem ser aceitos e não entregues, de forma ampla.

Os sinais que apontam para cá:

• Muitos destinatários parados em "enviada" simultaneamente.
• Queda brusca de entrega, sem mudança no seu código.
• A instância desconecta e reconecta de forma anormal.
• O WhatsApp no celular do número exibe aviso de restrição.

Se for isso, parar de disparar é a primeira medida — insistir agrava. As práticas para não chegar nesse ponto estão em como evitar banimento.

Como registrar para não investigar no escuro

Metade da dificuldade de diagnóstico vem de não ter o dado. O mínimo para conseguir responder "o que aconteceu com a mensagem do pedido 4821":

CREATE TABLE envios (
  id           BIGSERIAL PRIMARY KEY,
  referencia   TEXT NOT NULL,        -- 'pedido-4821-confirmado'
  numero       TEXT NOT NULL,
  numero_canon TEXT NOT NULL,        -- normalizado, para busca
  message_id   TEXT,                 -- devolvido pela API
  http_status  INT,
  erro         TEXT,
  status_final TEXT,                 -- atualizado pelo webhook
  enviado_em   TIMESTAMPTZ DEFAULT now()
);

Com isso, a investigação vira uma consulta em vez de uma escavação. E o message_id é o que amarra o envio aos eventos de status que chegam depois.

O que fazer em cada caso

Sintoma	Causa provável	Ação
400 no envio	Número mal formatado	Corrigir a normalização na origem
404 no envio	Nome de instância errado	Conferir o nome no painel
429 no envio	Passou do limite por minuto	Reenfileirar e desacelerar
502 em série	Instância caída	Pausar a fila, reconectar
502 isolado	Número não existe no WhatsApp	Marcar o contato como inválido
Sucesso, um contato parado	Bloqueio ou aparelho offline	Aguardar; não reenviar em laço
Sucesso, muitos parados	Possível restrição do número	Parar os disparos e investigar

Duas armadilhas comuns

Reenviar automaticamente o que "não foi entregue". Entrega pendente não é falha — é espera. Retentativa automática nesse caso gera duplicata assim que o aparelho do cliente volta. Retente falha de envio (502), nunca falha de entrega.

Confundir "não lida" com "não entregue". Mensagem entregue e não lida significa apenas que a pessoa não abriu a conversa. Não há nada a corrigir, e insistir só irrita.

Resumo

success: true responde uma pergunta só: a API aceitou e despachou. Entre isso e a leitura existem três estágios que dependem do WhatsApp, da rede e do aparelho do destinatário.

O roteiro que resolve quase todos os casos: confirme que a requisição não falhou, confira o formato do número, verifique o status da instância e só então considere bloqueio, aparelho offline ou restrição. E registre messageId, status HTTP e status final de cada envio — sem esse registro, toda investigação vira suposição.