Fila com ritmo anti-bloqueio
Cada número tem uma fila que espaça os envios: limites por minuto, hora e dia, intervalo aleatório e teto de destinatários novos. Sem cobrança por mensagem.
Atualizado em
O WhatsApp restringe números que enviam como robôs: dezenas de mensagens no mesmo segundo, o mesmo texto para centenas de contatos que nunca falaram com o número, rajadas a qualquer hora. Por isso a apiwpp não envia na hora em que você chama a API. Cada número conectado tem uma fila que espaça os envios num ritmo parecido com o de uma pessoa, e o seu sistema não precisa controlar nada disso.
A fila reduz o risco de bloqueio; ela não o elimina. Nada garante que um número nunca será restringido pelo WhatsApp, e o que você envia, e para quem, continua sendo a parte mais importante.
Os limites de cada número
Estes são os valores padrão, aplicados a cada número separadamente:
| Regra | Padrão |
|---|---|
| Envios por número | 3 por minuto, 60 por hora, 200 por dia |
| Intervalo entre dois envios | aleatório, de 3 a 8 segundos |
| Mesmo destinatário | pelo menos 30 segundos entre duas mensagens |
| Destinatários novos | 100 por 24 horas |
O intervalo aleatório evita o padrão de relógio que denuncia um robô. Os 30 segundos para o mesmo destinatário evitam que uma pessoa receba várias mensagens seguidas por causa de um erro no seu sistema. Antes de cada texto, a API ainda mostra "digitando…" por alguns instantes (typingDelay, 1500 ms por padrão), como faria alguém escrevendo no celular.
Os valores que valem para um número agora, inclusive durante o aquecimento, estão em GET /connections/{id}/queue, descrito mais abaixo.

