Authentication and session recovery

open-wa automates WhatsApp Web through a browser driver. On first launch, scan the QR code with WhatsApp's Linked Devices screen and keep the runtime running until authentication and client readiness complete. The quick start shows the complete first message path.

Pair a sessionCopy Anchor Link

The Easy API CLI's QR is rendered in its local terminal. The current published @open-wa/wa-automate@5.1.0 CLI does not forward link-code configuration, so use QR pairing with that CLI. In an embedded application, set createClient's linkCode to the phone's full international number using digits only, then listen for launch.auth.linkCode.generated before calling client.start(); read the code from event.details.linkCode. Follow the complete link-code login flow, which covers the phone steps and keeps the generated code in the local terminal.

For the published CLI, see Easy API setup and configuration options before starting. Do not print link codes or QR values to shared logs, webhooks, or support tools.

Persist the sessionCopy Anchor Link

The browser profile holds WhatsApp authentication state. The runtime derives a profile directory from the session ID by default; set userDataDir when you need a specific path and keep that directory private, persistent, and unique to the session.

const runtime = await createClient({
  sessionId: 'support',
  userDataDir: './private/sessions/support',
  driver: new PuppeteerDriver(),
});

Set restrictive file permissions on the profile, exclude it from version control and backups shared across accounts, and protect it like a credential. Setting ephemeral: true uses a temporary profile that is discarded when the process exits, so the next run may require pairing again.

Check readinessCopy Anchor Link

An HTTP response from /health means the Easy API process answered. Wait until its connected and session.ready fields are both true before sending messages. The current /health response can include QR and diagnostic data and is public, so keep it on loopback or a private network.

curl -sS http://127.0.0.1:8080/health

See health and readiness for the expected fields and recovery diagnostics. A process restart does not prove that WhatsApp reconnected; check readiness again after every restart.

Recover a sessionCopy Anchor Link

If the browser or Node process exits, restart with the same session ID and profile directory. The runtime attempts to restore authentication from that profile. If WhatsApp logged the device out, the profile is missing or damaged, or authentication times out, pair again and investigate the session state before retrying application work.

If you suspect that someone copied the profile, log out the linked device from WhatsApp, stop the runtime, replace the profile, and authenticate a new session. Do not delete a profile as a routine recovery step because it removes the saved authentication state.

Runtime eventsCopy Anchor Link

Use client.ready for the point at which the client can accept commands and session.connection.disconnected to observe a later disconnect. QR and link-code lifecycle events contain authentication material; see the session events guide for the safe event surface.

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

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

RelatedCopy Anchor Link

• Easy API setup for CLI installation and API-key configuration
• Security and deployment for network and credential boundaries
• Detect logouts for connection-state recovery