Bloquear um usuário na WhatsApp Business API: a regra das 24 horas que ninguém menciona

Semana passada colocamos no ar um recurso de bloquear/desbloquear na nossa integração com o Bitrix24, testamos com um número aleatório e vimos tudo "dar certo" — HTTP 200, nenhum erro, tudo verde. Só que o número nunca apareceu na lista de bloqueio.

Aquela tarde nos ensinou mais sobre o comportamento de bloqueio da WhatsApp Business API do que a documentação, então aqui vai tudo em um lugar só — incluindo a regra que explica a maioria das reclamações de "o bloqueio não funciona".

Antes de tudo, vamos falar do mesmo problema

Os resultados de busca sobre esse tema são uma bagunça porque dois problemas bem diferentes usam as mesmas palavras:

• Você quer bloquear um usuário — um spammer ou um contato abusivo escrevendo para a sua empresa. É disso que este artigo trata.
• O WhatsApp bloqueou a sua conta — seu número foi banido ou restringido. Problema completamente diferente (violações de política, notas de qualidade, ferramentas não oficiais), e nada do que vem a seguir vai ajudar.

A API em si é simples

A Cloud API expõe uma lista de bloqueio por número de telefone comercial. Três operações, um endpoint:

• POST /{phone-number-id}/block_users — bloqueia um ou mais números
• DELETE no mesmo caminho — desbloqueia
• GET no mesmo caminho — lista quem está bloqueado no momento

O payload é só messaging_product: "whatsapp" mais um array de usuários. Uma vez bloqueado, as mensagens do usuário simplesmente nunca chegam até você — nenhum webhook dispara, nada cai na sua caixa de entrada ou no CRM. Do lado dele, a entrega para discretamente em um tique cinza.

Até aqui, nenhuma surpresa. Agora as partes que mordem de verdade.

Regra 1: você só pode bloquear quem mandou mensagem nas últimas 24 horas

Esta é a grande regra, direto da documentação da Meta, mas raramente exposta pelas ferramentas:

Você só pode bloquear usuários que mandaram mensagem para a sua empresa nas últimas 24 horas.

Não dá para bloquear preventivamente um número que nunca escreveu para você. Não dá para bloquear alguém cujo spam chegou três dias atrás. A janela é a mesma janela de 24 horas de atendimento que rege as respostas de formato livre — o bloqueio é tratado como parte de uma conversa ativa, não como um firewall no nível da conta.

Na prática, isso significa que o bloqueio funciona exatamente quando você mais precisa (um spammer em plena rajada) e se recusa a funcionar quando você está fazendo faxina ("deixa eu bloquear todo mundo que mandou spam mês passado" — não).

Regra 2: uma resposta 200 não significa que alguém foi bloqueado

Eis a resposta que nos enganou. Os pedidos de bloqueio são por número: a chamada à API pode ter sucesso no geral enquanto cada número dentro dela é recusado. As recusas vêm dentro da resposta 200:

{
  "messaging_product": "whatsapp",
  "block_users": {
    "added_users": [],
    "failed_users": [
      {
        "input": "40740000000",
        "errors": [
          { "message": "...", "code": ... }
        ]
      }
    ]
  }
}

Se o número que você tentou bloquear não mandou mensagem nas últimas 24 horas, ele cai em failed_users — e se a sua integração só olha o status HTTP, ela vai alegremente reportar sucesso sem bloquear nada. Foi exatamente esse o bug que pegamos na nossa primeira versão e, a julgar pelos fóruns, não fomos os primeiros.

Se você está construindo em cima dessa API: trate failed_users como o resultado de verdade e mostre o motivo para o humano que clicou em "bloquear".

Os outros limites, rapidinho

• Máximo de 1.000 números por requisição, e a lista em si tem teto de 64.000 usuários bloqueados por número de telefone. Generoso, mas não infinito para alvos de spam em alto volume.
• Não dá para bloquear outra conta comercial — a API só bloqueia usuários comuns.
• O bloqueio é por número de telefone, não por WABA. Bloqueou um spammer no número de vendas? Ele ainda pode escrever para o número do suporte.
• A Meta está estendendo o endpoint para aceitar os novos IDs de usuário por empresa junto com os números de telefone — parte do lançamento dos nomes de usuário, em que você pode nem ter o telefone do spammer. Valem as mesmas regras.

Um efeito colateral que vale lembrar

Um usuário bloqueado produz silêncio absoluto — nenhum webhook, nenhum evento, nada. Hoje conferimos a lista de bloqueio como etapa padrão sempre que aparece no suporte um "as mensagens deste cliente pararam de chegar", porque um bloqueio esquecido há meses é indistinguível de uma integração quebrada. Um único GET resolve a dúvida.

Bloqueando de dentro do Bitrix24

Se o seu WhatsApp roda pelo WASync, a lista de bloqueio mora na própria conexão: um painel Bloqueados onde você vê todos os números bloqueados, adiciona um novo ou desbloqueia. Duas decisões de design saíram diretamente das falhas descritas acima:

1. Quando a Meta recusa um bloqueio, mostramos o motivo real — incluindo uma nota em linguagem simples sobre a regra das 24 horas — em vez de um checkmark verde de mentira.
2. A lista é sempre lida ao vivo da Meta, então o que você vê é o que está realmente valendo, não uma cópia em cache.

Spam no WhatsApp já é irritante o suficiente sem as suas ferramentas mentindo sobre o bloqueio ter funcionado ou não.

Atende pelo WhatsApp via Linhas Abertas do Bitrix24? Vale conferir também nosso checklist de solução de problemas para mensagens que não aparecem — bloqueios silenciosos são uma das sete causas da lista.