Pular para o conteúdo
apiwpp
Recurso

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:

RegraPadrão
Envios por número3 por minuto, 60 por hora, 200 por dia
Intervalo entre dois enviosaleatório, de 3 a 8 segundos
Mesmo destinatáriopelo menos 30 segundos entre duas mensagens
Destinatários novos100 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.

Painel da fila de um número: limites, uso e aquecimento
A fila de cada número mostra os limites atuais, o uso e o aquecimento.

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ãoPor horaPor diaDestinatários novos por 24 h
Até 6 horas5205
6 a 24 horas105010
1 a 3 dias2010020
3 a 7 dias3015030
7 a 14 dias4520050

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.

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.

Conecte seu primeiro número hoje.

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