Mensagem enviada no WhatsApp e o cliente não recebe: causas e solução

Entender a cadeia evita procurar no lugar errado. Primeiro, o seu sistema faz a chamada e a API a aceita (resposta de sucesso). Segundo, a instância a coloca na fila, respeitando o atraso configurado entre mensagens. Terceiro, a sessão do WhatsApp envia para os servidores da plataforma (um tique). Quarto, o aparelho do destinatário recebe (dois tiques) e depois a pessoa lê.

Cada etapa tem uma causa típica de falha: dados errados na primeira, fila ou desconexão na segunda, restrição do número na terceira e aparelho ou bloqueio do cliente na quarta. O glossário descreve os estados de entrega.

É a causa mais frequente. O número precisa ir com código do país e só dígitos, e alguns países têm regras próprias de formato. Um número fixo, desativado ou digitado com erro pode até ser aceito pela API, mas não vai chegar a ninguém.

Antes de campanhas e em suspeitas pontuais, verifique se o número tem WhatsApp com o endpoint de checagem, que devolve se cada número está registrado e o seu identificador. A ferramenta de validar número faz o mesmo na página. Limpar a lista antes de enviar também melhora a reputação do número.

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/chat/check \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"numbers":["5511999999999"]}'

Se a sessão caiu, as mensagens não saem. Consulte o status da instância: conectado, conectando ou desconectado. Em desconexão, é preciso ler um novo QR code. Ative alertas de mudança de conexão no seu webhook para saber na hora, e não pelo cliente.

Mensagens enviadas durante a desconexão podem não ter sido aceitas, então vale reenviar depois de reconectar, com cuidado para não duplicar. Use o histórico de mensagens da API para conferir o que de fato saiu antes de reenviar.

curl https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/instance/status \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET"

A instância tem um atraso mínimo e máximo entre mensagens, e campanhas usam intervalos aleatórios. Em lotes grandes, a última mensagem pode demorar para sair, e quem olha cedo conclui que "não foi". A resposta de status da instância mostra o atraso configurado.

Se o atraso estiver alto sem necessidade, ajuste-o com cuidado: reduzir demais o intervalo aumenta o risco de restrição. Para campanhas, acompanhe o andamento pela pasta do disparo em vez de reenviar. Veja o disparo em massa.

Se o cliente bloqueou o seu número, a mensagem fica com um tique só, sem entregar, e a plataforma não avisa você. Se o celular dele está sem internet ou desligado, o segundo tique aparece quando ele volta. Um tique por muitas horas e o segundo nunca chegando é o padrão clássico de bloqueio ou aparelho fora do ar.

Não insista com reenvios repetidos: eles aumentam denúncias. Tente um canal alternativo, como ligação ou e-mail, e confirme com o cliente se ele consegue ver mensagens suas. Quem repetidamente tem mensagens sem entrega deve ser removido da lista de envio.

Quando o WhatsApp limita o número, as mensagens podem ficar sem sair ou sair só para alguns contatos. O endpoint de limites informa quantas novas conversas o número pode iniciar no momento, o que ajuda a distinguir limitação de erro de integração.

Se a causa for restrição, siga o passo a passo do número bloqueado e reveja o comportamento de envio pela matriz de risco. O uso por API não oficial não é previsto nos Termos do WhatsApp, e a decisão sobre a conta é da plataforma.

1) Cheque o número: tem WhatsApp? Formato e código do país corretos? 2) Cheque a instância: conectada? 3) Cheque o histórico: a mensagem aparece nas mensagens da instância? 4) Cheque o webhook: o evento de status chegou? Use o endpoint de entregas recentes e o de erros para ver se o seu servidor respondeu 2xx. 5) Cheque o destinatário: ele bloqueou, está sem internet ou é um número que já não responde?

Registrar o ID da mensagem devolvido pelo envio permite cruzar todas as etapas. Se o problema é o webhook não chegando, veja o guia de receber mensagens por webhook. Se o problema é geral, a documentação da API lista os endpoints de apoio.

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/message/find \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"chatid":"5511999999999@s.whatsapp.net","limit":20}'

curl "https://api.zapzapapi.com/api/v1/instances/SEU_INSTANCE_ID/webhook/deliveries?limit=20" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET"

Valide números antes de campanhas, monitore a conexão com alertas, registre o ID de cada envio, trate o status de entrega no webhook (marcando falhas no seu sistema) e crie uma regra para tirar da lista quem acumula falhas. Para o cliente final, ofereça um canal alternativo quando uma mensagem for crítica, como cobrança ou confirmação.

Por fim, desconfie de métricas de "enviado" como prova de entrega. Meça entregue, lido e respondido, e use a resposta como o sinal mais confiável de que a conversa existe.

Às vezes a mensagem chegou ao cliente, mas o seu sistema não registrou o status porque o webhook falhou. Nesse caso o painel interno mostra "não entregue" e a equipe reenvia, gerando duplicidade. Compare o histórico de mensagens da instância com o seu banco antes de concluir que houve falha de entrega.

Use o endpoint de teste do webhook para validar a URL, olhe as últimas entregas para ver o código HTTP que o seu servidor devolveu e a lista de erros para achar timeouts. Se o seu endpoint demora, responda 2xx na hora e processe depois, em fila.

Em grupos, o identificador termina em g.us e é diferente do número de uma pessoa; usar o formato errado resulta em mensagem que nunca chega. Para números de outros países, confirme o código do país e use a checagem de números antes de enviar, porque cada país tem regras próprias de formato.