Events (SSE)

A single-direction Server-Sent Events stream for live state. Use it instead of polling for QR codes, instance state changes, and message activity.

Endpoint

Authenticate via Authorization: Bearer … or ?token=… query string. (Browser EventSource can't set headers; the query-token path is for that case.)

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

For browser code specifically, EventSource is the cleanest path because it handles reconnection for you:

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

Filtering

By default you get every event for every instance the API key can see. Narrow with query params:

Server-side filtering means you don't pay the bandwidth on stuff you don't care about.

Frame format

Standard SSE. Each event is a data: line carrying JSON:

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

data: {"event":"instance.connected","instance_id":"inst_01J...","phone_number":"5511..."}

Comments (: lines) are sent every 25 seconds as a keepalive — most reverse-proxies idle-close at 30s. Don't parse them.

What's on the wire

The same event names that power webhooks come down this stream:

• qr.updated — new QR PNG available
• instance.connected — pairing complete
• instance.disconnected — session ended (with reason)
• message.received — inbound from WhatsApp
• message.sent — outbound ack from WhatsApp
• message.delivered — recipient received
• message.failed — terminal send failure

The full payload reference is at Webhooks → Event payloads. Both the SSE stream and webhook deliveries draw from the same event bus, so payload shapes are identical.

When to use SSE vs webhooks

Webhooks are the durable record (retried, logged, replayable). SSE is the live feed (best-effort, no buffering — if you disconnect mid-event, you lose it).