Session events

Import ev when your application needs process-level lifecycle events. Use client listeners such as client.onMessage for WhatsApp messages after the session is ready.

import { ev } from '@open-wa/wa-automate';

ev.on('client.ready', ({ sessionId }) => {
  console.log(`Session ${sessionId} is ready`);
});

ev.on('session.connection.disconnected', ({ details }) => {
  console.warn('Session disconnected', details?.reason);
});

client.ready follows authentication and runtime finalization. For Easy API, also check /health and wait for both connected: true and session.ready: true before sending; HTTP liveness alone does not establish WhatsApp readiness. See the readiness guide.

Authentication eventsCopy Anchor Link

The core event map reports QR generation as a StepEvent; the QR is in event.details.qr. This value is a credential for pairing. The CLI renders the QR in its local terminal, while Easy API exposes QR state through /health and /qr; keep those responses on a private network.

ev.on('launch.auth.qr.generated', (event) => {
  const qr = event.details?.qr;
  if (!qr) return;

  // Render only inside a trusted local pairing UI. Do not log or forward it.
  showInPrivatePairingUi(qr);
});

showInPrivatePairingUi stands for your own trusted local UI. The runtime does not provide that helper.

The embedded runtime emits launch.auth.linkCode.generated with the code in event.details.linkCode; this event is sensitive, and the plugin gateway blocks it. The published Easy API CLI does not forward linkCode or print the generated event, so use its QR flow. Do not relay link codes through plugins, logs, webhooks, or shared telemetry. /api/events streams runtime events behind the Easy API key and network boundary; do not expose that endpoint publicly. See Easy API security.

Event payloadsCopy Anchor Link

Lifecycle events such as launch.auth.qr.generated use a common step shape with a correlation ID, timestamp, step name, and optional details or error. For exact payloads and available names, use the generated event reference.

type StepEvent<Details> = {
  correlationId: string;
  ts: number;
  step: string;
  details?: Details;
  error?: { name: string; message: string; stack?: string };
  durationMs?: number;
};

Some legacy event names in older examples, including qr.** and sessionData.**, are not the current core event names. Use the names and payloads in the generated reference for the package version you run.