Eventos (SSE)

Um stream Server-Sent Events de mão única para estado ao vivo. Use no lugar de polling para QR codes, mudanças de estado de canal e atividade de mensagens.

Endpoint

GET/v1/eventsBearer · API key

Autentique via Authorization: Bearer … ou query string ?token=…. (O EventSource do browser não consegue definir headers; o caminho via query-token é para esse caso.)

Stream SSE — mantenha a conexão aberta. A maioria das linguagens tem um cliente HTTP de streaming; os trechos abaixo assumem o mais simples disponível por ecossistema.

curl -s "$WHATISUP_API/v1/events" \
  -H "Authorization: Bearer $WHATISUP_API_KEY"

Para código de browser especificamente, EventSource é o caminho mais limpo porque ele lida com a reconexão por você:

const es = new EventSource(`${WHATISUP_API}/v1/events?token=${WHATISUP_API_KEY}`);
es.addEventListener('message', (e) => console.log(JSON.parse(e.data)));

Filtragem

Por padrão você recebe todo evento de todo canal que a chave de API consegue ver. Filtre com query params:

Param	Efeito
`channel_id`	apenas este canal
`events`	lista separada por vírgulas, ex.: `channel.connected,qr.updated`

Filtragem do lado do servidor significa que você não paga a banda em coisas com as quais não se importa.

Formato do frame

SSE padrão. Cada evento é uma linha data: carregando JSON:

data: {"event":"qr.updated","channel_id":"inst_01J...","qr":"data:image/png;base64,..."}

data: {"event":"channel.connected","channel_id":"inst_01J...","phone_number":"5511..."}

Comentários (linhas :) são enviados a cada 25 segundos como keepalive — a maioria dos reverse-proxies fecha por ociosidade aos 30s. Não faça parse deles.

O que vem na rede

Os mesmos nomes de evento que alimentam os webhooks vêm por este stream:

qr.updated — novo PNG de QR disponível
channel.connected — pareamento concluído
channel.disconnected — sessão encerrada (com reason)
message.received — entrada vinda do WhatsApp
message.sent — ack de saída do WhatsApp
message.delivered — destinatário recebeu
message.failed — falha de envio terminal

A referência completa de payload está em Webhooks → Event payloads. Tanto o stream SSE quanto as entregas de webhook bebem do mesmo barramento de eventos, então os formatos de payload são idênticos.

Quando usar SSE vs webhooks

Quer	Use
App first-party: dashboard, ferramenta interna, sua própria UI	SSE — sem webhook público para manter
Third-party: endpoint HTTPS de outra pessoa	Webhooks — durável, com retentativa, auditado
Ambos	Ambos. Eles não conflitam.

Webhooks são o registro durável (com retentativa, logado, replayable). SSE é o feed ao vivo (best-effort, sem buffer — se você desconectar no meio de um evento, você o perde).