Mensagem da API do WhatsApp não entregue: as causas, por ordem
Uma mensagem aceite pela API do WhatsApp não é uma mensagem entregue: a Meta comunica o resultado mais tarde, num webhook de estado, como enviada, entregue, lida ou falhada, com um código de erro. Verifique por ordem: o estado falhado e o respetivo código, a janela de 24 horas (131047), o método de pagamento (131042), o template (132001, 132015), o destinatário (131026, 131049, 131050) e, por fim, os limites e a ligação do número.
A easyCoexistence vigia cada número ligado 24 horas por dia, envia-lhe um e-mail quando a Meta deixa de entregar, a ligação cai ou a qualidade baixa, e reencaminha os webhooks de estado da Meta sem alterações para o seu sistema.
enviada (um visto), entregue (dois), lida (dois azuis) e falhada (um triângulo vermelho de erro), tal como os webhooks de estado as comunicam.
Passaram mais de 24 horas desde a última resposta do destinatário; a Meta recomenda enviar um template em seu lugar.
Não foi possível entregar: o número não está no WhatsApp, o destinatário não aceitou os novos termos ou usa uma versão antiga do WhatsApp.
Tempo predefinido durante o qual o WhatsApp repete a entrega de um template de utilidade ou de marketing não entregue, antes de o descartar; os templates de autenticação têm 10 minutos por predefinição.
Throughput fixo de um número usado tanto na app do WhatsApp Business como na Cloud API.
Porque é que uma mensagem aceite ainda não chega?
Porque a resposta da API e a entrega são dois eventos separados. Ao enviar, a Meta devolve um id de mensagem assim que aceita o pedido; se a mensagem chega ao telemóvel do cliente, fica para depois, num webhook de estado no campo messages. enviada significa que saiu dos servidores da Meta (um visto), entregue que chegou ao dispositivo (dois), lida que foi aberta (dois azuis), e falhada que não pôde ser enviada ou entregue, apresentada com um array errors: code, title e error_data.details. Por isso, o primeiro passo nunca é adivinhar: procure o estado falhado para esse id de mensagem e leia o seu código. Se não tiver um destino de webhook, nada o regista.
Quais são as causas, pela ordem de verificação?
Das mais comuns num número recém-ligado às mais raras. Cada linha indica o código da Meta, para que o estado falhado lhe diga em qual delas se encontra:
- Janela fechada: 131047, mais de 24 horas desde a última mensagem do cliente. As mensagens em texto livre precisam de uma janela aberta; envie um template.
- Pagamento: 131042, ou templates descartados em silêncio. Desde 1 de outubro de 2026, as mensagens de serviço também param após 1,000 mensagens por mês sem método de pagamento.
- Template: 132001 não aprovado ou idioma errado, 132000 número errado de variáveis, 132012 formato errado, 132015 pausado, 132016 desativado.
- Destinatário: 131026 não está no WhatsApp, versão antiga ou termos não aceites; 131050 parou as mensagens de marketing; 131049 retidas para manter um bom envolvimento; os templates de marketing para números dos Estados Unidos não são entregues.
- Limites: 131048 restringido após sinais de spam, 131056 demasiadas mensagens para uma mesma pessoa, 130429 throughput, 20 mensagens por segundo num número em Coexistence.
- Conta: 131031 ou 368, a WhatsApp Business Account restringida ou desativada por violação de uma política.
- Ligação: o número já não está associado, por exemplo após 14 dias sem abrir a app do WhatsApp Business.
Como lidar com os códigos do lado do destinatário?
De forma diferente, porque alguns merecem nova tentativa e outros nunca. O 131050 significa que a pessoa escolheu deixar de receber mensagens de marketing da sua parte: a Meta diz para não repetir, e o webhook user_preferences avisa quando param ou retomam. O 131049 é a Meta a reter uma mensagem de marketing para manter o envolvimento saudável, muitas vezes um limite por utilizador em templates de marketing: a Meta aconselha a esperar pelo menos 24 horas antes de reenviar, pois reenviar mais cedo devolve apenas o mesmo erro. O 131026 abrange números que não estão no WhatsApp, utilizadores que não aceitaram os termos atuais do WhatsApp e versões muito antigas da app; verifique primeiro o formato do número e o indicativo do país, depois peça ao cliente por outro canal.
Durante quanto tempo o WhatsApp continua a tentar entregar?
Durante o tempo de vida (TTL) da mensagem. Quando um telemóvel está desligado ou sem cobertura, o WhatsApp volta a tentar a entrega em vez de falhar logo: por defeito durante 30 dias em templates de utilidade e de marketing e 10 minutos em templates de autenticação. Uma empresa pode encurtá-lo por template com message_send_ttl_seconds, de 30 segundos a 12 horas para utilidade e de 30 segundos a 15 minutos para autenticação. Uma mensagem que não puder ser entregue dentro do seu TTL é descartada. Assim, uma mensagem com estado enviada e sem estado entregue passadas horas está normalmente à espera do telemóvel do cliente, não perdida; defina um TTL curto para códigos e alertas urgentes, para que uma entrega tardia nunca confunda ninguém.
O que isto significa para respostas de IA e automações?
Leia primeiro a execução e depois o estado. No separador Runs, uma execução Skipped não enviou nada e diz porquê: "Mais de 24 horas desde a última mensagem do cliente", "Respondeu a esta conversa há pouco no telemóvel" ou "Limite de respostas de IA para esta conversa atingido nesta hora". Uma execução Done significa que a Meta aceitou todas as respostas, o que não prova a entrega. A easyCoexistence não guarda os estados das mensagens: com automações ativas, chegam ao URL de reencaminhamento se o definir, e no modo direto vão diretamente para o seu próprio endpoint. A partir do ChatGPT ou do Claude, peça à sua IA para executar get_number_health: devolve o estado em tempo real, a classificação de qualidade e os últimos 15 eventos de monitorização, incluindo um bloco de envio com o código da Meta.
Como configurar
- Find the statusLook up the message id in your webhook log and read the latest status: delivered, read, sent only, or failed with an error code.
- Match the codeLook up the failed status's code in the list of causes above and in Meta's error codes reference.
- Check the accountConfirm the WhatsApp Business Account has a default payment method, a currency and a time zone in Billing & payments.
- Check the templateIf it was a template, confirm it is APPROVED in that language and the variables match its definition.
- Check the numberAsk your AI to run get_number_health, or open the number in the dashboard, to see the connection and any sending block.
Erros comuns
- Repetir após um 131050. A pessoa deixou de receber mensagens de marketing da sua parte; mais tentativas nunca são entregues e só podem acrescentar sinais negativos.
- Dar uma mensagem como entregue só pelo id. A Meta aceita primeiro e comunica as falhas mais tarde, por isso um fluxo que para no id deixa passar todas as mensagens recusadas.
- Enviar uma resposta em texto livre um dia depois. Após 24 horas sem mensagem do cliente, só é aceite um template.
- Funcionar sem destino de webhook. Os estados de falha chegam apenas por webhook; sem um, o motivo pelo qual uma mensagem não chegou perde-se.
A sua IA pode verificar um número a partir do ChatGPT ou do Claude com get_number_health. De US$ 9 a US$ 0.75 por número por mês, descendo à medida que adiciona números, com os primeiros 3 dias gratuitos.
Perguntas frequentes
Porque é que a mensagem mostra um visto durante horas?
Um visto é o estado enviada: a Meta enviou-a, mas o telemóvel ainda não a recebeu, normalmente porque está desligado ou sem ligação. O WhatsApp continua a tentar até o tempo de vida do template acabar, 30 dias por defeito para utilidade e marketing.
Porque é que as respostas chegam mas os templates não?
Normalmente é um problema de método de pagamento na WhatsApp Business Account. A Meta entrega mensagens de serviço dentro do escalão gratuito mensal do número sem um, mas não entrega templates. Adicione um cartão em Faturação e pagamentos.
Consigo ver mensagens falhadas na app do WhatsApp Business?
Não de forma fiável. Num número em Coexistence, as mensagens enviadas pela API aparecem na conversa da app, mas o motivo da falha só aparece no código de erro do webhook de estado.
A Meta cobra por mensagens que não foram entregues?
Não. A Meta cobra apenas por mensagens entregues, e as tentativas com um template pausado também não são cobradas.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em