Receiving messages

Incoming messages arrive on the message event as a WaIncomingMessageEvent.

import type { WaIncomingMessageEvent } from 'zapo-js'

client.on('message', (event: WaIncomingMessageEvent) => {
  // ...
})

The event payload

WaIncomingMessageEvent carries a rich key (a superset of Proto.IMessageKey) plus a few top-level fields. Pass the event (or just its key) verbatim to reply / edit / react / revoke / pin / keep.

Field	Type	Description
`key.remoteJid`	`string`	Deviceless conversation JID (group or 1:1) — the `:device` segment is stripped; the device id is exposed via `key.senderDevice`.
`key.id`	`string`	The message (stanza) id.
`key.fromMe`	`boolean`	True when the message was sent by this account.
`key.participant`	`string?`	The author in groups / broadcasts (omitted in 1:1).
`key.isGroup` / `key.isBroadcast` / `key.isNewsletter`	`boolean`	Chat-kind flags derived from `remoteJid`.
`key.remoteJidAlt`	`string?`	The `remoteJid`’s alternate addressing (PN if addressed by LID, or vice-versa) in 1:1 chats.
`key.participantAlt`	`string?`	The `participant`’s alternate addressing in group chats.
`key.senderDevice`	`number`	Sender’s device id; `0` when the source JID has no `:device` segment.
`key.senderUsername`	`string?`	Author’s handle, without the `@`. Absent on self-authored 1:1 stanzas — the peer’s handle surfaces as `key.recipientUsername` instead.
`key.recipientUsername`	`string?`	Peer’s handle, without the `@`. Populated on self-authored 1:1 stanzas (where `senderUsername` is absent) and on any message that carries `recipient_username` / `peer_recipient_username`.
`key.recipientJid` / `key.recipientAlt`	`string?`	Your receiving JID and its alternate form.
`key.serverId`	`number?`	Server-assigned message id for newsletter / channel messages.
`message`	`Proto.IMessage`	The decrypted message content.
`timestampSeconds`	`number?`	Server timestamp (unix seconds).
`expirationSeconds`	`number?`	Disappearing-message TTL the sender attached to this message, when present.
`pushName`	`string?`	The sender’s display name.

You also receive your own outgoing messages here (multi-device sync), flagged with key.fromMe === true. Filter them out if you only want inbound traffic.

The whole event (or event.key) is accepted as the target for replies/reactions/revokes/pins/keeps and as editKey for edits — no need to reshape it.

Extracting text

A message’s text lives in different fields depending on its type. A small helper covers the common cases:

function extractText(message?: Proto.IMessage | null): string | undefined {
  if (!message) return undefined
  return (
    message.conversation ??
    message.extendedTextMessage?.text ??
    message.imageMessage?.caption ??
    message.videoMessage?.caption ??
    undefined
  )
}

client.on('message', (event) => {
  const text = extractText(event.message)
  if (text) console.log(`${event.pushName}: ${text}`)
})

Identifying the message type

message is a protobuf union — inspect which field is set:

client.on('message', (event) => {
  const m = event.message
  if (!m) return

  if (m.conversation || m.extendedTextMessage) console.log('text')
  else if (m.imageMessage) console.log('image')
  else if (m.videoMessage) console.log('video')
  else if (m.audioMessage) console.log('audio')
  else if (m.documentMessage) console.log('document')
  else if (m.stickerMessage) console.log('sticker')
  else if (m.pollCreationMessage) console.log('poll')
  else if (m.locationMessage) console.log('location')
})

To download media from an image/video/audio/document message, see Media → downloading.

Sending receipts

client.message.sendReceipt marks messages as received/read/played. The easiest form takes the event(s) directly:

client.on('message', async (event) => {
  // mark as read
  await client.message.sendReceipt(event, { type: 'read' })
})

You can also pass an array of events, or address it manually by and ids:

await client.message.sendReceipt(chatJid, [id1, id2], { type: 'read' })

Calls

Read-only Incoming call signaling surfaces as the read-only call event (WaIncomingCallEvent). zapo reports calls — it does not place, accept, or reject them.

client.on('call', (event) => {
  console.log(
    event.type,          // 'offer' | 'accept' | 'terminate' | … | 'unknown'
    event.isVideo ? 'video' : 'voice',
    'from', event.callerPnJid ?? event.callCreatorJid,
    event.groupJid ? `(group ${event.groupJid})` : ''
  )
})

Useful fields: type (the signaling stage), callId, callCreatorJid / callerPnJid (who’s calling), isVideo, groupJid (group calls), and callerPushName. There is no API to answer a call.

Addons

Addons are encrypted follow-ups attached to a message: reactions, poll votes, and comments. They surface as the message_addon event.

Automatic decryption

Addons are decrypted and emitted for you by default — just subscribe to message_addon:

const client = new WaClient({ store, sessionId: 'default' }, logger)

client.on('message_addon', (event) => {
  console.log('addon:', event)
})

Manual decryption

Pass addons: { autoDecrypt: false } to receive the encrypted payload and decrypt on demand from the originating message event:

const client = new WaClient({
  store,
  sessionId: 'default',
  addons: { autoDecrypt: false }
}, logger)

