Event catalog

These event names can appear in the token timeline and can be selected when creating a webhook. The live SSE stream also includes short-lived pairing prompts.

Event	When it fires
`session.created`	A token is created.
`session.deleted`	A token is deleted.
`connection.state`	Token connection state changes.
`auth.qr`	A new pairing QR is generated.
`auth.paired`	WhatsApp is linked to the token.
`message.received`	The connected device receives an inbound message.
`message.sent`	An outgoing message is accepted by WhatsApp.
`message.receipt`	WhatsApp sends a delivery/read receipt.
`message.failed`	An outgoing send fails.
`call.incoming`	A connected token receives an incoming call.
`call.state`	A call changes state, for example ringing, active, or ended.
`call.ended`	A call ends.
`call.error`	A call operation or media stream reports an error.
`call.recording.ready`	A retained WAV recording artifact is ready.
`stanza.error`	WhatsApp returns a protocol-level error.
`stream.failure`	The WhatsApp connection stream fails.

Live SSE only:

Event	When it fires
`auth.pairing_required`	The token is waiting for QR scan or pairing-code entry.
`auth.pairing_code`	A pairing code is available after requesting one.

Event envelope

SSE event data, timeline event data, and webhook data all carry the event-specific fields. Timeline and webhook deliveries also include the event id, type, token id, and creation time in the outer envelope.

{
  "id": "019f...",
  "type": "message.receipt",
  "createdAt": "2026-06-29T17:10:00.000Z",
  "sessionId": "019eff5e-e24e-74ce-a9bb-ccd97e6946b6",
  "data": {
    "messageIds": ["3EB0A1B2C3D4E5F6"],
    "status": "read"
  }
}

Payload notes

connection.state includes a status such as open or close.
auth.qr includes qr, ttlMs, and createdAt.
auth.paired includes meJid.
message.received includes key, timestampSeconds, pushName, and message.
message.sent includes messageId, to, and contentType.
message.receipt includes receipt fields from WhatsApp, commonly message ids and delivery/read status.
message.failed includes to, contentType, and message.
call.* events include call metadata such as callId, peerJid, direction, mediaType, state, and timestamps.
call.recording.ready includes recordingId, kind, contentType, sizeBytes, durationMs, and expiresAt.
stanza.error and stream.failure include protocol or connection error details.

Call events include metadata only. Raw PCM audio is only available on the call media WebSocket.

Get started

Guides

Build with the API

API Reference

Event envelope

Payload notes

​Event envelope

​Payload notes

Event envelope

Payload notes