Pular para o conteúdo
apiwpp

Como evitar o bloqueio do número ao enviar mensagens pela API

O que faz o WhatsApp restringir um número e as regras de envio que reduzem o risco: aquecimento, ritmo da fila e limite de contatos novos.

Equipe apiwpp · 12 min de leitura · Atualizado em

APIs que usam o protocolo do WhatsApp Web funcionam com um número comum. Isso dá liberdade para enviar sem aprovação de templates, mas o número continua sujeito às mesmas regras antispam de qualquer usuário. Quem trata a API como disparador em massa costuma perder o número em pouco tempo; quem envia no ritmo de uma pessoa, para quem espera a mensagem, corre um risco muito menor.

A boa notícia é que os sinais que levam a uma restrição são conhecidos e quase todos dependem de como você envia, não de onde. Este guia reúne o que faz o WhatsApp desconfiar de um número, as regras que a fila da apiwpp aplica por padrão e o que fazer se, mesmo assim, algo der errado.

Uma ressalva honesta antes de começar: nenhuma ferramenta garante que um número nunca será restringido. O WhatsApp decide sozinho. O que dá para fazer é reduzir muito o risco, e é disso que tratam as próximas seções.

Por que números são bloqueados

Os sinais que mais pesam são volume alto logo após a conexão, muitas mensagens para quem nunca falou com o número e denúncias de spam. Um número recém-conectado que envia centenas de mensagens idênticas para desconhecidos reúne os três.

Na prática, o WhatsApp olha para o comportamento do número como um todo:

  • Idade da conexão. Um aparelho recém-conectado que já começa enviando muito parece automação, e é tratado com mais desconfiança.
  • Proporção de conversas novas. Responder quem escreveu para você é o uso normal do aplicativo. Iniciar dezenas de conversas por hora com números que nunca trocaram mensagem com você não é.
  • Reação de quem recebe. Cada denúncia, bloqueio ou conversa apagada sem resposta conta contra o número. Uma lista comprada ou antiga gera muitas dessas reações de uma vez.
  • Ritmo mecânico. Mensagens saindo em intervalos idênticos, sem pausa, 24 horas por dia, não se parecem com uma pessoa usando o celular.

Nada disso é exclusivo das APIs não oficiais: o mesmo número, operado à mão com o mesmo comportamento, teria o mesmo destino. A diferença é que uma integração mal escrita consegue repetir o erro milhares de vezes em poucos minutos.

Aqueça o número novo

Nos primeiros 14 dias depois de conectar, comece com poucas mensagens por hora e aumente aos poucos. Na apiwpp esse aquecimento é automático: a fila aplica limites menores no início e libera mais envios conforme o número amadurece.

Os limites padrão de cada etapa, contados a partir do pareamento, são estes:

Desde o pareamentoPor horaPor diaDestinatários novos em 24 h
Até 6 horas5205
De 6 a 24 horas105010
De 1 a 3 dias2010020
De 3 a 7 dias3015030
De 7 a 14 dias4520050
Limite de envios por dia durante os 14 dias de aquecimento.

Duas regras importam aqui. Primeiro, nenhuma etapa passa dos limites normais da fila: o aquecimento só aperta, nunca afrouxa. Segundo, parear o número de novo (depois de um logout, por exemplo) recomeça o aquecimento do zero, e as contagens por minuto, hora e dia também voltam a zero. Evite trocar de aparelho conectado sem necessidade. Se o termo é novo para você, o glossário resume o conceito em poucas linhas.

Nesses primeiros dias, dê prioridade a quem já conversa com o número: clientes que pediram atendimento, respostas a mensagens recebidas, avisos para quem acabou de comprar. O detalhe de cada etapa está no guia de aquecimento de número.

Cuidado com contatos novos

Responder quem escreveu para você é seguro. Iniciar conversa com quem nunca falou com o número é o que mais gera denúncia. Por isso a API limita quantos destinatários novos cada número alcança em 24 horas e responde 429 quando o teto é atingido:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": "new_recipient_cap_reached",
  "message": "…"
}

