Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

Porque é que uma mensagem do WhatsApp falhou: como ler o estado failed e os seus erros

Um webhook de estado failed significa que a Meta não conseguiu enviar nem entregar uma mensagem que a empresa enviou pela API. Chega ao campo messages com o estado failed e um array errors que contém code, title, message, error_data.details e href. O código indica o motivo: 131047 janela fechada, 131026 não entregável, 131049 limite de marketing, 131050 marketing interrompido, 131042 problema de pagamento.

A easyCoexistence liga o número da sua app WhatsApp Business à Cloud API da Meta através de Coexistence e passa os estados failed para o seu servidor, diretamente ou como reencaminhamentos assinados quando as automações estão ativas.

131047

Passaram mais de 24 horas desde a última resposta do destinatário; a solução da Meta é enviar um template em vez disso.

131049

Não entregue para manter saudável o envolvimento no ecossistema; espere pelo menos 24 horas antes de reenviar o template de marketing.

131050

O destinatário escolheu deixar de receber mensagens de marketing da empresa; a Meta indica que não se deve repetir.

No contacts

Um estado failed omite o array contacts, por isso correlacione a falha através de statuses.id.

Delivered

A Meta cobra pelas mensagens quando são entregues, não quando são enviadas.

Como é um estado failed?

Como qualquer estado, mais o array errors. O array contacts está em falta, recipient_user_id é omitido quando a mensagem foi enviada para um número de telefone, e não há objeto pricing. Title e message têm o mesmo texto, error_data.details explica-o numa frase, e href aponta para a lista de códigos de erro da Meta. Este é o exemplo da própria Meta, um template de marketing interrompido pelo limite por utilizador:

Meta's example: a message that failed with 131049
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
                "status": "failed",
                "timestamp": "1751142888",
                "recipient_id": "16505551234",
                "errors": [
                  {
                    "code": 131049,
                    "title": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "message": "This message was not delivered to maintain healthy ecosystem engagement.",
                    "error_data": {
                      "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
                    },
                    "href": "/documentation/business-messaging/whatsapp/support/error-codes"
                  }
                ]
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Que códigos de erro aparecem mais, e o que significam?

A Meta devolve erros na resposta de envio, num estado failed, ou em ambos, por isso o mesmo código pode chegar por qualquer dos caminhos, e a sua rotina de tratamento deve ler os dois locais. Estes são os códigos que explicam a maioria das mensagens que nunca chegam, com o motivo da própria Meta e a primeira coisa a tentar. A lista completa está na referência de códigos de erro da Meta:

131026Undeliverable: not a WhatsApp number, terms not accepted, or an outdated WhatsApp version on the recipient's phone.
131047More than 24 hours since the customer last wrote. Send an approved template instead.
131049Held back to keep engagement healthy, usually the per-user marketing limit. Wait 24 hours or more.
131050The customer stopped marketing messages from you. Do not retry.
131042A problem with the payment method on the WhatsApp Business Account.
130472Not sent because the recipient is part of Meta's marketing message experiment.
131053Media could not be uploaded, often an unsupported file type.
131000Unknown error. Try again; if it persists, open a Direct Support ticket.

Como deve uma rotina de tratamento reagir a cada tipo de falha?

Classifique o código em função do que fazer a seguir, antes de qualquer nova tentativa. Uma repetição generalizada transforma uma recusa de marketing em falhas repetidas e pode prolongar um bloqueio, enquanto descartar um erro temporário perde uma mensagem que teria sido entregue um minuto depois.

  • Repetir com backoff: 131000 desconhecido, 131016 serviço indisponível, 130429 throughput atingido.
  • Esperar primeiro: 131049, pelo menos 24 horas, porque as tentativas precoces podem bloquear esse utilizador até mais 24 horas.
  • Mudar a mensagem: 131047 exige um template aprovado, porque a janela de 24 horas está fechada.
  • Parar para este cliente: 131050, até chegar um resume de user_preferences.
  • Corrigir a conta ou o conteúdo: 131042 pagamento, 131031 conta restringida, 131053 multimédia.

Que falhas aparecem apenas como estado failed?

