Events

Everything that happens on your WhatsApp connection — new messages, button taps, group changes, calls, the QR code — is delivered to your code as a typed event. You subscribe with client.on(name, handler), and zaileys hands your handler a fully-typed payload for that specific event.

import { Client } from 'zaileys'
 
const client = new Client()
 
client.on('qr', ({ qrString }) => console.log('Scan QR:', qrString))
client.on('connect', ({ me }) => console.log('Connected as', me.id))
 
client.on('text', async (msg) => {
  console.log(msg.senderId, '|', msg.text)
  await msg.reply(`You said: ${msg.text}`)
})

Subscribing & unsubscribing

client.on returns an unsubscribe function. Call it to stop listening. There is also client.off(name, handler) if you kept a reference to the original handler.

// on() returns a disposer
const stop = client.on('text', (msg) => console.log(msg.text))
stop() // remove this listener later
 
// or remove by reference
const handler = (msg: MessageContext) => console.log(msg.text)
client.on('text', handler)
client.off('text', handler)

The Client is a typed event emitter (TypedEventEmitter<ClientEventMap>), where ClientEventMap is the union of connection lifecycle events and inbound message events. See Client for the full constructor and connect() / disconnect() API.

Event catalog

Connection lifecycle

These fire as your session connects, authenticates, and (occasionally) drops. Every payload carries the sessionId of the client.

Inbound messages

These deliver a rich message context object — the same shape across every message type. The media accessor is populated only for media kinds.

Message mutations

Interactive replies

See Interactive Messages for how to send buttons, lists, templates, and carousels.

Groups

Calls, presence, lifecycle

Connection events in depth

client.on('qr', ({ qrString, expiresAt }) => {
  console.log('Scan this QR:', qrString)
  console.log('Expires at:', new Date(expiresAt).toLocaleTimeString())
})

client.on('connect', async ({ sessionId, me }) => {
  console.log(`[${sessionId}] connected as ${me.id}${me.name ? ` (${me.name})` : ''}`)
})

client.on('disconnect', ({ reason, willReconnect }) => {
  console.log('Disconnected:', reason, willReconnect ? '(reconnecting…)' : '(stopped)')
})

For pairing-code login instead of QR, listen for pairing-code:

const client = new Client({ authType: 'pairing', phoneNumber: '628xxxxxxxxxx' })
client.on('pairing-code', ({ code }) => console.log('Enter on phone:', code))

The reconnecting event lets you observe backoff before the retry actually happens:

client.on('reconnecting', ({ attempt, delayMs, reason }) => {
  console.log(`Reconnect #${attempt} in ${delayMs}ms (was: ${reason})`)
})

The auth-exhausted event fires once the authGuard budget is spent — the client has emitted maxQrAttempts QR codes (default 5) or made maxPairingAttempts pairing requests (default 3) without completing login. At that point zaileys stops: it tears the socket down and will not auto-retry. This is deliberate — endlessly regenerating a QR / pairing code is exactly what spams WhatsApp into restricting the account. To retry, call connect() again (which resets the budget); but first investigate why auth never completed (wrong phone number, QR never scanned, network never staying up):

client.on('auth-exhausted', ({ kind, attempts, max }) => {
  console.error(`auth-exhausted: gave up after ${attempts}/${max} ${kind} attempt(s)`)
  // fix the underlying cause, then re-arm the budget:
  // await client.connect()
})

The message context

Every message event (text, image, video, audio, document, sticker, mention, mention-all) hands your handler a MessageContext — a single object with all the metadata plus action methods (reply, react, replied, …). This is the workhorse object of zaileys.

client.on('text', async (msg) => {
  console.log(msg.senderId)   // "628xxxxxxxxxx"
  console.log(msg.senderName) // "Andi" | null
  console.log(msg.text)       // "hello"
  console.log(msg.isGroup)    // false
  await msg.reply('Hi!')      // quoted reply
  await msg.react('👍')        // react to the message
})

Identity & routing fields

Content fields

Boolean flags

All of these are plain boolean fields you can branch on directly.

Methods

reply() — quoted text reply

