Eventos em tempo real (WebSocket)
Existe um WebSocket em /ws que empurra eventos ao vivo. Antes de investir nele, leia a seção
final: para integração servidor-a-servidor, provavelmente não é o que você quer.
Autenticação
Só por cookie de sessão do painel. Não há autenticação por chave de API aqui.
Versões antigas aceitavam
?token=xxxna query string. Isso foi removido: se você encontrou esse formato em alguma documentação, ela está desatualizada e a conexão será rejeitada.
Como o navegador envia o cookie de sessão automaticamente, o uso natural é numa página do próprio painel:
const ws = new WebSocket('wss://apidevzap.com/ws');
Sem sessão válida, o servidor responde { "error": "Unauthorized" } e fecha a conexão.
Assinando uma instância
Conectado, você recebe uma confirmação:
{ "type": "connected", "message": "WebSocket connected successfully" }
A partir daí, assine as instâncias que interessam:
ws.send(JSON.stringify({ action: 'subscribe', instanceId: 'INST-XXX' }));
Resposta: { "type": "subscribed", "instanceId": "INST-XXX" }. Se a instância não existir ou for
de outro tenant, vem { "type": "error", "message": "Instance not found or access denied" }.
Para parar: { action: 'unsubscribe', instanceId: 'INST-XXX' }.
Eventos recebidos
Todos no envelope { type, instanceId, data, timestamp }.
| Evento | Quando |
|---|---|
qr.update |
Novo QR code disponível |
status.changed |
O estado da instância mudou (data.status, e data.reason ao cair, ex.: PASSKEY_REQUIRED) |
connection.ready |
A instância terminou de conectar |
message.received |
Chegou uma mensagem |
message.sent |
Uma mensagem foi enviada |
Note que os nomes aqui são diferentes dos eventos de webhook: aqui é qr.update e
status.changed; lá é qr.updated e connection.changed. São sistemas distintos com vocabulários
distintos.
WebSocket ou webhook?
| WebSocket | Webhook | |
|---|---|---|
| Autenticação | Cookie de sessão | Chave de API (no registro) |
| Direção | Você conecta | Nós chamamos você |
| Se cair | Perde os eventos do período | Retry automático |
| Serve para | Interfaces, telas ao vivo | Integração servidor-a-servidor |
Use WebSocket para atualizar uma tela em tempo real, acompanhar o QR code aparecendo, mostrar o status mudando. É o que o painel faz.
Use webhook para qualquer coisa que precise ser confiável. O WebSocket não tem garantia de entrega: se a conexão cair, os eventos daquele intervalo se perdem, e não há como recuperá-los.
Para acompanhar a conexão de uma instância sem manter um WebSocket aberto, o caminho mais simples é
consultar GET /api/v1/instances/{id} quando precisar, especialmente porque os eventos de webhook
connection.changed e qr.updated, apesar de aceitos no registro, não são emitidos hoje.
Guia verificado em 05/08/2026 contra a implementação atual.