client.on('message', async (event) => {
  await client.message.tryDecryptAddon(event)
})

Recovering unavailable messages

Some <message> stanzas arrive as an <unavailable/> placeholder rather than an encrypted body — a consumed view-once, a hosted or bot message the server could not fan out, or a plain fanout placeholder the primary still holds the plaintext for. All four flavors surface as the message_unavailable event with a kind discriminator. Plain fanout placeholders (kind === 'other') are recoverable: the lib queues a PLACEHOLDER_MESSAGE_RESEND peer request to the primary device, and the recovered payload arrives later as a regular message event with the same key.id. Consumers know to wait for it via resendRequested:

client.on('message_unavailable', (event) => {
  if (event.resendRequested) {
    console.log('waiting for primary to resend', event.key.id)
    // A `message` event with the same key.id will follow (best-effort)
  }
})

The recovery is best-effort — the queued request is not persisted, so a failed peer message is not retried. resendRequested is false for the unrecoverable kinds ('view_once', 'hosted', 'bot'), for stanzas past the server age window (driven by the placeholder_message_resend_maximum_days_limit AB prop, not a hardcoded 30 days), and on mobile-primary sessions (there is no other device to ask). The lib does not time the pending resend out — a real primary can answer past the 30s peer-request default; wa-web behaves the same way.

The retry ladder comes first

A message that fails to decrypt is not handed straight to the placeholder resend. zapo first climbs the Signal retry ladder, because the sender only rebuilds its session once the receipt count goes high enough:

Receipt count	What the sender does
1–2	Re-encrypts on the existing session. Count 2 records the session base key.
3	Compares the base key and, when unchanged, drops the session — the next copy arrives as a `pkmsg` on a fresh one.
4	zapo stops sending retry receipts and delegates to the placeholder resend.

Before 1.8.1 the handoff happened at count 3, which consumed that attempt and suppressed its receipt: the ladder stopped at 2, the peer kept re-encrypting on the same broken session, and the peer-data response came back over it and failed to decrypt too — leaving the message unrecoverable behind a message too far in future error. Moving the handoff to count 4 lets the session rebuild actually happen.

Protocol messages

Edits, revokes, and other protocol-level updates arrive on message_protocol as WaIncomingProtocolMessageEvent (it extends the message event with a protocolMessage field):

client.on('message_protocol', (event) => {
  console.log(event.protocolMessage)
})

Requesting older history

The initial pairing flow streams a bounded window of message history. To pull older messages for a specific chat on demand, call client.message.requestHistorySync:

const { messageId } = await client.message.requestHistorySync({
  chatJid,
  oldestMsgId: topMessage.key.id,
  oldestMsgFromMe: topMessage.key.fromMe,
  oldestMsgTimestampMs: topMessage.timestampSeconds * 1000,
  count: 50
})

The method returns once the request is dispatched — not when the chunk arrives. The backfill is delivered later as a history_sync_chunk event, same as the bootstrap history. Subscribe before calling if you need to react to it:

client.on('history_sync_chunk', (event) => {
  // event.conversations, event.pushnamesCount, event.progress, ...
})

await client.message.requestHistorySync({ chatJid })

Pair oldestMsgId, oldestMsgFromMe, and oldestMsgTimestampMs from the topmost message currently visible to page backwards correctly. Omit count to let the server apply its own default (~50).

Receipts (inbound)

When others read or play your messages, you receive receipt events:

client.on('receipt', (event) => {
  // event.status: 'delivered' | 'read' | 'played' | 'inactive'
  for (const id of event.messageIds) {
    console.log(event.status, 'for', id)
  }
})

event.messageIds is the full set of stanza ids this receipt acknowledges. WhatsApp batches read/delivery receipts into a single <receipt> carrying a <list><item id=…/> block — messageIds mirrors wa-web’s externalIds: list items first, then event.stanzaId appended last. Single-message receipts contain just [event.stanzaId]. WaIncomingReceiptEvent also carries participantUsername?: string — the participant’s handle without the @, read from the stanza’s participant_username attribute when present.

receipt events still expose stanzaId / chatJid directly (they extend WaIncomingBaseEvent); the rename only applies to message, message_addon, and message_bot_chunk payloads, which now use event.key. event.stanzaId is still the last id in the batch — iterate messageIds to cover the rest.

Getting started

Core concepts

Guides

Plugins

Reference

Advanced

Reverse engineering

Receiving messages

The event payload

Extracting text

Identifying the message type

Sending receipts

Calls

Addons

Automatic decryption

Manual decryption

Recovering unavailable messages

The retry ladder comes first

Protocol messages

Requesting older history

Receipts (inbound)

​The event payload

​Extracting text

​Identifying the message type

​Sending receipts

​Calls

​Addons

​Automatic decryption

​Manual decryption

​Recovering unavailable messages

​The retry ladder comes first

​Protocol messages

​Requesting older history

​Receipts (inbound)

The event payload

Extracting text

Identifying the message type

Sending receipts

Calls

Addons

Automatic decryption

Manual decryption

Recovering unavailable messages

The retry ladder comes first

Protocol messages

Requesting older history

Receipts (inbound)