client.on('text', async (msg) => {
  // plain quoted reply
  await msg.reply(`Echo: ${msg.text}`)
 
  // rich reply (markdown + suggestions) — see /rich-responses
  await msg.reply(
    ['*Rich reply* ✨', '', '```ts', 'const x = 1', '```'].join('\n'),
    { rich: true, title: '🤖 zaileys' },
  )
})

react() — emoji reaction

client.on('text', async (msg) => {
  await msg.react('👀') // acknowledge receipt
})

replied() — look up the quoted message

Resolves the message this one was a reply to, as a full MessageContext. Great for context-aware bots (“reply to my message to translate it”).

client.on('text', async (msg) => {
  const quoted = await msg.replied()
  if (quoted) {
    console.log('In reply to:', quoted.senderId, '|', quoted.text)
    await msg.reply(`You quoted: "${quoted.text}"`)
  }
})

media — download attachments

On image / video / audio / document / sticker events, msg.media exposes a buffer() and a stream():

import { writeFile } from 'node:fs/promises'
 
client.on('image', async (msg) => {
  console.log('caption:', msg.text)
  if (!msg.media) return
  const buf = await msg.media.buffer()
  await writeFile('received.jpg', buf)
})

See Media for streaming, MIME handling, and re-uploading.

citation — author / banned checks

If you configured citation in client options, these predicates tell you whether the sender qualifies.

client.on('text', async (msg) => {
  if (await msg.citation.banned()) return            // ignore banned users
  if (!(await msg.citation.authors())) return         // owner-only command
  await msg.reply('Welcome, author!')
})

Mention context

The mention event extends MessageContext with the JIDs mentioned and your own JID; mention-all additionally flags isMentionAll and may include group members.

client.on('mention', async (msg) => {
  if (msg.mentionedJids.includes(msg.selfJid)) {
    await msg.reply('You tagged me!')
  }
})
 
client.on('mention-all', async (msg) => {
  console.log('Tagged everyone in', msg.roomId, 'members:', msg.members?.length)
})

Interactive events in depth

When you send buttons or lists (see Interactive Messages), taps come back as button-click and list-select. These carry the original message key, the selected id, and the sender — not a full message context.

client.on('button-click', (ctx) => {
  console.log('button:', ctx.buttonId, '|', ctx.buttonText, '| from', ctx.sender.jid)
  if (ctx.buttonId === 'yes') {
    client.send(ctx.sender.jid).text('You tapped Yes ✅')
  }
})
 
client.on('list-select', (ctx) => {
  console.log('row:', ctx.rowId, '|', ctx.title, '| from', ctx.sender.jid)
})

Type-safe handlers

Because on is generic over the event name, payloads are inferred automatically — but you can also import the payload types for standalone handler functions.

import { Client } from 'zaileys'
import type {
  MessageContext,
  ButtonClickPayload,
} from 'zaileys'
 
const onText = (msg: MessageContext): void => {
  console.log(msg.senderId, msg.text)
}
 
const onButton = (ctx: ButtonClickPayload): void => {
  console.log(ctx.buttonId)
}
 
const client = new Client()
client.on('text', onText)
client.on('button-click', onButton)

Filtering inbound messages

zaileys does not expose middleware on raw events, but two mechanisms control what you receive:

ignoreMe — drop your own outgoing messages before they reach handlers. Set it in client options.

const client = new Client({ ignoreMe: true })
client.on('text', (msg) => {
  // msg.isFromMe is never true here when ignoreMe is set
})

Branch inside the handler — the flags and citation predicates on the context are your filter toolkit.

const OWNER = '628xxxxxxxxxx'
 
client.on('text', async (msg) => {
  if (msg.isFromMe) return                              // ignore self
  if (msg.isGroup) return                               // private chats only
  if (msg.senderId.replace(/\D/g, '') !== OWNER) return // owner only
  await msg.react('👀')
  await msg.reply(`Echo: ${msg.text}`)
})

For prefix-based command routing instead of manual branching, use client.command(...) — see Commands and Automation.

Tips & gotchas

Related

• Client — constructor, options, connect() / disconnect()
• Interactive Messages — sending the buttons and lists that produce button-click / list-select
• Commands — prefix-based routing on top of the text event
• Media — downloading and re-sending attachments
• Configuration — ignoreMe, citation, qrTerminal, authType, reconnect tuning
• Error Handling — disconnect reasons and reconnection behavior