Sua primeira instância

Estados possíveis

DISCONNECTED  →  CONNECTING  →  QR_PENDING  →  CONNECTED
                                                   ↓
                                              (uso normal)
                                                   ↓
                                              DISCONNECTED  (manual ou erro)
                                                   ↓
                                              BANNED        (Meta baniu)
                                                   ↓
                                              ERROR         (falha irrecuperável)

Criar via API

curl -X POST https://api.pepinozap.com/v1/instances \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "vendas-1"}'

Estado inicial: DISCONNECTED. O worker pega a instância via lease no Redis e tenta abrir o socket.

Receber QR via SSE

const evt = new EventSource(
  `https://api.pepinozap.com/v1/instances/${id}/qr?token=${apiKey}`,
);
 
evt.onmessage = (e) => {
  const data = JSON.parse(e.data);
  if (data.qrDataUrl) renderQrImage(data.qrDataUrl);
  if (data.status === 'CONNECTED') celebrate();
};

Reconexão automática

Quando o socket cai, o worker tenta reconectar com backoff exponencial:

Tentativa	Delay
1ª	5s
2ª	10s
3ª	30s
4ª+	60s (max)

Se o WhatsApp respondeu com loggedOut, a instância vira DISCONNECTED e exige novo QR scan.

Quando vira BANNED

Worker detecta loggedOut com motivo "Banned" (ou similar) → atualiza status=BANNED, banned_at=now(), ban_reason="...". Sem reconexão automática nesse caso (proteção pra não piorar).

Pra evitar ban: use warmup nos primeiros dias (≤10 msgs/min), nunca envie a mesma mensagem pra muita gente (use templates com variação), e respeite o opt-out.

Próximos passos

Conceitos: anti-ban — como minimizar risco de ban
Webhooks — receba eventos no seu backend em tempo real
API Reference — endpoints completos