Eventos

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 a conexão com o WhatsApp muda.

Envelope

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

string

Tipo do evento, em UPPER_SNAKE. Um dos valores abaixo.

string

ID da instância na Zapfy que originou o evento.

string

ID único do evento. Use como chave de idempotência (a entrega é at-least-once).

string

Momento da emissão, ISO 8601 (UTC).

object

Payload específico do evento — descrito abaixo. Os exemplos a seguir mostram o evento completo (envelope + data).

Tipos de evento

Evento	Quando dispara
`MESSAGE_RECEIVED`	Você recebeu uma mensagem.
`MESSAGE_SENT`	Você enviou uma mensagem.
`MESSAGE_STATUS`	Uma mensagem foi entregue, lida ou falhou.
`CONNECTION_UPDATE`	Seu número conectou ou desconectou.
`QRCODE_UPDATED`	Um novo QR Code foi gerado para conectar.

MESSAGE_RECEIVED / MESSAGE_SENT

Mensagem em conversa de contato (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": "João Silva"
    },
    "type": "TEXT",
    "text": "Olá, tudo bem?",
    "media": null
  }
}

Mensagem em grupo — chat é o grupo (phone: null) e sender é o participante que enviou:

{
  "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": "Família"
    },
    "sender": {
      "jid": "5511999998888@s.whatsapp.net",
      "phone": "5511999998888",
      "name": "João Silva"
    },
    "type": "TEXT",
    "text": "Olá grupo!",
    "media": null
  }
}

Os campos abaixo descrevem o objeto data:

string

ID da mensagem no WhatsApp. Reaproveite em delete/edit.

boolean

true se foi você quem enviou (MESSAGE_SENT); false se recebeu.

object

A conversa — o contato ou grupo onde a mensagem está. É aqui que você responde.

Mostrar chat

string

JID da conversa (contato …@s.whatsapp.net ou grupo …@g.us). Use como destinatário pra responder.

string | null

Telefone em E.164 (só dígitos) quando a conversa é um contato; null em grupo.

boolean

true quando a conversa é um grupo.

string | null

Nome do grupo; null em conversa de contato.

object

Quem enviou esta mensagem. Em conversa de contato é o próprio contato; em grupo, o participante.

Mostrar sender

string

JID de quem enviou. Identificador estável mesmo quando o número não está disponível.

string | null

Telefone do remetente em E.164; null quando o WhatsApp anonimiza o remetente (@lid).

string | null

Nome de exibição (pushName) do remetente.

string

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

string

Conteúdo de texto. Em mídias, traz a legenda.

object | null

Presente em mídias: { mimeType, url, filename, caption }.

MESSAGE_STATUS

Status de uma mensagem que você enviou — data traz chat (mesma forma), sem 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

Presente em 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

Número da conta conectada, em E.164. null enquanto não há sessão (ex.: CONNECTING ou DISCONNECTED).

string | null

Motivo da queda quando DISCONNECTED (ex.: 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 em data URL (PNG base64) para parear o número.

string

Expiração do QR, ISO 8601 (UTC).

Início

Webhooks

Envelope

Tipos de evento

MESSAGE_RECEIVED / MESSAGE_SENT

MESSAGE_STATUS

CONNECTION_UPDATE

QRCODE_UPDATED

​Envelope

​Tipos de evento

​MESSAGE_RECEIVED / MESSAGE_SENT

​MESSAGE_STATUS

​CONNECTION_UPDATE

​QRCODE_UPDATED

Envelope

Tipos de evento

MESSAGE_RECEIVED / MESSAGE_SENT

MESSAGE_STATUS

CONNECTION_UPDATE

QRCODE_UPDATED