Easy API quick start

Use this page when you want a local WhatsApp API running before you write custom Node.js code.

Run it

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

That starts an Easy API instance on port 8080 and prints the local address for the API and the interactive docs.

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

Expected terminal output

Exact log lines vary by version and browser driver, but you should see the runtime start, then print the local API address and docs URL.

Easy API listening on http://localhost:8080
Interactive docs: http://localhost:8080/api-docs/

Open the docs URL after the session is connected. If you changed the port, replace 8080 with your chosen port.

What you get

When the runtime is healthy you usually have three things:

• the session bootstrap flow (QR or link-code authentication)
• the HTTP API surface
• the generated interactive docs for that running session

That makes Easy API the shortest route from “I want an API” to “I can send and receive messages”.

Common flags

# choose a port
npx @open-wa/wa-automate --port 8080

# protect the API with your own 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

API-key examples

Use --api-key "your-secure-key" when you want a stable key that your apps, scripts, or teammates can reuse. The current CLI reads the value after --api-key, --key, or -k; a bare --api-key does not generate a key.

npx @open-wa/wa-automate --port 8080 --api-key "your-secure-key"

When calling the API, send the same key with your request headers.

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

Good defaults for a first session

• Set a session id early if you plan to run more than one account.
• Protect the API with an API key before exposing it anywhere outside your machine.
• Treat the Easy API as a runtime surface, then move business logic into your own app or worker processes.

Session persistence

Easy API stores the browser profile for a session on disk so a restart can reuse the same authenticated WhatsApp Web session.

By default, the profile directory is derived from the session id. For --session-id sales, the local profile directory is ./_IGNORE_sales. If you do not set a session id, the default session uses ./_IGNORE_session.

To keep the session across restarts, start the process from the same working directory and reuse the same --session-id. To back it up, stop the process first, then copy the matching _IGNORE_* directory to safe storage. Restore that directory before starting the runtime again.

Authentication paths

• If you are doing an ordinary first login, scan the QR code the runtime emits.
• If you already know the host account number and want to avoid QR scanning, use Link-code login.

If you want the fastest path to first success, follow the Quick Start guide.

Deployment notes

• Use --host or -h to choose the local bind host.
• Use --session-id plus distinct ports when you run multiple sessions on one host.
• Put restart policy around the process early; do not wait until you have a flaky production incident.

Production warning

Tunneling and remote access

The current v5 CLI only warns when --tunnel is provided; it does not restore tunnel setup parity. For controlled remote access, use Cloudflare Session Proxy instead.

Webhooks

The current CLI parses --webhook into config, but startup warns that v5 CLI webhook registration parity is not restored. For source-backed webhook delivery in the current v5 alpha, load @open-wa/integration-webhook from wa.config.* through the plugin config section below.

Load a plugin from config

Load plugins from the config file through the plugins array. Put plugin-specific settings in pluginConfig.

plugins: [
  '@open-wa/integration-webhook',
  './my-local-plugin'
],
pluginConfig: {
  webhook: {
    // plugin-specific config
  }
}

Process management

If you want automatic restarts and supervised uptime, run under a process manager.

npx @open-wa/wa-automate --pm2 --session-id STICKER-BOT --port 8080

PM2 is useful when you need process restarts, basic memory controls, and a named process per session.

When to graduate from this page

• Move to Custom code if you want direct client control.
• Move to Socket Client if your app needs to consume a remote Easy API instance.
• Move to Multiple sessions if one runtime is no longer enough.

Related guides

• CLI options
• Multiple sessions
• Socket Client

Was this helpful?

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

YesNo