Disparo em massa no WhatsApp: fila, rate limit e retry (a engenharia que o for-loop não resolve)

for (const contato of contatos) {
  await enviar(contato.numero, mensagem);
}

import { Queue, Worker } from 'bullmq';

const fila = new Queue('campanha', { connection: redis });

// PRODUTOR — só enfileira. Não envia nada. Termina em segundos.
async function agendarCampanha(campanhaId, contatos, template) {
  for (const c of contatos) {
    await fila.add('envio', {
      campanhaId,
      to: c.numero,
      params: [c.nome, c.pedido],
      template,
    }, {
      // Determinístico: reenfileirar a campanha inteira não duplica nada.
      jobId: `${campanhaId}:${c.numero}`,
      attempts: 5,
      backoff: { type: 'exponential', delay: 2000 },
    });
  }
}

new Worker('campanha', async (job) => {
  const { to, params, template, campanhaId } = job.data;

  // Opt-out AQUI, não na montagem da campanha. Uma campanha grande
  // leva horas para escoar, e quem pede para sair no meio precisa
  // parar de receber no meio.
  if (await estaEmOptOut(to)) {
    await registrar(campanhaId, to, 'optout');
    return;
  }

  try {
    const r = await enviarTemplate(to, template, params);
    await registrar(campanhaId, to, 'enviado', r.messageId);
  } catch (e) {
    if (definitivo(e)) {
      await registrar(campanhaId, to, 'falha_definitiva', null, e.code);
      return;                       // não repete: não adianta
    }
    throw e;                        // temporário: deixa a fila repetir
  }
}, {
  connection: redis,
  concurrency: 1,                   // um por vez: ritmo é o objetivo
  limiter: { max: 20, duration: 60_000 },   // no máximo 20 por minuto
});

const DEFINITIVOS = new Set([
  'numero_invalido',
  'sem_whatsapp',
  'template_nao_aprovado',
  'contato_bloqueou',
]);

function definitivo(e) {
  if (DEFINITIVOS.has(e.code)) return true;

  const s = e.status;
  if (!s) return false;                 // rede: temporário
  if (s === 429) return false;          // limite: temporário
  if (s >= 500) return false;           // servidor: temporário
  return s >= 400 && s < 500;           // demais 4xx: definitivo
}

backoff: {
  type: 'custom',
  // 2s, 4s, 8s, 16s… com até 30% de variação aleatória,
  // para as tentativas não voltarem todas no mesmo instante.
  strategy: (tentativa) => {
    const base = Math.min(2000 * 2 ** (tentativa - 1), 5 * 60_000);
    return base * (1 + Math.random() * 0.3);
  },
}

async function pausaHumana() {
  // 3 a 10 segundos, variável. Intervalo fixo é padrão detectável.
  const ms = 3000 + Math.random() * 7000;
  await new Promise((r) => setTimeout(r, ms));
}

function dentroDoHorario() {
  const agora = new Date();
  const h = agora.getHours();
  const dia = agora.getDay();
  if (dia === 0) return false;              // domingo não
  if (dia === 6) return h >= 9 && h < 13;   // sábado de manhã
  return h >= 8 && h < 20;
}

if (!dentroDoHorario()) {
  await job.moveToDelayed(Date.now() + 30 * 60_000);
  return;
}

async function progresso(campanhaId) {
  const [aguardando, ativos, falhos] = await Promise.all([
    fila.getWaitingCount(),
    fila.getActiveCount(),
    fila.getFailedCount(),
  ]);
  const enviados = await contarPorStatus(campanhaId, 'enviado');

  return {
    enviados,
    aguardando,
    ativos,
    falhos,
    // Com limiter de 20/min, dá para estimar o fim de verdade
    terminaEm: `${Math.ceil(aguardando / 20)} min`,
  };
}

CREATE TABLE envios (
  campanha_id  BIGINT,
  numero       VARCHAR(20),
  status       VARCHAR(20) DEFAULT 'pendente',
  tentativas   INT DEFAULT 0,
  proxima_em   TIMESTAMPTZ DEFAULT NOW(),
  message_id   VARCHAR(80),
  erro         VARCHAR(50),
  PRIMARY KEY (campanha_id, numero)
);