A fila de envio

O que acontece de verdade

Envie para alguém que não escreveu para o seu número nas últimas 24 horas, e a API responde queued em vez de sent:

{
  "data": {
    "id": "9c1f0b7e-8b1a-4a2e-9b0a-1f2e3d4c5b6a",
    "to": "+5511988887777",
    "status": "queued",
    "scheduledAt": "2026-08-24T19:18:00.000Z",
    "quotaRemaining": 4999,
    "newConversationsRemaining": 19
  }
}

A mensagem conta na cota assim que a chamada aceita o envio. scheduledAt é o horário previsto. Por padrão, as mensagens da fila saem com 15 a 25 minutos de intervalo, escolhido ao acaso, uma por vez por número. O intervalo conta a partir da saída real da mensagem anterior, não de um horário antigo, para que uma fila atrasada não saia toda de uma vez. Até ela sair, id é o id da fila, não o da mensagem no WhatsApp.

Por que seguramos

Enviar muitas mensagens em pouco tempo pode parecer spam, mesmo para quem já conversou com o número. Espaçar a fila evita uma rajada acidental. Isso não garante que o WhatsApp vá manter o número conectado.

A falha que isso evita é banal e comum. Você envia uma lista de quinze, o seu próprio sistema emenda mais quatro atrás, e na hora do almoço o número já era. Ninguém quis mandar spam pra ninguém. A rajada é um acidente de software ser rápido.

Todo o resto de como não ser banido continua valendo. Isso aqui resolve o tempo, que é justamente a parte mais difícil de acertar na mão.

O que nunca fica esperando

Estas são as exceções para envios individuais. Com a fila ligada, toda mensagem de um lote espera o intervalo completo, inclusive respostas e mensagens para quem já conversou com o número.

• Respostas recentes saem na hora. A pessoa precisa ter enviado uma mensagem para este número nas últimas 24 horas. Um contato salvo no celular, uma mensagem enviada no passado ou uma conversa importada no pareamento não bastam.
• send_otp nunca espera nem mostra "digitando…", porque tem alguém num formulário aguardando o código. O primeiro código para uma pessoa nova ainda gasta o limite de conversas novas do dia.
• skipQueue: true pula a fila naquele envio. Use só quando a pessoa estiver esperando a mensagem na hora. Mensagens para grupos também não entram na fila em envios individuais.
• Um número com pacing.enabled: false envia tudo na hora, e espaçar os envios passa a ser tarefa sua.

await client.sendMessage({
  to: "+5511988887777",
  text: `Your code is ${code}`,
  // Only for something the recipient is waiting for RIGHT NOW.
  skipQueue: true,
});

Saber quando ela saiu

A chamada de envio não tem como te dar o id de mensagem do WhatsApp, porque nada foi enviado ainda. message.sent chega no seu webhook quando a mensagem finalmente sai. Ele traz o id da fila que você já tem, ao lado do messageId do próprio WhatsApp, que é o id que os recibos de entrega vão usar.

{
  "id": "6f1e…",
  "type": "message.sent",
  "timestamp": "2026-08-24T19:18:04.000Z",
  "data": {
    "number": { "id": "a1b2…", "name": "Outreach", "phone": "5511900000000" },
    "id": "9c1f0b7e-8b1a-4a2e-9b0a-1f2e3d4c5b6a",
    "messageId": "3EB0C7E5F5A2B4D9E1F3",
    "to": "+5511988887777",
    "queuedAt": "2026-08-24T19:00:00.000Z",
    "sentAt": "2026-08-24T19:18:04.000Z"
  }
}

Se o número cair ou for restringido, as mensagens que ainda não saíram continuam na fila. Quando ele reconectar, elas voltam a sair com o intervalo configurado. Uma recusa confirmada, como uma url de mídia que parou de funcionar, pode gerar message.failed e um estorno. Se não soubermos se a mensagem saiu após um timeout ou uma interrupção, não tentamos de novo nem estornamos como se ela não tivesse saído. Confira a conversa e os recibos de entrega antes de reenviar.

Ver e cancelar o que está esperando

GET /v1/queue lista as mensagens que ainda esperam, da mais próxima para a mais distante. Cancele antes de o envio começar. A resposta diz se a cota da mensagem foi devolvida, e qualquer limite de conversas novas reservado por ela é liberado. No painel, Mensagens mostra a fila da conta e Números mostra a fila de cada número.

const waiting = await client.listQueuedMessages({ numberId });
// [{ id, to, kind, preview, scheduledAt, queuedAt }, …]

await client.cancelQueuedMessage({ id: waiting[0].id });
// → { canceled: true, refunded: true }

Mudar o intervalo

O intervalo pertence ao número e é de 15–25 minutos por padrão. Mude com update_number, ou no painel, em Números.

await client.updateNumber({
  numberId,
  pacing: { minMinutes: 30, maxMinutes: 90 },   // slower, safer
  humanize: { markRead: false },                // no blue ticks from us
});

Você pode desligar a fila, mas aí precisa espaçar os envios por conta própria. Isso também vale quando usar skipQueue. Evite rajadas e escreva só para quem espera receber suas mensagens.

Enviar como uma pessoa

A segunda metade da mesma ideia: o envio é feito do jeito que uma pessoa faria, não do jeito que um software faria.

• O número fica online pouco antes de enviar, e sai depois.
• Ele abre o que o destinatário escreveu por último, o que marca os tiques azuis, antes de responder.
• Ele mostra “digitando…” pelo tempo que a mensagem levaria para ser digitada.

Isso custa alguns segundos por chamada e vem ligado. Desligue qualquer parte por número com update_number, ou só numa mensagem com humanize: false.

O que isto não é

Não é agendador. Você escolhe um intervalo, nunca um horário de entrega. Também não é garantia de entrega. Quem decide se a mensagem chega continua sendo o WhatsApp, e os recibos continuam chegando em message.status.

E não substitui ter algo que valha a pena enviar. A fila espaça uma lista ruim direitinho. Ela não impede as pessoas dessa lista de tocar em Bloquear.