Events

Every event arrives in the same envelope. The top-level fields never change; only data varies by event type. The payload is normalized by Zapfy — it does not change when the underlying connection to WhatsApp changes.

Envelope

{
  "event": "MESSAGE_RECEIVED",
  "instanceId": "01J9Z...",
  "id": "evt_01J9Z...",
  "timestamp": "2026-06-09T12:34:56.789Z",
  "data": { }
}

string

Event type, in UPPER_SNAKE. One of the values below.

string

ID of the Zapfy instance that produced the event.

string

Unique event ID. Use it as an idempotency key (delivery is at-least-once).

string

Emission time, ISO 8601 (UTC).

object

Event-specific payload — described below. The examples that follow show the full event (envelope + data).

Event types

Event	When it fires
`MESSAGE_RECEIVED`	You received a message.
`MESSAGE_SENT`	You sent a message.
`MESSAGE_STATUS`	A message was delivered, read or failed.
`CONNECTION_UPDATE`	Your number connected or disconnected.
`QRCODE_UPDATED`	A new QR Code was generated to connect.

MESSAGE_RECEIVED / MESSAGE_SENT

Message in a contact chat (1:1):

{
  "event": "MESSAGE_RECEIVED",
  "instanceId": "01J9Z...",
  "id": "evt_01J9Z...",
  "timestamp": "2026-06-09T12:34:56.789Z",
  "data": {
    "messageId": "3EB0C767D...",
    "fromMe": false,
    "chat": {
      "jid": "5511999998888@s.whatsapp.net",
      "phone": "5511999998888",
      "isGroup": false,
      "name": null
    },
    "sender": {
      "jid": "5511999998888@s.whatsapp.net",
      "phone": "5511999998888",
      "name": "John Doe"
    },
    "type": "TEXT",
    "text": "Hi, how are you?",
    "media": null
  }
}

Message in a group — chat is the group (phone: null) and sender is the participant who sent it:

{
  "event": "MESSAGE_RECEIVED",
  "instanceId": "01J9Z...",
  "id": "evt_01J9Z...",
  "timestamp": "2026-06-09T12:34:56.789Z",
  "data": {
    "messageId": "3EB0C767D...",
    "fromMe": false,
    "chat": {
      "jid": "120363012345678901@g.us",
      "phone": null,
      "isGroup": true,
      "name": "Family"
    },
    "sender": {
      "jid": "5511999998888@s.whatsapp.net",
      "phone": "5511999998888",
      "name": "John Doe"
    },
    "type": "TEXT",
    "text": "Hey group!",
    "media": null
  }
}

The fields below describe the data object:

string

Message ID on WhatsApp. Reuse it in delete/edit.

boolean

true if you sent it (MESSAGE_SENT); false if you received it.

object

The conversation — the contact or group the message belongs to. This is where you reply.

Show chat

string

Conversation JID (contact …@s.whatsapp.net or group …@g.us). Use it as the recipient to reply.

string | null

Phone in E.164 (digits only) when the conversation is a contact; null for groups.

boolean

true when the conversation is a group.

string | null

Group name; null for contact conversations.

object

Who sent this message. In a contact chat it’s the contact itself; in a group, the participant.

Show sender

string

JID of who sent it. Stable identifier even when the number isn’t available.

string | null

Sender’s phone in E.164; null when WhatsApp anonymizes the sender (@lid).

string | null

Sender’s display name (pushName).

string

TEXT · IMAGE · AUDIO · VIDEO · DOCUMENT · STICKER · LOCATION · CONTACT · INTERACTIVE.

string

Text content. For media, holds the caption.

object | null

Present for media: { mimeType, url, filename, caption }.

MESSAGE_STATUS

Status of a message you sent — data carries chat (same shape), no sender:

{
  "event": "MESSAGE_STATUS",
  "instanceId": "01J9Z...",
  "id": "evt_01J9Z...",
  "timestamp": "2026-06-09T12:35:01Z",
  "data": {
    "messageId": "3EB0C767D...",
    "chat": {
      "jid": "5511999998888@s.whatsapp.net",
      "phone": "5511999998888",
      "isGroup": false,
      "name": null
    },
    "status": "DELIVERED",
    "error": null
  }
}

string

PENDING · SENT · DELIVERED · READ · FAILED.

object | null

Present on FAILED: { code, message }.

CONNECTION_UPDATE

{
  "event": "CONNECTION_UPDATE",
  "instanceId": "01J9Z...",
  "id": "evt_01J9Z...",
  "timestamp": "2026-06-09T12:34:56.789Z",
  "data": {
    "status": "CONNECTED",
    "phone": "5511777776666",
    "reason": null
  }
}

string

CONNECTING · CONNECTED · DISCONNECTED.

string | null

Connected account’s phone number, in E.164. null while there is no session (e.g. CONNECTING or DISCONNECTED).

string | null

Disconnect reason when DISCONNECTED (e.g. LOGGED_OUT, BANNED).

QRCODE_UPDATED

{
  "event": "QRCODE_UPDATED",
  "instanceId": "01J9Z...",
  "id": "evt_01J9Z...",
  "timestamp": "2026-06-09T12:35:55Z",
  "data": {
    "qr": "data:image/png;base64,iVBOR...",
    "expiresAt": "2026-06-09T12:36:55Z"
  }
}

string

QR Code as a data URL (base64 PNG) to pair the number.

string

QR expiration, ISO 8601 (UTC).

Getting started

Webhooks

Envelope

Event types

MESSAGE_RECEIVED / MESSAGE_SENT

MESSAGE_STATUS

CONNECTION_UPDATE

QRCODE_UPDATED

​Envelope

​Event types

​MESSAGE_RECEIVED / MESSAGE_SENT

​MESSAGE_STATUS

​CONNECTION_UPDATE

​QRCODE_UPDATED

Envelope

Event types

MESSAGE_RECEIVED / MESSAGE_SENT

MESSAGE_STATUS

CONNECTION_UPDATE

QRCODE_UPDATED