Documentação

Boas práticas, fluxo da fila e snippets de API

Aviso de risco: esta integração usa biblioteca não oficial. A Meta proíbe automação não-oficial em seus termos. Para uso comercial em escala, considere a WhatsApp Cloud API oficial — ou avise seu cliente do risco de banimento por contrato.

Boas práticas obrigatórias

  1. Throttle entre envios. Já configurado: SEND_THROTTLE_MIN_MS/SEND_THROTTLE_MAX_MS (padrão 2-5s com jitter). Para disparo, eleve para 10-30s.
  2. Aqueça números novos. Use o número 2+ semanas com tráfego natural (foto, status, conversas reais) antes de qualquer disparo. Volume inicial: 50-100 msg/dia, escalar gradualmente.
  3. Varie o conteúdo. Mesma mensagem para 100+ destinatários é o sinal nº 1 de spam. Personalize com nome e mude pequenas palavras (use templates com variáveis).
  4. Prefira contatos opt-in. Reportes de "spam" pelos destinatários é o gatilho mais forte. Só envie pra quem aceitou receber. Lista fria de cold-mailing → ban quase certo.
  5. Respeite horário comercial. Disparos de madrugada multiplicam reportes. Use 9h-18h, dias úteis.
  6. Evite mensagens só com link/promoção. Texto curto + URL é detectado pelos filtros do WhatsApp. Acrescente contexto humano antes do link.
  7. Não desligue o celular pareado. O SISTEMA depende do celular. Manter o aparelho off por dias degrada a sessão.
  8. Reaja a sinais de bloqueio. Se receber erro Rate limit ou as mensagens pararem de chegar, pare imediatamente e deixe descansar 24h. Insistir = ban definitivo.
  9. Múltiplos números, não um só. Distribua disparos entre várias sessões (cada uma com seu chip). Concentrar volume em 1 número = ban garantido.
  10. Monitore o delivery rate. Queda repentina nas confirmações de entrega = você foi shadow-banned. Reduza volume na hora.

Todo envio passa por uma fila Redis (BullMQ). Isso garante ordem, retries automáticos e que mensagens não são perdidas em caso de crash.

Estados do job
waitingAguardando worker. Se a sessão estiver desconectada, fica aqui até reconectar.
activeWorker processando o envio agora.
completedMensagem entregue ao WhatsApp. Retorna messageId.
failedEsgotou tentativas (3x com backoff exponencial). Ver no Bull Board.
delayedAguardando backoff antes do próximo retry.

Como funciona o aguardando envio

  1. Você chama POST /sessions/:id/send-message → job entra em waiting.
  2. O worker da sessão (1 por sessão, concurrency=1) puxa o próximo job.
  3. Se a sessão estiver connected, o envio acontece. Se não, o job fica em waiting até a sessão reconectar.
  4. Após o envio, o worker dorme entre SEND_THROTTLE_MIN_MS e SEND_THROTTLE_MAX_MS (jitter randômico) antes de pegar o próximo.
  5. Falhas com backoff exponencial (2s, 4s, 8s) e até 3 tentativas. Erros marcados como permanentes (ex: número inválido) não retentam.
Default = fire-and-forget. Toda chamada enfileira o job e responde 202 com jobId em milissegundos — o throttle anti-ban roda no worker, não na sua chamada HTTP. Acompanhe o resultado pelo Bull Board ( Filas). Use wait:true apenas em testes pra bloquear até concluir (limite SEND_JOB_TIMEOUT_MS).
Abrir Bull Board

Nova sessão

Conecte um novo número WhatsApp

Pra você identificar a sessão no painel.

Opcional. POST com cada mensagem que chegar. Pode editar depois.

Opcional. Avisa quando a sessão cair, voltar ou for desparcelada.

Próximo passo: depois de criar, clique Conectar no card e escaneie o QR Code com o celular.

Whats.hd

Acesse o painel para gerenciar suas sessões

Whats.hd
painel de sessões
API Reference Filas
Sessões
0
Conectadas
0
Pendentes na fila
0
Recebidas
0
Crie uma sessão pra parear um número WhatsApp.
Comece conectando seu primeiro número
Crie uma sessão, escaneie o QR Code e comece a enviar e receber mensagens.
Whats.hd · sessões em paralelo · fila persistente · webhook