Quick start

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 published Easy API CLI 5.1.0 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.

When authentication succeeds, the runtime can restore this session on a later run using the same session profile. 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.