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.
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 pareamento | Por hora | Por dia | Destinatários novos em 24 h |
|---|---|---|---|
| Até 6 horas | 5 | 20 | 5 |
| De 6 a 24 horas | 10 | 50 | 10 |
| De 1 a 3 dias | 20 | 100 | 20 |
| De 3 a 7 dias | 30 | 150 | 30 |
| De 7 a 14 dias | 45 | 200 | 50 |
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.newRecipientsdeGET /connections/{id}/queuemostra 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.
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:
- 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.
- Diga quem está falando. A primeira mensagem de uma conversa deve deixar claro o nome da empresa e o motivo do contato.
- 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. - 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.
- 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.deliverycom o statusfailede o motivoreachout_timelocked; - o evento
connection.statuschega com o motivoreachout_timelocke o fim previsto emreachoutTimelock.endsAt; - enquanto o bloqueio durar, a fila recusa os envios sem tentá-los, porque cada tentativa aprofundaria a restrição, e cada envio com
clientRefgeramessage.send_failedcom o motivoreachout_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 umclientRefnovo: 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
clientRefem todo envio para nunca duplicar uma mensagem. - Ofereça sempre uma forma de o contato parar de receber mensagens.
Como começar hoje
- Liste de onde vêm os números para os quais você envia e separe quem nunca falou com você.
- Troque os textos fixos por templates com variáveis e inclua uma opção de saída.
- Passe a base por
contacts/checke marque quem não tem WhatsApp. - Gere um
clientRefestável para cada envio, como o id do pedido somado ao tipo do aviso. - Trate a resposta
429e o eventomessage.send_failedno seu sistema, em vez de repetir o envio na força. - Assine os eventos
connection.statuse alerte a equipe quando chegarreachout_timelock. - 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: