Subscribing to events and real-time updates in WA-JS

WA-JS uses an event emitter (backed by EventEmitter2) to surface real-time updates from WhatsApp Web’s internals. Feature modules register listeners on WhatsApp’s internal stores and models, then re-emit normalized events through a single global bus. Your code subscribes to that bus using the WPP.* event methods, without touching any WhatsApp internals directly.

Global event API

All event methods are available directly on window.WPP:

Method	Description
`WPP.on(event, listener)`	Subscribe to an event. Calls `listener` each time the event fires.
`WPP.off(event, listener)`	Unsubscribe a previously registered listener.
`WPP.once(event, listener)`	Subscribe for exactly one invocation, then auto-remove.
`WPP.onAny(listener)`	Subscribe to every event. The first argument to `listener` is the event name.
`WPP.waitFor(event, options?)`	Returns a `Promise` that resolves the next time the event fires.
`WPP.many(event, n, listener)`	Subscribe for exactly `n` invocations, then auto-remove.
`WPP.listenerCount(event)`	Return the number of listeners for an event.
`WPP.removeAllListeners(event?)`	Remove all listeners for an event (or all events if omitted).

Connection events

Connection events are emitted on the conn.* namespace and reflect WhatsApp Web’s internal stream state. They fire immediately with the current value when you subscribe, and again whenever the value changes.

`conn.stream_mode_changed`

Fired when the high-level connection mode changes. The callback receives a StreamMode string.

WPP.on('conn.stream_mode_changed', function (mode) {
  console.log('Stream mode:', mode);
});

StreamMode values

Mode	When it appears
`QR`	QR code is displayed, waiting for phone scan
`MAIN`	Main interface loaded; authenticated and ready
`SYNCING`	Syncing messages and data after login
`OFFLINE`	Connection is offline
`CONFLICT`	Login conflict detected (same account opened elsewhere)
`PROXYBLOCK`	Connection blocked by a proxy
`TOS_BLOCK`	Account blocked for Terms of Service violation
`SMB_TOS_BLOCK`	Business account blocked for Terms of Service violation
`DEPRECATED_VERSION`	The running WhatsApp Web version is no longer supported

`conn.stream_info_changed`

Fired when the low-level connection state changes. The callback receives a StreamInfo string.

WPP.on('conn.stream_info_changed', function (info) {
  console.log('Stream info:', info);
});

StreamInfo values

Info	Meaning
`OFFLINE`	No network connection
`OPENING`	TCP/WebSocket connection being established
`PAIRING`	Pairing handshake in progress
`SYNCING`	Downloading message history
`RESUMING`	Resuming a previous session
`CONNECTING`	Connecting to the WhatsApp server
`NORMAL`	Fully connected and operational

Other connection events

Event	Payload	Description
`conn.authenticated`	`undefined`	Fired after a successful QR code scan
`conn.logout`	`undefined`	Fired when the session is logged out
`conn.logout_reason`	`LogoutReason`	Reason code for the logout
`conn.main_init`	`undefined`	Interface is beginning to boot
`conn.main_loaded`	`undefined`	Main interface loaded but still syncing
`conn.main_ready`	`undefined`	Authenticated and ready to send messages
`conn.online`	`boolean`	`true` when online, `false` when offline
`conn.require_auth`	`undefined`	Authentication is required (QR scan)
`conn.qrcode_idle`	`undefined`	QR code timed out without a scan
`conn.needs_update`	`undefined`	WhatsApp Web version update required

Chat events

Chat events are emitted on the chat.* namespace whenever messages, reactions, or read state changes occur.

`chat.new_message`

Fired whenever a new message is added to any chat. The payload is a MsgModel instance.

WPP.on('chat.new_message', function (msg) {
  console.log('From:', msg.from.toString());
  console.log('Body:', msg.body);
  console.log('Is group:', msg.isGroupMsg);
  console.log('Is from me:', msg.id.fromMe);
});

Other chat events

Event	Payload	Description
`chat.new_chat`	`ChatModel`	A new chat was created
`chat.active_chat`	`ChatModel \| null`	The currently open chat changed
`chat.msg_revoke`	`{ id, refId, from, to, type }`	A message was deleted (`revoke`, `sender_revoke`, or `admin_revoke`)
`chat.msg_ack_change`	`{ ack, ids, chat, sender? }`	Message delivery/read acknowledgement changed
`chat.msg_edited`	`{ chat, id, msg }`	A message was edited
`chat.new_reaction`	`{ id, msgId, reactionText, sender, … }`	A reaction was added or removed
`chat.unread_count_changed`	`{ chat, unreadCount, previousUnreadCount }`	Unread count updated
`chat.presence_change`	`{ id, isOnline, state, … }`	Contact typing/online presence changed
`chat.poll_response`	`{ msgId, chatId, selectedOptions, sender }`	A poll vote was received
`chat.update_label`	`{ chat, ids, labels, type }`	Labels added or removed from a chat

Code examples

WPP.loader.onReady(function () {
  // Check the current mode immediately
  const data = WPP.conn.getStreamData();

  if (data.mode === 'MAIN') {
    startMyBot();
  } else {
    // React when it changes
    WPP.once('conn.stream_mode_changed', function (mode) {
      if (mode === 'MAIN') {
        startMyBot();
      }
    });
  }
});

function startMyBot() {
  WPP.on('chat.new_message', function (msg) {
    if (!msg.id.fromMe && msg.body === 'ping') {
      WPP.chat.sendTextMessage(msg.from.toString(), 'pong');
    }
  });
}

Key events reference

Event	Payload type	When it fires
`conn.stream_mode_changed`	`StreamMode` string	Connection mode changes (QR, MAIN, OFFLINE, …)
`conn.stream_info_changed`	`StreamInfo` string	Low-level socket state changes
`conn.authenticated`	`undefined`	Successful QR scan
`conn.main_ready`	`undefined`	Fully authenticated and ready to send
`conn.online`	`boolean`	Network connectivity changes
`conn.logout`	`undefined`	Session logged out
`chat.new_message`	`MsgModel`	Any new incoming or outgoing message
`chat.msg_revoke`	`object`	Message deleted by sender or admin
`chat.new_reaction`	`object`	Reaction added or removed from a message
`chat.presence_change`	`object`	Contact typing indicator or online status

Use WPP.waitFor(event) when you need a one-time async pattern — for example, waiting for the first authenticated event before proceeding. It returns a Promise that resolves with the event payload, so you can await it directly without managing listener cleanup yourself:

WPP.loader.onReady(async function () {
  if (!WPP.conn.isAuthenticated()) {
    // Block until QR is scanned
    await WPP.waitFor('conn.authenticated');
  }
  console.log('Session is authenticated');
});

Get Started

Core Concepts

Guides

Subscribing to events and real-time updates in WA-JS

Global event API

Connection events

`conn.stream_mode_changed`

`conn.stream_info_changed`

Other connection events

Chat events

`chat.new_message`

Other chat events

Code examples

Key events reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​Global event API

​Connection events

​conn.stream_mode_changed

​conn.stream_info_changed

​Other connection events

​Chat events

​chat.new_message

​Other chat events

​Code examples

​Key events reference

Build docs developers (and LLMs) love

Global event API

Connection events

`conn.stream_mode_changed`

`conn.stream_info_changed`

Other connection events

Chat events

`chat.new_message`

Other chat events

Code examples

Key events reference