# open-wa/wa-automate: running a WhatsApp account as an API, bot runtime and MCP server > The v5 monorepo turns a WhatsApp Web session into a local HTTP API, a SocketClient backend or an embedded runtime, but the package is still on 5.0.0-alpha.0 and the README tells production users to stay on 4.76.0. **open-wa/wa-automate-nodejs** — 💬 🤖 The most reliable tool for chatbots with advanced features. Be sure to 🌟 this repository for updates! - Repository: https://github.com/open-wa/wa-automate-nodejs - Website: https://openwa.dev/ - Stars: 3,663 · Forks: 726 - Language: TypeScript - License: NOASSERTION - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/open-wa-wa-automate-nodejs ## The problem: WhatsApp has no first-party API for ordinary accounts WhatsApp is where a lot of customer conversations already happen, but there is no supported way for a small team to subscribe to those messages programmatically. The official business APIs require a business account and a provider relationship. open-wa/wa-automate takes the other route: it drives WhatsApp Web and exposes the result as something a normal backend can consume. The README describes the package as "a Node.js toolkit for WhatsApp Web automation" and lists the shapes you can build with it: a local API, a bot backend, a webhook source, a plugin host, or an MCP server. The audience is therefore Node.js developers who already own the surrounding system (a helpdesk, an order pipeline, a CRM) and want WhatsApp as one more event source rather than as a separate product. The README is explicit that this is unofficial and not affiliated with WhatsApp or Meta, and that using it means agreeing to the project's terms of service. That framing matters more than any feature list. You are automating a consumer client, and the project puts the risk on you in the first two lines of the document. ## Four surfaces over one runtime: Easy API, SocketClient, embedded, MCP The v5 repository is a monorepo. The root package.json is named @open-wa/monorepo, marked private, and declares workspaces for packages/*, apps/*, integrations/* and sdks/*. The published library is @open-wa/wa-automate, with a companion @open-wa/wa-automate-types-only package for type consumers. The architecture separates the WhatsApp runtime from the things that talk to it. Easy API starts the runtime and puts an HTTP layer in front of it, with generated documentation and schemas. SocketClient is the opposite direction: another Node.js process connects to a running Easy API instance instead of owning a browser. The embedded runtime is for applications that want to call createClient directly and manage the lifecycle themselves. MCP sits on top of Easy API and exposes its methods as tools an AI agent can discover and call. That layering is the real design decision here. It means you can start with the CLI, then move business logic out into your own service over the socket, without rewriting the WhatsApp side. It also means the browser is a process you have to think about: the README lists Puppeteer, Playwright and Lightpanda-backed runtime packages as interchangeable drivers, which is a maintenance surface in itself. ## Installing open-wa/wa-automate and getting a first session to respond The README's fastest path is the CLI. It starts an Easy API instance, triggers the first-run authentication flow, and serves interactive docs for the live session. Note the @alpha tag: this installs the v5 line, which the README warns is still in alpha. ```bash npx @open-wa/wa-automate@alpha --port 8080 ``` On first login the runtime asks you to authenticate, either by scanning a QR code it prints or by link-code login. Once the session connects, the README points at the generated docs as the proof of life, and at two machine-readable artifacts you can feed into other tooling. ```text http://localhost:8080/api-docs/ http://localhost:8080/meta/swagger.json http://localhost:8080/meta/postman.json ``` The README gives three variations worth knowing before you build anything on top. Setting an API key protects the HTTP surface, and naming the session matters as soon as more than one account is involved. ```bash npx @open-wa/wa-automate@alpha --port 8080 --api-key "your-secure-key" npx @open-wa/wa-automate@alpha --session-id sales --port 8081 ``` If you would rather not run Node.js directly, the README also documents a container image. It advises --init so the init process reaps zombie processes, and notes that W_A_V pins the library version, for example -e W_A_V=4.42.1. ```bash docker run -p 8080:8080 --init openwa/wa-automate ``` The README's own guidance for a first real session is to set sessionId early, add an API key before exposing the port beyond your machine, and keep business logic in your own application rather than inside the runtime. ## The v5 alpha is the biggest limitation, and the README says so The README carries a caution block stating that the repository is on version 5, that v5 is still in alpha and can have issues, and that you should use version 4 unless you are testing or contributing to v5. It names 4.76.0 as the last stable version and shows the pinned install command for it. The root package.json version is 5.0.0-alpha.0, and the most recent releases are v5.0.0-alpha.8 and its scoped package tags, published on 2026-07-08. The last push to the repository was on 2026-09-10. This is not a cosmetic warning. Following the README's own quick start puts you on an alpha line, so the default "get started" path and the "use this in production" path are different commands. If you copy the first snippet you find and ship it, you have made a choice the maintainers explicitly advised against. There is a second, narrower gap. The README states that the v5 alpha CLI parses --webhook but currently warns that CLI webhook registration parity is not restored, so the flag does not enable source-backed delivery. The working configuration is the @open-wa/integration-webhook plugin in wa.config.*, documented in apps/docs/content/docs/guides/webhooks-for-business.mdx. Anyone migrating from v4 who relied on a CLI flag will find the flag present and inert, which is a worse failure than an unknown option. Finally, the operational shape: this drives a browser session. The README's Docker notes say the image is best for local testing or a disposable first run unless you plan session persistence properly. Session state is your problem, not the library's. ## wa-automate versus the Python port and other WhatsApp automation routes The related searches around this project include wa-automate-python, and the comparison is worth stating plainly. The Python port is a separate codebase with its own release cadence, so the v4-versus-v5 split described here does not transfer to it, and neither do the v5 monorepo surfaces such as SocketClient or the MCP server. If your stack is Python, choosing the port means giving up the Node.js plugin and integration packages described in this README. Against the official WhatsApp Business APIs, the difference is not features but posture. The official route is sanctioned and comes with a business account and provider relationship; this project is, in its own words, unofficial and not affiliated with WhatsApp or Meta. That is the trade: less paperwork and a familiar account, in exchange for automating a client you do not control and accepting the project's terms of service. Within the project itself there is a real alternative worth naming. SocketClient connects another Node.js application to a running Easy API instance, so you do not own the browser runtime. The embedded runtime does the opposite and calls createClient inside your process. The first keeps the browser in one place and lets several consumers attach; the second removes a network hop and gives you the lifecycle, at the cost of coupling your application to the runtime's process. ## Licence and upgrade cost in a monorepo that warns you off its own default The root package.json declares Apache-2.0. GitHub reports the repository licence as NOASSERTION, which means the platform could not map the repository's licence files to a known identifier. The README links a separate tos.md that you agree to by using the project. Those are two different documents, and the discrepancy between the declared licence and the platform's classification is something to read yourself rather than infer. This is not legal advice. The upgrade cost is unusual because the project is already asking you to move backwards. The README tells mature v4 production systems to stay on 4.76.0 and to test v5 separately, and the repository carries MIGRATION-LOG.md and a package.json.v4-backup at the root, which suggests the migration path is being tracked rather than assumed. The monorepo also runs on pnpm workspaces and turbo, with a check:effect-contracts script that chains tests, builds and typechecks across the runtime, webhook, S3, Chatwoot and client packages plus a portable-imports check. That is a lot of internal contract surface for a project whose published entry point is still an alpha. Practically: pin your version explicitly, keep v4 and v5 sessions apart, and treat any CLI flag you relied on in v4 as unverified until you confirm it against the plugin configuration in the docs. ## Conclusion Adopt open-wa/wa-automate if you want WhatsApp events inside your own Node.js service and you are willing to pin 4.76.0 or treat the v5 alpha as disposable. Do not adopt it if you need a supported, officially sanctioned WhatsApp integration, because the README states the project is unofficial and not affiliated with WhatsApp or Meta. Before writing code, verify three things: which version tag you are actually installing, that the session survives a restart in your environment, and whether your delivery path is the webhook plugin in wa.config.* rather than the --webhook CLI flag, which the README says currently warns that registration parity is not restored. ## FAQ ### What is OpenWA? OpenWA refers to open-wa/wa-automate, a Node.js toolkit for WhatsApp Web automation. The README says you can use it to build a local API, bot backend, webhook source, plugin host or MCP server, and that it is unofficial and not affiliated with WhatsApp or Meta. ### Is WhatsApp automation free? The README does not describe pricing for open-wa/wa-automate. It does state that the project is unofficial, that using it means agreeing to its terms of service, and that you use it at your own risk. ### What does WhatsApp automation mean? In this project's terms, it means driving a WhatsApp Web session programmatically so your software can react to messages and events. The README frames the output as an API, a bot runtime, a webhook source or an MCP tool surface. ## Sources - [Issues](https://github.com/open-wa/wa-automate-nodejs/issues) - [open-wa/wa-automate-nodejs on GitHub](https://github.com/open-wa/wa-automate-nodejs) - [Project website](https://openwa.dev/) - [README](https://github.com/open-wa/wa-automate-nodejs/blob/master/README.md) - [Releases](https://github.com/open-wa/wa-automate-nodejs/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/open-wa-wa-automate-nodejs