Quick start

Follow these steps to start a local API, connect a WhatsApp account, and send one test message.

Prerequisites

Node.js >= 22.21.1, this is required. The library will not work on older versions. Check with node --version.
npm or pnpm, any package manager works, but pnpm is used for repo development.
A WhatsApp account on a linked phone, this automates WhatsApp Web, not the mobile app.

Start the Easy API

Run the CLI to start a local WhatsApp API:

npx @open-wa/wa-automate --port 8080

These examples pin port 8080 for consistency. If you omit --port, the current v5 CLI uses port 8002.

You should see terminal output showing:

The browser launching
A QR code appearing in the terminal
The local API address (usually http://localhost:8080)

Authenticate

The runtime will display a QR code in your terminal. Open WhatsApp on your phone:

Tap Menu or Settings
Tap Linked Devices
Tap Link a Device
Scan the QR code in your terminal

Alternatively, if you know the host account number, use Link-code login to avoid QR scanning.

Once authenticated, the terminal will show the session is connected and the API is ready.

Verify the API is running

Open your browser to:

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

This is the interactive API documentation for your live session. If this page loads, your session is up, the API is reachable, and you can discover all available methods.

Other useful endpoints:

http://localhost:8080/meta/swagger.json, OpenAPI schema
http://localhost:8080/meta/postman.json, Postman collection

Send your first message

Open http://localhost:8080/api-docs/
Find the sendText method
Enter a chat ID (your own number in format 1234567890@c.us)
Enter a message body
Execute the request

curl -X POST http://localhost:8080/api/sendText \
  -H "Content-Type: application/json" \
  -d '{"to": "1234567890@c.us", "text": "Hello from open-wa!"}'

If you started the API with --api-key "your-secure-key", include it in the header:

curl -X POST http://localhost:8080/api/sendText \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secure-key" \
  -d '{"to": "1234567890@c.us", "text": "Hello from open-wa!"}'

You should receive the message on your phone within seconds.

Expected API result, illustrative and abbreviated. The Easy API wraps method results in data; for sendText, that value is the sent message id string:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "data": "true_1234567890@c.us_EXAMPLE"
}

Auth failure result, illustrative and abbreviated:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Unauthorized"
}

If the API is protected and the key is missing or wrong, expect an authentication error instead of a message send. Add the same X-API-Key value that you used when starting the runtime, then retry the request. Once the send succeeds, keep the API key on every client request and move to the guide that matches your next use case below.

Where next?

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 commands

# Protect with an API key
npx @open-wa/wa-automate --port 8080 --api-key "your-secure-key"

# Run a named session
npx @open-wa/wa-automate --session-id sales --port 8081

# For source-backed webhook delivery in the current v5 alpha,
# load @open-wa/integration-webhook from wa.config.* instead of relying on --webhook.

Was this helpful?

Wally and his cute companion coffee mug are coding day and night to keep this up-to-date!