Mensagem enviada mas não entregue na API do WhatsApp: checklist de diagnóstico

Atualizado em 29/10/2026

Quando a API do WhatsApp aceita a mensagem mas ela não chega, a resposta está no webhook de status: ou a mensagem ficou parada em sent (saiu dos servidores da Meta, mas não chegou ao aparelho) ou terminou em failed com um código de erro. No primeiro caso, as causas mais comuns são cliente offline, número bloqueado pelo cliente ou país com restrição; no segundo, o código diz o que aconteceu e se vale reenviar. A Meta só cobra mensagens entregues, então uma mensagem que não chegou não entra na fatura.

Este checklist parte do sintoma que você vê no seu sistema e chega à ação. Para a referência completa de códigos, veja o guia de erros da API do WhatsApp.

Passo 1: confirme que a API aceitou a mensagem

Antes de falar em entrega, confira a resposta síncrona do envio. Se a chamada devolveu um objeto error, a mensagem nem saiu: o problema é de token, parâmetro, template ou limite de chamadas, e não de entrega. Se devolveu 200 com um wamid, a mensagem foi aceita:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
  "messages": [{ "id": "wamid.HBgLNTUxMTk5OTk5OTk5..." }]
}

Guarde esse wamid. É por ele que você liga cada evento de status à mensagem original. Sem ele no banco, o diagnóstico vira adivinhação.

Passo 2: leia o status no webhook

A partir daqui, tudo chega pelo webhook messages, no array statuses. A referência de status da Meta define cinco valores:

Status	O que a Meta diz	O que significa para o diagnóstico
sent	A mensagem saiu dos servidores da Meta	Aceita e despachada, mas ainda não chegou ao aparelho
delivered	Entregue no aparelho do usuário	Chegou; a partir daqui é cobrável
read	Exibida numa conversa aberta no aparelho	Lida (só conta como lida se foi entregue)
played	Primeira reprodução de uma mensagem de voz	Só para áudio de voz
failed	Falha ao enviar ou entregar	Veja o array errors

Dois detalhes evitam alarme falso. Primeiro, se o usuário lê a mensagem na hora, a Meta pode não mandar o delivered, porque o read já implica a entrega. Então “não recebi delivered” não quer dizer “não foi entregue” quando existe read. Segundo, se o webhook não está chegando de jeito nenhum, o problema é outro: revise a configuração descrita no guia de webhooks da API do WhatsApp antes de culpar a entrega.

O guia de status de mensagem via webhook mostra como gravar esses eventos. Aqui o foco é o que fazer quando eles mostram um problema.

Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →

Passo 3: mensagem parada em sent

Este é o caso mais confuso: nada de erro, mas também nada de delivered. A página de suporte da Cloud API lista as causas mais comuns:

• O cliente não ficou online. A Meta segura mensagens para usuários offline por uma janela de 30 dias. Se o aparelho não conectar nesse prazo, a mensagem não é entregue.
• O cliente bloqueou o número da empresa, ou outro número comercial da mesma empresa.
• O cliente está em um país restrito ou sancionado.

A Meta avisa que, em muitos desses casos, não revela a causa exata. Por isso a ação é a mesma para os três: confirmar por outro canal (e-mail, SMS, ligação) se a pessoa consegue mandar mensagem para o seu número, se não bloqueou a empresa e se o app está atualizado.

O que não fazer: reenviar a mesma mensagem a cada hora. Se houve bloqueio, o reenvio não muda o resultado.

Passo 4: mensagem em failed com código

Quando a entrega falha, o evento traz o array errors, com code, title, message e error_data.details. A tabela abaixo cobre os códigos que mais aparecem em “enviei e não chegou”, conforme a tabela de códigos de erro da Meta:

