Eventos em tempo real (SSE)
Abra um stream Server-Sent Events em GET /events, retome de onde parou com Last-Event-ID e recupere o histórico com ReplayEvents.
GET /events abre um stream Server-Sent Events com os eventos dos números da chave: mensagens recebidas e enviadas, status de entrega, conexão dos números, atendimento, chamadas e, opcionalmente, campanhas e aquecimento. Exige events:read.
curl -N "https://api.zynzap.com.br/v1/events" \
-H "Authorization: Bearer $ZYNZAP_API_KEY" \
-H "Last-Event-ID: 1042"Formato
Cada evento é um bloco event: + data: terminado por uma linha em branco:
id: 1043
event: domain
data: {"MessageReceived":{"session_id":"8c1f7a52-4d1e-4b8a-9a43-2f6f5d0c9e11","from":"[email protected]","body":"Oi!","message_id":"3EB0C431C2B5A1F0D2E1","is_group":false,"timestamp_unix_ms":1760280000000,"message_type":"text","push_name":"Ana"}}
event: ping
data: {"t":1760280025000}event | Significado |
|---|---|
domain | Um evento. id: é o cursor (crescente) e data: é { "<Tipo>": {...} }, o mesmo data dos webhooks. |
ping | Batimento a cada 25 s. Ignore. |
refresh | Não foi possível reproduzir o histórico pedido (reason: cursor_expired, buffer_limit, replay_limit, replay_incomplete, replay_unavailable). Refaça uma consulta completa do que importa e continue. |
error | Erro com o corpo padrão (ex.: API_AUTH_REVOKED quando a chave é revogada). O stream fecha em seguida. |
end | O servidor encerrou o stream. Reconecte. |
Parâmetros
| Parâmetro | Onde | Descrição |
|---|---|---|
Last-Event-ID | cabeçalho | Cursor do último evento processado. O EventSource do navegador envia sozinho ao reconectar. |
after_cursor | query | Alternativa ao cabeçalho. |
session_id | query | Filtra por número; repita para vários (até 1000). |
include_product | query | true inclui campanhas e aquecimento (só chaves sem restrição de números). |
Retomar sem perder eventos
Os eventos são persistidos por um período. Ao reconectar com o último cursor, o servidor reenvia o que você perdeu (até 20 mil eventos) e depois continua ao vivo, sem duplicar nem pular. Se o cursor for antigo demais, chega refresh.
Boas práticas:
- Grave o
idde cada evento depois de processá-lo. - Reconecte com backoff (1 s, 2 s, 4 s... até 30 s). Cada conexão dura até 1 hora; o limite é de 10 aberturas por minuto por conta.
- Deduplique por cursor: depois de uma reconexão, eventos já vistos podem aparecer.
Histórico sob demanda: ReplayEvents
Para buscar eventos sem manter conexão (por exemplo, após o webhook ficar desativado), use ReplayEvents com after_cursor. Ele devolve até 1000 eventos por chamada, next_cursor, has_more e reset_required (cursor expirado).
curl -X POST "https://api.zynzap.com.br/v1/rpc/ReplayEvents" \
-H "Authorization: Bearer $ZYNZAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request": {
"after_cursor": "1042",
"limit": 500
}
}'Cada item de events tem json_payload (o mesmo JSON de data:) e cursor.
Navegador
O EventSource nativo não envia cabeçalhos, e a chave nunca deve ir para o navegador. Consuma o stream no seu servidor e repasse ao front-end o que for necessário.