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"]}'
-
Exige o escopo
realtime:subscribe, que só abre o canal. Cada tipo de evento exige também o escopo de leitura dele:message.*→messages:read;instance.qr.updated→instances:connect; os demaisinstance.*→instances:read;webhook.failed→webhooks:read. Pedir um tipo sem o escopo dele, ou usar uma chave que não lê tipo nenhum, dá403. -
A resposta (
201,Cache-Control: no-store) trazticket,urleexpiresAt. - O ticket vale 60 s e uma conexão. É um segredo: não o registre em log.
-
instanceIdsvazio ou ausente = todas as instâncias da chave; instância fora da chave dá403.eventsvazio ou ausente = todos os tipos que a chave pode ler (webhook.testnão existe em tempo real).
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):
{"type": "ping"};-
{"type": "resume", "cursor": "…"}: reenvia o que ainda está no buffer depois desse cursor. Um por conexão a cada 10 s (estimado, pode mudar); repetir antes disso dáerrorrate_limited, e a 3ª repetição fecha com1008; -
{"type": "subscribe", "instanceIds": […], "events": […]}: só restringe o filtro; nunca alarga o escopo do ticket.
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);
};
}