Sintoma no webhook	Causa	Ação
failed 131026	Não foi possível entregar: número sem WhatsApp, usuário não aceitou os termos atuais ou usa versão antiga do app	Confirmar o número por outro canal; não reenviar em loop. Detalhes em erro 131026
failed 131047	Mais de 24 horas desde a última resposta do cliente	Enviar template. Ver erro 131047
failed 131049	Marketing não entregue para manter o engajamento saudável (limite por usuário)	Esperar pelo menos 24 horas antes de reenviar
failed 131050	O usuário parou de receber marketing da sua empresa	Não reenviar; tratar como opt-out
failed 130472	Mensagem não enviada por fazer parte de um experimento da Meta	Não reenviar; ver erro 130472
failed 131042	Problema com a forma de pagamento	Revisar faturamento da conta
failed 131048	Restrição de envio do número: muitas mensagens anteriores bloqueadas ou marcadas como spam	Ver a qualidade no WhatsApp Manager
failed 131056	Muitas mensagens para o mesmo destinatário em pouco tempo	Esperar e tentar de novo só para esse contato
failed 131000	Erro desconhecido	Tentar de novo; se persistir, abrir chamado
sent sem delivered por dias	Cliente offline, bloqueio ou país restrito	Confirmar por outro canal
delivered e failed para a mesma mensagem	Cliente com vários aparelhos: chegou em um, falhou em outro	Considerar entregue

Os códigos que dependem do destinatário

O 131026 é o “não entregue” genérico. A Meta cita três causas e não diz qual ocorreu: o número não é de WhatsApp, a pessoa não aceitou os termos e a política de privacidade mais recentes, ou usa uma versão antiga do app. A orientação oficial é pedir, por outro canal, que o usuário confirme que consegue mandar mensagem ao seu número, aceite os termos e atualize o aplicativo.

O 131050 é escolha do usuário: ele parou de receber marketing da sua empresa. A Meta orienta não reenviar e sugere assinar o webhook user_preferences para saber quando o usuário para ou volta a aceitar marketing.

Os códigos de marketing

O 131049 é o limite por usuário de templates de marketing. A Meta diz que, se você suspeita desse limite, deve esperar pelo menos 24 horas antes de reenviar, porque reenviar antes gera o mesmo erro. O tema tem artigo próprio: limite de marketing por usuário.

O 130472 é de um experimento da Meta que retém marketing para uma porcentagem muito pequena de usuários. Não é falha do seu código e não há como contornar.

Os códigos da sua conta

O 131042 aponta para a forma de pagamento. A Meta lista como causas comuns linha de crédito acima do limite, conta de pagamento não vinculada, linha de crédito inativa, fuso ou moeda não configurados e solicitação “em nome de” (On Behalf Of) pendente ou recusada.

O 131048 é sinal de qualidade: o número está com restrição porque muitas mensagens anteriores foram bloqueadas ou denunciadas como spam. Antes de reenviar, revise o conteúdo e a origem da base. O guia de qualidade do número explica como acompanhar.

Passo 5: descarte limite de mensagens e forma de pagamento

Duas causas ficam fora do nível da mensagem e afetam tudo de uma vez.

Limite de mensagens do portfólio. A documentação de limites define o limite como o número máximo de destinatários únicos que você pode alcançar fora da janela de atendimento em 24 horas móveis. Portfólios novos começam em 250. O limite é do portfólio inteiro, então um número pode consumir a capacidade de todos. Se a falta de entrega começou no meio de uma campanha grande, compare o volume do dia com o limite atual no WhatsApp Manager.

Forma de pagamento. Pela página de preços, desde 1º/10/2026 cada número tem 1.000 mensagens de serviço gratuitas por mês. Sem forma de pagamento, a Meta deixa de entregar mensagens de serviço depois dessa franquia. Se as respostas do atendimento pararam de chegar no fim do mês, comece por aqui.

Um classificador simples no webhook

Este trecho em Node.js separa os casos para o seu time não precisar abrir JSON a cada reclamação. Ele grava o último status, trata o conflito delivered + failed e devolve uma ação:

// Ação por código de erro (tabela de códigos da Meta)
const ACAO = {
  131026: 'confirmar_por_outro_canal',
  131047: 'enviar_template',
  131049: 'reenviar_apos_24h',
  131050: 'opt_out_marketing',
  130472: 'nao_reenviar',
  131042: 'revisar_pagamento',
  131048: 'revisar_qualidade',
  131056: 'esperar_e_reenviar',
  131000: 'tentar_de_novo'
};

