ConectZap · Documentação

Tempo real

Além dos webhooks, os mesmos eventos (esquema Event) podem ser recebidos por WebSocket em realtime.conectzap.app. É o canal para painéis e integrações que precisam de latência baixa. A entrega é de melhor esforço: um evento pode se perder (falha no ConectZap, evento grande demais, reinício) ou chegar repetido. O resume recupera só o que ainda está no buffer. Para não perder nada, use webhooks, o canal oficial de integração.

1. Peça um ticket

A chave de API nunca vai na URL do WebSocket. Troque-a por um ticket de uso único:

curl -X POST https://api.conectzap.app/v1/realtime/tickets \
  -H "Authorization: Bearer $CONECTZAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceIds": [], "events": ["message.received"]}'

2. Conecte

Abra o WebSocket na url recebida (wss://realtime.conectzap.app/v1/stream?ticket=…). Erros do upgrade: 401 ticket inválido, vencido ou já usado; 403 Origin não permitido (clientes de servidor, sem Origin, são aceitos; em navegador, só o painel do ConectZap); 429 limite por IP ou de conexões da empresa (50, estimado, pode mudar).

3. Frames

Do servidor

type Quando
ready Ao conectar: {cursor, reauthAt}. A partir de reauthAt a conexão é fechada com 4001.
events Lote {items} de até 100 itens e 512 KB (estimado, pode mudar); cada item é {cursor, event}.
resumed Depois de um resume aceito: {cursor}.
resync_required O cursor do resume não serve: reconcilie pela API REST.
pong Resposta ao ping.
error {code} de uma mensagem do cliente recusada.

Do cliente

JSON, até 4 KB por mensagem e até 10 por segundo (acima disso a conexão fecha com 1008):

Cursor, resume e resync_required

O cursor é por empresa (não por instância) e opaco. Guarde o do último item processado e, ao reconectar, mande resume com ele: o servidor reenvia o que ainda está no buffer e responde resumed. O buffer guarda os últimos 10 min ou 5.000 eventos (estimado, pode mudar), e só enquanto alguém está conectado ou se conectou há pouco. Cursor desconhecido, de outra época, à frente do último ou mais velho que o buffer recebe resync_required: busque o estado atual pela API REST (por exemplo, o status das instâncias) e siga a partir do novo cursor.

instance.qr.updated nunca é guardado nem reenviado: peça GET /v1/instances/{instanceId}/qr. A entrega é de melhor esforço: pode perder e pode repetir eventos, então deduplique por event.id e use webhooks quando não puder perder nada.

Códigos de fechamento

Código Motivo O que fazer
4001 Reautenticação (a cada 24 h, ou antes, se o ConectZap não conseguir revalidar a chave por mais de 5 min) Peça um ticket novo e reconecte com resume.
4401 Chave revogada ou vencida, ou empresa fora de active Não reconecte em laço: corrija a credencial.
1008 Violação de política (mensagem inválida ou ritmo excedido) Corrija o cliente.
1009 Frame grande demais Mensagens do cliente até 4 KB.
1013 Cliente lento Processe os lotes mais rápido (fila local) e reconecte com resume.
1001, 1012 Deploy do ConectZap (normal) Reconecte com backoff e ticket novo.

Reconexão

Reconecte com backoff exponencial e jitter, de 0,5 s até 30 s, pedindo um ticket novo a cada tentativa e mandando resume com o último cursor. Zere o backoff ao receber ready.

// Cliente mínimo (Node 22+ ou navegador do seu servidor de painel): reconexão com backoff,
// ticket novo a cada tentativa e resume com o último cursor.
let ultimoCursor = null; // guarde em disco/banco para sobreviver a reinícios
let tentativa = 0;

async function novoTicket() {
  const r = await fetch("https://api.conectzap.app/v1/realtime/tickets", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CONECTZAP_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ events: ["message.received", "message.updated"] }),
  });
  if (!r.ok) throw new Error(`ticket: HTTP ${r.status}`);
  return (await r.json()).url; // wss://realtime.conectzap.app/v1/stream?ticket=…
}

async function conectar() {
  const ws = new WebSocket(await novoTicket());
  ws.onmessage = (m) => {
    const frame = JSON.parse(m.data);
    if (frame.type === "ready") {
      tentativa = 0;
      if (ultimoCursor) ws.send(JSON.stringify({ type: "resume", cursor: ultimoCursor }));
      else ultimoCursor = frame.cursor;
    } else if (frame.type === "events") {
      for (const { cursor, event } of frame.items) {
        processar(event); // deduplique por event.id
        ultimoCursor = cursor;
      }
    } else if (frame.type === "resync_required") {
      ultimoCursor = null;
      reconciliarPelaApiRest(); // o buffer não cobre o intervalo perdido
    }
  };
  ws.onclose = (e) => {
    if (e.code === 4401) return pararEAvisar(); // credencial revogada ou vencida: não insista
    // 0,5 s, 1 s, 2 s… até 30 s, com jitter
    const atraso = Math.min(30_000, 500 * 2 ** tentativa++) * (0.5 + Math.random() / 2);
    setTimeout(() => conectar().catch(() => ws.onclose(e)), atraso);
  };
}