Skip to main content
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 engine changes.

​
Envelope

{
  "event": "MESSAGE_RECEIVED",
  "instanceId": "01J9Z...",
  "id": "evt_01J9Z...",
  "timestamp": "2026-06-09T12:34:56.789Z",
  "data": { }
}
​
event
string
Event type, in UPPER_SNAKE. One of the values below.
​
instanceId
string
ID of the Zapfy instance that produced the event.
​
id
string
Unique event ID. Use it as an idempotency key (delivery is at-least-once).
​
timestamp
string
Emission time, ISO 8601 (UTC).
​
data
object
Event-specific payload — described below.

​
Event types

EventWhen it fires
MESSAGE_RECEIVEDYou received a message.
MESSAGE_SENTYou sent a message.
MESSAGE_STATUSA message was delivered, read or failed.
CONNECTION_UPDATEYour number connected or disconnected.
QRCODE_UPDATEDA new QR Code was generated to connect.

​
MESSAGE_RECEIVED / MESSAGE_SENT

{
  "messageId": "3EB0C767D...",
  "chatId": "5511999998888",
  "from": "5511999998888",
  "to": "5511777776666",
  "fromMe": false,
  "pushName": "John Doe",
  "type": "TEXT",
  "timestamp": "2026-06-09T12:34:55Z",
  "text": "Hi, how are you?",
  "media": null
}
​
type
string
TEXT · IMAGE · AUDIO · VIDEO · DOCUMENT · STICKER · LOCATION · CONTACT · INTERACTIVE.
​
text
string
Text content. For media, holds the caption.
​
media
object | null
Present for media: { mimeType, url, filename, caption }.

​
MESSAGE_STATUS

{
  "messageId": "3EB0C767D...",
  "chatId": "5511999998888",
  "status": "DELIVERED",
  "timestamp": "2026-06-09T12:35:01Z",
  "error": null
}
​
status
string
PENDING · SENT · DELIVERED · READ · FAILED.
​
error
object | null
Present on FAILED: { code, message }.

​
CONNECTION_UPDATE

{
  "status": "CONNECTED",
  "number": "5511777776666",
  "reason": null
}
​
status
string
CONNECTING · CONNECTED · DISCONNECTED.
​
reason
string | null
Disconnect reason when DISCONNECTED (e.g. LOGGED_OUT, BANNED).

​
QRCODE_UPDATED

{
  "qr": "data:image/png;base64,iVBOR...",
  "expiresAt": "2026-06-09T12:35:55Z"
}
​
qr
string
QR Code as a data URL (base64 PNG) to pair the number.
​
expiresAt
string
QR expiration, ISO 8601 (UTC).