async function onStatus(st, db) {
  const msg = await db.findByWamid(st.id);
  if (!msg) return;

  if (st.status === 'failed') {
    // Se já houve delivered, a mensagem chegou em ao menos um aparelho
    if (msg.deliveredAt) return;
    const err = (st.errors || [])[0] || {};
    await db.update(st.id, {
      status: 'failed',
      errorCode: err.code,
      errorDetails: err.error_data?.details,
      action: ACAO[err.code] || 'revisar_manual'
    });
    return;
  }

  const patch = { status: st.status };
  if (st.status === 'delivered' || st.status === 'read') patch.deliveredAt = st.timestamp;
  await db.update(st.id, patch);
}

Complete com uma rotina diária que lista mensagens em sent há mais de 48 horas. Essas são as candidatas a “cliente offline ou bloqueio”, e a ação para elas é o contato por outro canal, não o reenvio.

Mensagem não entregue é cobrada?

Não. A página de preços da Meta diz que a empresa só é cobrada quando a mensagem é entregue. Mensagens em failed, ou paradas em sent, não geram cobrança. O experimento do 130472 também é explícito: a Meta não envia a mensagem e não cobra por ela.

Mesmo assim, falha tem custo indireto: muito 131026 indica base desatualizada, e muitas denúncias levam ao 131048.

Como diagnosticar com a Vectalk

A Vectalk é um proxy da Cloud API oficial, então os eventos de status chegam no seu webhook no mesmo formato da Meta, com os mesmos códigos desta tabela. Além do webhook, você pode consultar o histórico pela API:

curl --request GET \
  --url 'https://apis.vectalk.com.br/api/messages?status=failed&direction=outbound&from=2026-10-01&to=2026-10-29' \
  --header 'Authorization: Bearer SEU_TOKEN'

O endpoint Listar Mensagens aceita os filtros status (sent, delivered, read, failed, pending), direction, período e messageId (o wamid), útil para investigar uma reclamação específica. Na Vectalk, só mensagens entregues são descontadas do saldo pré-pago, e a cobrança da Meta passa pela linha de crédito da Vectalk, sem cartão seu cadastrado na Meta. Para começar, crie a conta em apps.vectalk.com.br/register. O panorama da plataforma está no guia da API oficial do WhatsApp.

Perguntas frequentes

Por que minha mensagem fica só em “sent”?

Porque ela saiu dos servidores da Meta mas não chegou ao aparelho. As causas mais comuns, segundo a Meta, são cliente que não ficou online nos 30 dias em que a mensagem é retida, bloqueio do número da empresa e país restrito ou sancionado.

Recebi “delivered” e “failed” para a mesma mensagem. Qual vale?

O delivered. A Meta explica que isso acontece quando o cliente usa o WhatsApp em vários aparelhos e a mensagem chega a um deles e falha em outro. Delivered significa que chegou a pelo menos um aparelho.

A API avisa quando o cliente me bloqueou?

A documentação de suporte cita o bloqueio como causa de mensagem enviada e não entregue, e diz que a Meta muitas vezes não revela a causa. Não conte com um código específico para isso: trate sent prolongado como sinal e confirme por outro canal.

Pago por mensagem que não foi entregue?

Não. A Meta só cobra mensagens entregues. Uma mensagem em failed ou parada em sent não é cobrada.

Devo reenviar automaticamente quando dá erro?

Só para erros temporários, como 131000 e 131056, e com espera entre as tentativas. Para 131026, 131050 e 130472, reenviar não resolve. Para 131049, espere pelo menos 24 horas.

---

Fontes oficiais consultadas em 29/10/2026: Códigos de erro da WhatsApp Cloud API, Suporte da WhatsApp Cloud API, Referência do webhook de status, Experimentos, Limites de mensagens, Preços, Listar Mensagens na documentação da Vectalk.