O cabeçalho Retry-After traz os segundos até abrir uma vaga ou, durante o aquecimento, até a próxima etapa aumentar o limite, o que vier antes (o valor acima é só um exemplo). Nada é colocado na fila quando o teto é atingido, então o seu sistema decide o que fazer: agendar para mais tarde, avisar a equipe ou escolher outro canal.

Em Node.js, tratar esse caso leva poucas linhas. O exemplo usa o fetch nativo e devolve o tempo de espera para o seu agendador:

type Envio = { to: string; message: string; clientRef: string }

export async function enviar(connectionId: string, envio: Envio) {
  const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/send`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.APIWPP_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(envio),
  })

  if (res.status === 429) {
    const body = await res.json()
    const esperarSegundos = Number(res.headers.get('Retry-After') ?? '60')
    // new_recipient_cap_reached: nada foi enfileirado; reagende, não insista
    return { status: 'reagendar' as const, motivo: body.error, esperarSegundos }
  }

  if (!res.ok) throw new Error(`Envio recusado: ${res.status}`)

  // 202 (novo job) ou 200 com duplicate: true (mesmo clientRef)
  return { status: 'na-fila' as const, job: await res.json() }
}

Decida pelo status HTTP e pelo campo error, nunca pelo texto de message, que é escrito para pessoas e pode mudar. A página de integração com Node.js mostra o mesmo envio com o webhook ao lado.

Alguns detalhes que evitam surpresas:

  • O que conta como novo. É conhecido quem trocou mensagem com o número nos últimos 28 dias e depois do pareamento atual: escreveu para ele ou recebeu mensagem dele, pela API ou digitada no celular. Qualquer outro é novo. Contatos conhecidos nunca são barrados por esse teto, e grupos não contam.
  • O padrão é de 100 por 24 horas. Durante o aquecimento, o teto é menor e segue a tabela da seção anterior. Cada destinatário novo conta uma vez a cada 24 horas, e o campo usage.newRecipients de GET /connections/{id}/queue mostra quantos o número já alcançou.
  • Verifique antes de enviar. Enviar para quem não tem WhatsApp falha na hora com not_on_whatsapp. Limpar a base antes evita tentativas inúteis, e a verificação de números faz isso em lotes.

A verificação usa a rota POST /connections/{id}/contacts/check, com até 100 números por chamada e a conexão aberta:

curl -X POST https://api.apiwpp.com/connections/$ID/contacts/check \
  -H "Authorization: Bearer $APIWPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones":["5511988887777","5511955550000"]}'
{
  "results": [
    { "phone": "5511988887777", "exists": true, "jid": "[email protected]" },
    { "phone": "5511955550000", "exists": false }
  ]
}

Marque no seu cadastro quem voltou com exists: false e não tente de novo a cada campanha.

A apiwpp também resolve o nono dígito sozinha: antes de cada envio, pergunta ao WhatsApp em qual endereço o número está registrado. Você informa o campo to só com dígitos, com país e DDD, e não precisa montar o endereço à mão. O motivo está explicado no guia sobre o nono dígito.

Deixe a fila ditar o ritmo

Não tente contornar a fila com vários números em paralelo para o mesmo público. Envie com um clientRef, acompanhe o horário previsto na resposta e trate o evento message.send_failed quando um envio não puder acontecer. A fila é o rate limit que protege o número, não um obstáculo a vencer.

Cada número tem a própria fila com ritmo anti-bloqueio. Os valores padrão são:

  • 3 mensagens por minuto, 60 por hora e 200 por dia por número;
  • um intervalo aleatório de 3 a 8 segundos entre dois envios;
  • pelo menos 30 segundos entre duas mensagens para o mesmo destinatário.

A chamada de envio não espera a mensagem sair. Ela coloca o envio na fila e responde 202 na hora, com a posição e o horário previsto:

curl -X POST https://api.apiwpp.com/connections/$ID/send \
  -H "Authorization: Bearer $APIWPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511988887777","message":"Olá, Ana! Seu pedido 1234 saiu para entrega.","clientRef":"pedido-1234-envio"}'
{
  "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f",
  "scheduledAt": 1790251205000,
  "position": 2
}

O scheduledAt é o horário previsto do envio, em milissegundos desde 1970 (unix), e position é o lugar na fila. Se a position cresce sem parar, o seu sistema está pedindo mais do que o número deve enviar: é hora de espaçar os avisos, não de procurar um atalho.

O clientRef é a sua garantia contra duplicidade: se a requisição cair por tempo esgotado e o seu sistema repetir, a API devolve o envio original com "duplicate": true em vez de mandar a mensagem duas vezes. Mandar a mesma mensagem duas vezes para a mesma pessoa é um jeito rápido de ganhar uma denúncia. O assunto tem um guia próprio sobre mensagens duplicadas.

A fila de um número: envios espaçados, uso por minuto, hora e dia, e o contador de destinatários novos.

Para acompanhar o estado do número, a rota GET /connections/{id}/queue mostra quantos envios aguardam, os limites em vigor (limits), o uso atual (usage) e a etapa do aquecimento (warmup). Um envio que ainda não saiu pode ser cancelado com DELETE /connections/{id}/queue/{jobId}, útil quando um lote foi disparado por engano.

Antes de cada texto, a apiwpp ainda mostra "digitando…" por um instante, como faria uma pessoa. O padrão é de 1,5 segundo, e o campo typingDelay (em milissegundos) muda esse tempo por envio:

{ "to": "5511988887777", "message": "Seu pedido saiu para entrega.", "typingDelay": 3000 }

O que você envia também conta

O ritmo certo não salva uma mensagem que ninguém quer receber. Algumas práticas simples fazem mais diferença do que qualquer limite:

  1. Envie para quem pediu. Clientes que deixaram o número num cadastro, numa compra ou num atendimento esperam ouvir de você. Listas compradas ou raspadas geram denúncias em série.
  2. Diga quem está falando. A primeira mensagem de uma conversa deve deixar claro o nome da empresa e o motivo do contato.
  3. Varie o conteúdo. Use templates com variáveis, como {{nome}} e {{pedido}}, para que cada mensagem seja de fato daquela pessoa, e não um texto idêntico repetido centenas de vezes.
  4. Ofereça uma saída. Uma linha como "responda SAIR para não receber mais avisos" custa pouco e evita que a pessoa use o botão de denúncia. Respeite o pedido no seu sistema.
  5. Respeite o horário. Mensagens de madrugada irritam e geram bloqueios. Agende avisos não urgentes para o horário comercial.

Se o seu caso é campanha de marketing em grande volume para quem não é cliente, a API não oficial não é o caminho. O guia sobre disparo em massa explica por quê e quais alternativas existem.

O que fazer quando algo dá errado

Às vezes o WhatsApp recusa mensagens para contatos que nunca falaram com o número (o erro 463) e, se a conta insiste, aplica um bloqueio temporário de novas conversas, o reach-out timelock. Esse bloqueio costuma ser um aviso que precede restrições mais sérias, então vale tratá-lo como alarme.

A apiwpp detecta o bloqueio e avisa de três formas:

  • o envio recusado pelo WhatsApp chega em message.delivery com o status failed e o motivo reachout_timelocked;
  • o evento connection.status chega com o motivo reachout_timelock e o fim previsto em reachoutTimelock.endsAt;
  • enquanto o bloqueio durar, a fila recusa os envios sem tentá-los, porque cada tentativa aprofundaria a restrição, e cada envio com clientRef gera message.send_failed com o motivo reachout_timelocked.

O evento que chega no seu webhook tem este formato:

{
  "type": "connection.status",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "loja-centro",
  "timestamp": "2026-09-24T15:10:00.000Z",
  "data": {
    "status": "open",
    "phoneNumber": "5511977776666",
    "reason": "reachout_timelock",
    "reachoutTimelock": { "active": true, "endsAt": "2026-09-25T12:00:00.000Z", "enforcementType": "BIZ_QUALITY" }
  }
}

Repare que a conexão continua open: o número ainda recebe e responde mensagens, só não pode iniciar conversas. Quando o WhatsApp suspende o bloqueio antes do prazo, chega outro connection.status com reachout_timelock_lifted. O endsAt pode vir null quando o WhatsApp não informa um fim.

Nessa hora:

  • Pare de iniciar conversas. Continue respondendo quem escreve, mas suspenda avisos para contatos novos.
  • Revise o que saiu nas últimas horas. Um lote para uma lista antiga ou um erro que repetiu mensagens costumam explicar o problema.
  • Reenvie só depois do prazo. Passado o endsAt, reenvie o que era importante com um clientRef novo: o antigo já foi usado por um envio que falhou.
  • Não reconecte o número por impulso. Parear de novo recomeça o aquecimento e zera a lista de contatos conhecidos, o que deixa o número mais limitado, não menos.

Se a sessão cair de vez, o connection.status chega com status: close, o motivo logged_out e willReconnect: false: a sessão acabou do lado do WhatsApp (aparelho removido no celular ou um bloqueio da conta). Aí não há o que reconectar sem um QR code novo, e o número recomeça como recém-conectado.

Guarde também os eventos connection.status no seu sistema. Eles contam a história do número e ajudam a entender o que aconteceu antes de uma restrição.

Resumo

  • Aqueça números novos por 14 dias.
  • Priorize conversas com quem já falou com o número.
  • Respeite a fila e os limites de novos destinatários.
  • Use clientRef em todo envio para nunca duplicar uma mensagem.
  • Ofereça sempre uma forma de o contato parar de receber mensagens.

Como começar hoje

  1. Liste de onde vêm os números para os quais você envia e separe quem nunca falou com você.
  2. Troque os textos fixos por templates com variáveis e inclua uma opção de saída.
  3. Passe a base por contacts/check e marque quem não tem WhatsApp.
  4. Gere um clientRef estável para cada envio, como o id do pedido somado ao tipo do aviso.
  5. Trate a resposta 429 e o evento message.send_failed no seu sistema, em vez de repetir o envio na força.
  6. Assine os eventos connection.status e alerte a equipe quando chegar reachout_timelock.
  7. Crie sua conta na apiwpp e conecte o primeiro número: são 7 dias de teste com os recursos do PRO (exceto IP dedicado). Os preços por número estão em preços.

Perguntas frequentes

A apiwpp garante que meu número não será bloqueado?

Não. Nenhuma ferramenta que usa o protocolo do WhatsApp Web pode garantir isso, porque quem decide é o WhatsApp. A fila, o aquecimento e o teto de destinatários novos reduzem bastante o risco, desde que o conteúdo também seja algo que as pessoas querem receber.

Quantas mensagens posso enviar por dia?

O padrão é de até 200 mensagens por dia por número, com no máximo 60 por hora e 3 por minuto, depois do aquecimento. Nos primeiros 14 dias os limites são menores e sobem por etapas. Não há cobrança por mensagem: o limite existe para proteger o número.

O que conta como destinatário novo?

É quem não trocou nenhuma mensagem com o número nos últimos 28 dias desde o pareamento atual. O padrão é de 100 destinatários novos a cada 24 horas. Quem já conversa com o número nunca é barrado por esse limite.

Usar vários números em paralelo evita o bloqueio?

Não. Dividir a mesma lista fria entre vários números só multiplica as denúncias e coloca todos eles em risco. Cada número tem a própria fila e o próprio aquecimento, e deve ser usado para conversar com quem espera aquele contato.

O que acontece se eu reconectar o número?

Parear o número de novo recomeça o aquecimento de 14 dias e zera a lista de contatos conhecidos. Reinícios e atualizações dos servidores não pedem novo QR code, porque a sessão fica salva e criptografada. Só reconecte quando for de fato necessário, como na troca do número.

Como sei que o WhatsApp restringiu meu número?

O evento connection.status chega no seu webhook com o motivo reachout_timelock e o fim previsto em reachoutTimelock.endsAt quando o WhatsApp bloqueia temporariamente novas conversas. Os envios com clientRef recusados nesse período geram message.send_failed. Se a sessão foi encerrada do lado do WhatsApp, o motivo é logged_out.


Leia também:

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.