Quick start

QR pairing is the default login method. Scan the QR code from Linked Devices on your phone to link the account.

This page uses 5.1.0 and describes that version's saved browser profile. For current v5 session files and release status, see the v4-to-v5 migration guide. The change to saved login data does not replace QR pairing.

Before you startCopy Anchor Link

• Node.js 22.21.1 or newer. Install it from nodejs.org, then check with node --version.
• npm or pnpm. The commands below use npx, which is included with npm; use pnpm dlx if pnpm is your package manager.
• A phone that already runs WhatsApp. The guide links that phone to the browser session on your computer; it does not automate the WhatsApp mobile app.
• A terminal. The shell examples are written for Bash-compatible terminals. PowerShell and CMD variants are included where quoting or environment assignment differs.

Prepare your terminal

Open Terminal on macOS/Linux or PowerShell on Windows, change to a folder where you want the session profile saved, and run the command for your shell:

mkdir open-wa-quickstart && cd open-wa-quickstart

Keep this terminal open while the runtime is running. Stop it with Ctrl+C after the session has been tested.

1. Start the Easy APICopy Anchor Link

Run supported 5.1.0 in your terminal. This starts a session called quickstart on port 8080:

npx @open-wa/wa-automate@5.1.0 --session-id quickstart --host 127.0.0.1 --port 8080

The session profile is persisted under _IGNORE_quickstart in the current directory unless you set userDataDir in a config file. --host 127.0.0.1 keeps the API on this computer. The terminal should show the browser starting, then a QR code or another authentication prompt, and the local API address http://localhost:8080. When the dashboard is enabled, open the local dashboard to view the session; use /health below for the explicit readiness fields.

The API process can be listening before WhatsApp authentication completes. Continue to Authenticate, then use /health in Check readiness.

2. Authenticate the sessionCopy Anchor Link

For a QR login, open WhatsApp on the phone that owns the account:

1. Open Settings on iPhone, or Menu then Linked devices on Android.
2. Tap Linked devices and then Link a device.
3. Scan the QR code shown by open-wa in the computer terminal.

The Easy API CLI uses QR authentication. For an embedded Node.js app that requests a link code, follow Link-code login; the computer runs open-wa and generates the code, and the phone enters it in its Linked devices flow.

On later starts, the runtime restores the saved portable session data. Authentication is complete only when the readiness check reports connected: true and session.ready: true.

3. Check readinessCopy Anchor Link

Open the API docs page to discover the running HTTP surface:

http://localhost:8080/api-docs/

That page proves that the HTTP process and docs route respond. It does not prove that WhatsApp is authenticated or that a message can be sent. Check the session separately:

curl http://localhost:8080/health

In Windows PowerShell, use curl.exe for the same request so PowerShell does not resolve its older curl alias:

curl.exe http://localhost:8080/health

After authentication, the response includes these readiness fields:

{
  "status": "ok",
  "connected": true,
  "session": {
    "status": "ready",
    "ready": true,
    "state": "READY",
    "pending": [],
    "blockers": []
  }
}

The complete response also includes launch, patch, license, and reconnection details, including QR data while pairing. /health is public in the current release and does not require or check X-API-Key, so keep the server on loopback or a private network. If connected or session.ready is false, keep the runtime open, finish the QR or link-code flow, and inspect session.pending and session.blockers before trying to send. A page response with HTTP 200 is process liveness, not WhatsApp readiness.

4. Send your first messageCopy Anchor Link

Use a chat ID for a known recipient. Replace 447123456789@c.us with the recipient's full international number followed by @c.us; do not include +, spaces, brackets, or dashes. For a group, use its @g.us ID. If an incoming message gives you a message.from value, reuse that exact ID, including an @lid suffix when the runtime supplies one, instead of converting it to a phone number.

The recipient’s phone should receive the message. That first received message, together with connected: true and session.ready: true, is the end of this onboarding path.

Where next?Copy Anchor Link

• I want to build a bot → Read Messages and events
• I want to connect my CRM → Read Chatwoot integration
• I want AI agents to access WhatsApp → Read MCP integration
• I want to build a plugin → Read Plugin getting started
• I want to deploy to production → Read Security & deployment
• I want to write custom code → Read Custom code

Common next commandsCopy Anchor Link

# Protect with an API key
npx @open-wa/wa-automate@5.1.0 --session-id quickstart --host 127.0.0.1 --port 8080 --api-key "your-secure-key"

# Run a second named session on another port
npx @open-wa/wa-automate@5.1.0 --session-id sales --host 127.0.0.1 --port 8081

For Docker, use the complete Docker baseline with the same explicit WA_* settings; Docker Hub currently publishes only a moving image tag.