As que a Meta decide depois de aceitar o pedido. O envio devolve um wamid, e a recusa chega mais tarde neste webhook. A Meta não entrega templates de marketing a utilizadores do WhatsApp com números de telefone dos Estados Unidos (+1 com indicativo de área dos EUA). Um template de marketing enviado a um cliente que deixou de receber mensagens de marketing é processado e depois reportado como falhado com 131050, e o limite de marketing por utilizador reporta 131049 da mesma forma.

Se o número não tiver destino de webhook, estas falhas não ficam visíveis em lado nenhum e a mensagem simplesmente parece enviada. Para a ordem completa de verificações quando um cliente não recebeu nada, veja a página sobre mensagens da API do WhatsApp que não foram entregues.

O que muda num número em Coexistence?

Duas coisas importam. Primeiro, a janela de 24 horas aplica-se apenas à API. O guia de Coexistence da Meta diz que as mensagens enviadas a partir da app WhatsApp Business não estão sujeitas à janela de atendimento ao cliente. Por isso, depois de um 131047, o proprietário ainda pode responder a esse cliente a partir do telemóvel, enquanto o seu sistema envia um template aprovado.

Segundo, o throughput é fixo. Um número usado na app e na API ao mesmo tempo envia no máximo 20 mensagens por segundo, e ultrapassar esse valor devolve 130429. Tudo o resto se comporta como em qualquer número da Cloud API: o mesmo campo, o mesmo array errors, os mesmos códigos.

Como é que as automações e a sua IA veem uma falha?

Depende de quando a Meta diz não. Uma recusa no momento do envio, como 131047, falha o passo da automação: a execução mostra Failed com a mensagem da Meta no separador Runs, e o proprietário recebe um e-mail para poder responder ao cliente pessoalmente. As automações também verificam a janela antes de enviar uma resposta de texto livre e saltam com window_closed em vez de tentar.

Uma falha que a Meta reporta depois chega como estado failed ao seu URL de reencaminhamento ou destino direto, e a execução mantém-se como estava. Uma IA que enviou um template através do conector MCP vê o wamid e "sent: true". Peça ao seu sistema o estado desse wamid, ou peça ao assistente para executar get_number_health quando muitas mensagens falham ao mesmo tempo.

Erros comuns

  • Repetir 131050 em ciclo. O cliente deixou de receber mensagens de marketing, por isso cada tentativa falha da mesma forma até ele voltar a aceitá-las.
  • Reenviar um template de marketing 131049 em poucas horas. A Meta pede pelo menos 24 horas, e as tentativas precoces podem bloquear esse utilizador até mais 24 horas.
  • Registar apenas o title. error_data.details contém o motivo específico, por isso guarde o código e os detalhes em conjunto com o wamid.
  • Correr sem destino de webhook e julgar a entrega pela resposta de envio, que só diz que a Meta aceitou a mensagem.
Fazer isto com a EasyCoexistence

Quando a resposta de uma automação é recusada no momento do envio, a execução mostra o erro da Meta e é enviado um e-mail, e cada número é monitorizado 24/7 quanto a desligamentos e quedas de qualidade. De US$ 9 a US$ 0.75 por número e por mês, a descer à medida que acrescenta números, com os primeiros 3 dias gratuitos.

Perguntas frequentes

A Meta cobra uma mensagem falhada?

A Meta indica nas páginas de preços que cobra pelas mensagens entregues, não pelas que são apenas enviadas. Um estado failed não traz objeto de pricing. As cobranças vão para a conta WhatsApp Business da própria empresa; a easyCoexistence nunca aplica qualquer margem.

O 131026 quer dizer que o cliente bloqueou a empresa?

A lista da Meta para o 131026 aponta outros motivos: o número não está no WhatsApp, o destinatário não aceitou os termos mais recentes, ou a versão do WhatsApp é demasiado antiga. A Meta sugere pedir ao cliente, por outro canal, que verifique esses pontos.

Porque é que recipient_user_id aparece em algumas falhas e noutras não?

A Meta omite-o num estado failed quando a mensagem foi enviada para um número de telefone. Quando enviou para o BSUID do cliente, a falha inclui-o, e pode faltar recipient_id.

Pode uma mensagem falhar depois de entregue?

A referência da Meta descreve failed como falha ao enviar ou entregar. Quando a mensagem chega ao dispositivo, os próximos estados que pode esperar são read, ou played no caso de mensagens de voz.

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 gratuito

Verificado em