Events

WhatsmeowClient extends EventEmitter and emits typed events. The whatsmeow events listed below are forwarded.

note

Many upstream whatsmeow events are not forwarded yet — for example app-state sync events (mute, pin, archive), newsletter live updates, blocklist/privacy setting changes, PairSuccess and UndecryptableMessage.

Usage

client.on("message", ({ info, message }) => { /* ... */ });
client.on("connected", ({ jid }) => { /* ... */ });

Connection Events

Event	Payload	Description
connected	{ jid: string }	WhatsApp connection established. Safe to send messages.
disconnected	{}	Connection lost. Auto-reconnect is automatic.
logged_out	{ reason: string }	Session revoked. Must re-pair.
stream_error	{ code: string }	Protocol error. Usually followed by auto-reconnect.
temporary_ban	{ code: string, expire: string }	Temporary ban from WhatsApp.
stream_replaced	{}	Another client connected with the same session. whatsmeow stops and does not reconnect; run one process per store.
client_outdated	{}	WhatsApp rejected the client version (405). whatsmeow does not reconnect; update whatsmeow-node.
connect_failure	{ code: number, reason: string, message: string }	Connection refused for a reason whatsmeow doesn't handle. It does not reconnect.
keep_alive_timeout	{ errorCount: number }	Keep-alive pings failing. Connection may be degraded.
keep_alive_restored	{}	Keep-alive recovered. Connection is healthy.

Message Events

Event	Payload	Description
message	{ info: MessageInfo, message: Record<string, unknown> }	New message received.
message:receipt	{ type: string, chat: string, sender: string, isGroup: boolean, ids: string[], timestamp: number }	Read/delivery receipt.

MessageInfo

interface MessageInfo {
  id: string;
  chat: string;      // JID of the chat
  sender: string;    // JID of the sender
  isFromMe: boolean;
  isGroup: boolean;
  timestamp: number;  // Unix timestamp
  pushName: string;   // Sender's display name
}

Presence Events

Event	Payload	Description
presence	{ jid: string, presence: "available" | "unavailable", lastSeen?: number }	Contact online/offline status.
chat_presence	{ chat: string, sender: string, state: "composing" | "paused", media: "audio" | "" }	Typing/recording indicator.

Group Events

Event	Payload	Description
group:info	GroupInfoEvent	Group metadata changed.
group:joined	{ jid: string, name: string }	You joined a group.

GroupInfoEvent

interface GroupInfoEvent {
  jid: string;
  name?: string;         // New group name
  description?: string;  // New description
  announce?: boolean;     // Announcement mode changed
  locked?: boolean;       // Lock status changed
  ephemeral?: boolean;    // Disappearing messages changed
  join?: string[];        // JIDs that joined
  leave?: string[];       // JIDs that left
  promote?: string[];     // JIDs promoted to admin
  demote?: string[];      // JIDs demoted from admin
}

Media Events

Event	Payload	Description
picture	{ jid: string, remove: boolean, pictureId?: string }	Profile/group picture changed.

Call Events

Event	Payload	Description
call:offer	{ from: string, callId: string }	Incoming call.
call:accept	{ from: string, callId: string }	Call accepted.
call:terminate	{ from: string, callId: string, reason: string }	Call ended.

Other Events

Event	Payload	Description
identity_change	{ jid: string, timestamp: number }	Contact's identity key changed (re-registered).
history_sync	{ type, chunkOrder, progress, conversations: { id, name, unreadCount, messages }[] }	History sync chunk. conversations[].messages use the same { info, message } shape as message events. Initial syncs can be large.
qr	{ code: string }	QR code for pairing.
qr:timeout	null	QR pairing timed out.
qr:error	{ event: string }	QR channel error.
log	{ level: string, msg: string, [key: string]: unknown }	Go binary log output. Useful for debugging.
error	Error	Internal error.
exit	{ code: number | null }	Go binary exited.