← Voltar ao Blog
novidades byon diagnostico whatsapp-cloud-api troubleshooting

A Meta Retornou 200, Mas a Mensagem Nunca Chegou: Diagnóstico de Números no PipesBot

Read in English →

Resumo: um 200 OK com wamid da WhatsApp Cloud API quer dizer “aceito”, não “entregue”. Se o número, a WABA ou a empresa por trás dele estiver bloqueado, a Meta aceita o envio do mesmo jeito e só avisa da falha depois, se você estiver ouvindo. O botão Check Health dos números BYON agora virou Diagnostics: ele pergunta à Meta o que está bloqueando cada parte da cadeia, mostra a correção sugerida e permite enviar uma mensagem de teste para ver a resposta crua da Meta. Os mesmos dados estão disponíveis em GET /v1/pool-numbers/:id/health.

O chamado que começou tudo

Um cliente escreveu: “Recebo mensagens normalmente. Meu bot responde. A API retorna sucesso. Ninguém recebe nada.”

Do nosso lado estava tudo saudável. O token de acesso era válido, os webhooks chegavam e todo envio voltava com um id de mensagem. A causa estava um nível acima: a WABA tinha sido bloqueada porque o método de pagamento falhou (erro 141006 da Meta). Desde 1º de outubro, service messages são cobradas depois da faixa grátis, então um cartão ausente ou recusado agora interrompe a entrega.

A Meta não recusou os envios. Ela aceitou, e um pouco depois mandou um webhook de status failed. Se a sua integração ignora status (e Apps legacy nunca recebiam status), as mensagens simplesmente somem.

Nosso health check antigo só testava se o token funcionava, então dizia “active”. Estava certo sobre o token e não ajudava em nada nesse problema.

O que o Diagnóstico verifica

A Meta expõe um health_status em cada número que cobre cada entidade da cadeia: o número, a WABA, o portfólio de negócio e o app. Para cada uma, a Meta diz se ela pode enviar mensagens (AVAILABLE, LIMITED ou BLOCKED), quais erros estão bloqueando e o que fazer.

Abra a aba Numbers do seu App e clique em Diagnostics num número BYON. O diálogo mostra:

  • O veredito: esse número consegue enviar mensagens agora?
  • Um selo por entidade, com os erros que bloqueiam, a correção sugerida pela Meta e informações extras, como um nome de exibição ainda aguardando aprovação.
  • Detalhes do número: status da conexão, status do nome, plataforma, quality rating e tier de limite de mensagens.
  • Um envio de teste: escolha um template ou um texto, envie para um número seu e veja o status HTTP e o corpo exatos que a Meta devolveu.

Erros de chamadas de voz (a faixa 138xxx) aparecem na mesma lista da Meta, mas não afetam mensagens, então marcamos esses separadamente. Um número com problema de SIP pode enviar mensagens normalmente.

Rodar o Diagnóstico também atualiza a saúde do token do número: ele vira unhealthy quando a Meta recusa o token e volta para active depois de uma checagem bem-sucedida.

Os mesmos dados pela API

Se você opera uma plataforma em cima do PipesBot, seus clientes vão perguntar “por que minhas mensagens não estão saindo?”. Agora você responde pelo seu próprio painel:

curl https://api.pipes.bot/v1/pool-numbers/pn_abc123/health \
  -H "Authorization: Bearer ak_your_app_key"
{
  "checkedAt": "2026-10-25T13:02:11.000Z",
  "canSendMessage": "BLOCKED",
  "entities": [
    { "type": "PHONE_NUMBER", "id": "1098765432", "canSendMessage": "AVAILABLE", "errors": [], "additionalInfo": [] },
    {
      "type": "WABA",
      "id": "2233445566",
      "canSendMessage": "BLOCKED",
      "errors": [
        {
          "code": 141006,
          "description": "There is an error with the payment method. This will block business initiated conversations.",
          "solution": "There was an error with your payment method. Please add a new payment method to the account.",
          "area": "messaging"
        }
      ],
      "additionalInfo": []
    }
  ],
  "phone": { "displayPhoneNumber": "+55 11 98765-4321", "status": "CONNECTED", "qualityRating": "GREEN", "messagingLimitTier": "TIER_250" },
  "error": null
}

O endpoint usa uma chave de App (ak_) e funciona mesmo quando o número está meio quebrado, que é exatamente quando você precisa dele. Se não for possível consultar a Meta (token expirado, id errado), canSendMessage vem null e error explica o motivo, com tokenInvalid marcado quando o problema é o token.

Hábitos que valem a pena

O Diagnóstico explica por que um número está bloqueado. Estes hábitos ajudam você a perceber mais cedo:

  • Leia os status failed. Na API v2, os status chegam no seu webhook. Um pico de failed é o seu primeiro alerta.
  • Mantenha um método de pagamento válido na WABA. Um método com falha bloqueia as conversas iniciadas pela empresa (é o que diz o 141006), e as service messages param quando o número passa das 1.000 grátis do mês.
  • Verifique antes de culpar o bot. Quando um cliente disser “o bot parou de responder”, rode o Diagnóstico primeiro. Leva poucos segundos e descarta uma categoria inteira de problemas que nenhuma mudança de código resolve.

O Diagnóstico já está no ar para todo número BYON no dashboard. A referência da API está em Number Management.