Destinatários novos e contatos conhecidos
A regra que mais protege o número é o teto de destinatários novos: por padrão, até 100 pessoas por 24 horas que nunca trocaram mensagem com o número.
Um contato é conhecido quando trocou mensagem com o número nos últimos 28 dias, depois da conexão atual: escreveu para ele ou recebeu mensagem dele, pela API ou digitada no celular. Qualquer outro é um destinatário novo. Contatos conhecidos nunca são barrados por esse teto, então quem conversa com os próprios clientes quase não sente o limite. Grupos não contam.
Quando o número já alcançou o teto das últimas 24 horas, um envio para mais uma pessoa nova é recusado na hora, e nada é enfileirado:
{ "error": "new_recipient_cap_reached", "message": "This number already reached 100 new recipients …" }
A resposta é 429, com o cabeçalho Retry-After dizendo em quantos segundos uma vaga abre. O seu sistema pode reagendar o envio para esse horário:
const response = 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({ to: '5511988887777', message: 'Olá! Recebemos o seu cadastro.', clientRef: 'cadastro-8812' }),
})
if (response.status === 429) {
const retryAfter = Number(response.headers.get('Retry-After') ?? 60)
// Reagende o envio para daqui a retryAfter segundos, com o mesmo clientRef.
}
Parear o número de novo, depois de um logout ou de o WhatsApp encerrar a sessão, zera os contatos conhecidos: todos voltam a contar como novos. Por isso, desconectar de propósito é diferente de fazer logout.
Aquecimento dos primeiros 14 dias
Um número recém-conectado é o mais vigiado. Nos 14 dias depois do pareamento, a fila usa limites menores, que sobem por etapas:
| Desde a conexão | Por hora | Por dia | Destinatários novos por 24 h |
|---|---|---|---|
| Até 6 horas | 5 | 20 | 5 |
| 6 a 24 horas | 10 | 50 | 10 |
| 1 a 3 dias | 20 | 100 | 20 |
| 3 a 7 dias | 30 | 150 | 30 |
| 7 a 14 dias | 45 | 200 | 50 |
Nenhuma etapa passa dos limites normais. O aquecimento é automático e recomeça quando você conecta outro número ou o mesmo número depois de um logout. O recurso de aquecimento de número e o guia sobre por que os primeiros 14 dias importam explicam o que fazer nesse período.
Acompanhar a fila pela API
Cada envio responde 202 na hora, com o lugar na fila e o horário previsto:
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 3 }
scheduledAt é o horário previsto do envio, em milissegundos unix, e position é o lugar na fila. Por isso a fila não serve para códigos de verificação ou alertas que precisam chegar no mesmo segundo: o envio sai quando o ritmo do número permite.
Para ver o estado do número, chame GET /connections/{id}/queue:
{
"pending": 1,
"scheduled": 2,
"limits": { "perMinute": 3, "perHour": 60, "perDay": 200, "newRecipientsPerDay": 100 },
"usage": { "minute": 1, "hour": 12, "day": 40, "newRecipients": 7 },
"warmup": { "createdAt": 1789646400000, "messagesSent": 40, "isInWarmup": false, "endsAt": 1790856000000 }
}
limits são os limites atuais, usage é quanto deles já foi usado e warmup mostra se o número ainda está aquecendo. Um envio que ainda não saiu pode ser cancelado com DELETE /connections/{id}/queue/{jobId}. O resultado de cada envio chega pelos webhooks: message.delivery com o status e, para envios com clientRef que não vão acontecer, message.send_failed com o motivo.
Bloqueio temporário de novas conversas
Se o WhatsApp começa a recusar mensagens para contatos que nunca falaram com o número, a conta pode entrar num bloqueio temporário de novas conversas. A apiwpp detecta esse bloqueio, avisa pelo evento connection.status com o fim previsto e, enquanto ele durar, recusa os envios sem tentá-los, porque cada tentativa aprofundaria a restrição. Depois do fim, reenvie com um clientRef novo.
Mensagens ilimitadas dentro do ritmo
Nos planos LITE e PRO não há cobrança por mensagem nem cota de mensagens: o preço é por número conectado, por mês, e você envia quantas mensagens quiser dentro dos limites da fila. Precisa de mais volume? Conecte mais números; cada um tem a própria fila e os próprios limites. Veja os preços e a calculadora.
A fila não transforma o número numa ferramenta de disparo em massa, e não foi feita para isso. Para listas frias ou compradas, leia por que números são bloqueados em disparos em massa; para o dia a dia, o guia como evitar o bloqueio do número reúne as boas práticas.
Perguntas frequentes
Por que a mensagem não sai no mesmo segundo?
Porque cada envio entra na fila do número, que espaça as mensagens com intervalos aleatórios e limites por minuto, hora e dia. A resposta 202 traz scheduledAt, o horário previsto, e position, o lugar na fila.
A fila garante que o meu número nunca será bloqueado?
Não. A fila reduz o risco, com ritmo humano, teto de destinatários novos e aquecimento, mas nada garante que o WhatsApp não restrinja um número. Enviar só para quem espera a sua mensagem continua sendo o mais importante.
O limite de destinatários novos vale para os meus clientes?
Não para quem já conversa com o número. Um contato que trocou mensagem com ele nos últimos 28 dias, depois da conexão atual, é conhecido e nunca é barrado pelo teto. O limite vale para pessoas que nunca falaram com o número.
Pago mais se enviar mais mensagens?
Não. O preço é por número conectado, por mês, com mensagens ilimitadas dentro dos limites da fila. Para enviar mais, conecte mais números, cada um com a própria fila.
Posso ver quanto do limite já usei?
Sim. GET /connections/{id}/queue mostra os limites atuais do número, quanto deles já foi usado no minuto, na hora e no dia, os destinatários novos das últimas 24 horas e o estado do aquecimento.
Outros recursos
Todos: Recursos →Nos 14 dias depois de conectado, cada número segue limites menores de envio e de destinatários novos, que sobem em cinco etapas. A fila aplica tudo sozinha, e o estado do aquecimento aparece em GET /connections/{id}/queue.
Consulte até 100 números por chamada e saiba quais estão no WhatsApp, com o endereço (JID) em que cada um está registrado. Útil no cadastro, na limpeza da base e antes de uma sequência de envios.
O clientRef é o seu identificador de um envio. Repetir a requisição com o mesmo valor devolve o job original com duplicate: true, sem enfileirar outra mensagem, e o clientRef volta nos eventos de entrega e de falha.