Easy API quick start

Use this page when you want a local HTTP API before writing embedded Node.js code. The npm registry reported @open-wa/wa-automate@5.1.0 as latest on 2026-09-29.

Run itCopy Anchor Link

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

The published 5.1.0 CLI defaults to 0.0.0.0:8002; set both flags to keep a local setup on loopback at port 8080. The session profile is persisted under ./_IGNORE_sales unless you set userDataDir in a config file.

The process may expose HTTP routes before WhatsApp authentication finishes. Follow the Quick start pairing steps, then use /health to confirm readiness.

Check the API and session separatelyCopy Anchor Link

The interactive docs route proves that the HTTP surface responds:

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

It does not prove that the WhatsApp session is authenticated. Check the session:

curl http://localhost:8080/health

Proceed with messaging only when the response contains "connected": true and "session": { "ready": true }. If readiness is false, inspect session.pending and session.blockers, complete QR authentication, and check again. Link-code login is supported through embedded createClient in 5.1.0; the published Easy API CLI uses QR authentication.

Protect the API with a keyCopy Anchor Link

Pass a key explicitly at startup and send the same value in X-API-Key on protected requests:

npx @open-wa/wa-automate@5.1.0 \
  --host 127.0.0.1 \
  --session-id sales \
  --port 8080 \
  --api-key "your-secure-key"

curl http://localhost:8080/api/session/getConnectionState \
  -H "X-API-Key: your-secure-key"

This calls the protected getConnectionState method. The CLI accepts --api-key, --key, and -k; a bare key flag does not generate a secret. /health is public and may include QR and diagnostic data, so keep the bind address private and do not expose that route through a public proxy. Keep the key and session profile private.

Common flagsCopy Anchor Link

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

# Bind to a host explicitly when a reverse proxy or container needs it
npx @open-wa/wa-automate@5.1.0 --session-id sales --host 0.0.0.0 --port 8080

# Use a config file for plugins or other structured settings
npx @open-wa/wa-automate@5.1.0 --config ./wa.config.mjs --session-id sales --host 127.0.0.1 --port 8080

The v5 CLI's --tunnel flag only prints a warning; it does not configure a tunnel. For remote access, use Cloudflare Session Proxy.

Authentication and persistenceCopy Anchor Link

The published Easy API CLI authenticates with the QR code shown by the computer runtime. Link-code login is available to embedded Node.js applications through createClient; follow Link-code login for that flow. The phone already runs WhatsApp; it links the phone to the browser session on the computer.

After a successful login, restart from the same working directory with the same --session-id and the runtime reuses ./_IGNORE_sales. Stop the process before backing up that directory, and protect the copy as authentication material.

Plugins and webhooksCopy Anchor Link

Load plugins from wa.config.mjs through plugins, then put each plugin's settings under its pluginConfig key:

// wa.config.mjs
export default {
  port: 8080,
  plugins: ['@open-wa/integration-webhook'],
  pluginConfig: {
    webhook: {
      url: 'https://your-app.example/webhooks/open-wa',
      events: ['message.received'],
      headers: {
        'X-Webhook-Secret': process.env.OPEN_WA_WEBHOOK_SECRET,
      },
    },
  },
};

Use Webhook payloads for the supported plugin contract. The CLI still parses --webhook as a legacy config value, but current v5 delivery is configured through the plugin.

Production boundaryCopy Anchor Link

Do not expose Easy API directly to the public internet. /health is public even when an API key protects API calls, and its response may include QR and diagnostic data; keep it on a private network and do not proxy it publicly. Use an API key for protected API calls, protect the session profile, and make the readiness distinction part of your supervisor: HTTP liveness means the process answers, while connected and session.ready mean the WhatsApp session can be used.

For a repeatable browser container, use the Docker baseline. For direct browser ownership, use Custom code. For a remote consumer, use Socket Client.

Process managementCopy Anchor Link

Use a process manager when you need automatic restarts and one named process per session:

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

Process restarts do not replace session readiness checks; after a restart, wait for /health to report connected: true and session.ready: true before sending.