Pular para o conteúdo principal
Todo evento chega no mesmo envelope. Os campos do topo não mudam; só o data varia por tipo de evento. O payload é normalizado pela Zapfy — não muda quando o engine por trás muda.

​
Envelope

{
  "event": "MESSAGE_RECEIVED",
  "instanceId": "01J9Z...",
  "id": "evt_01J9Z...",
  "timestamp": "2026-06-09T12:34:56.789Z",
  "data": { }
}
​
event
string
Tipo do evento, em UPPER_SNAKE. Um dos valores abaixo.
​
instanceId
string
ID da instância na Zapfy que originou o evento.
​
id
string
ID único do evento. Use como chave de idempotência (a entrega é at-least-once).
​
timestamp
string
Momento da emissão, ISO 8601 (UTC).
​
data
object
Payload específico do evento — descrito abaixo.

​
Tipos de evento

EventoQuando dispara
MESSAGE_RECEIVEDVocê recebeu uma mensagem.
MESSAGE_SENTVocê enviou uma mensagem.
MESSAGE_STATUSUma mensagem foi entregue, lida ou falhou.
CONNECTION_UPDATESeu número conectou ou desconectou.
QRCODE_UPDATEDUm novo QR Code foi gerado para conectar.

​
MESSAGE_RECEIVED / MESSAGE_SENT

{
  "messageId": "3EB0C767D...",
  "chatId": "5511999998888",
  "from": "5511999998888",
  "to": "5511777776666",
  "fromMe": false,
  "pushName": "João Silva",
  "type": "TEXT",
  "timestamp": "2026-06-09T12:34:55Z",
  "text": "Olá, tudo bem?",
  "media": null
}
​
type
string
TEXT · IMAGE · AUDIO · VIDEO · DOCUMENT · STICKER · LOCATION · CONTACT · INTERACTIVE.
​
text
string
Conteúdo de texto. Em mídias, traz a legenda.
​
media
object | null
Presente em mídias: { 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
Presente em FAILED: { code, message }.

​
CONNECTION_UPDATE

{
  "status": "CONNECTED",
  "number": "5511777776666",
  "reason": null
}
​
status
string
CONNECTING · CONNECTED · DISCONNECTED.
​
reason
string | null
Motivo da queda quando DISCONNECTED (ex.: LOGGED_OUT, BANNED).

​
QRCODE_UPDATED

{
  "qr": "data:image/png;base64,iVBOR...",
  "expiresAt": "2026-06-09T12:35:55Z"
}
​
qr
string
QR Code em data URL (PNG base64) para parear o número.
​
expiresAt
string
Expiração do QR, ISO 8601 (UTC).