A new foundation for OpenWA.

Three years in the making, V5 is a major change to how you run and extend OpenWA. WhatsApp automation still sits at the centre, but you now have a clearer choice about which process owns the browser and session—and how the rest of your application talks to it.

V5 became npm's latest release with this launch. Existing V4 applications need a deliberate migration; installing V5 over an unchanged V4 application isn't a drop-in upgrade.

Choose where your WhatsApp session lives. These are alternative setups; you don't need to run all three.

Start with the way you want to run itCopy Anchor Link

Run WhatsApp as an API. Easy API owns browser setup, authentication, the session and HTTP hosting. Start it as a process and call its documented methods from your service. This is the shortest route when you want an API without managing a browser lifecycle in your application.

Connect your application remotely. SocketClient connects a Node.js app to a running Easy API instance. Commands travel over HTTP and live events over Server-Sent Events. Your bot, worker or dashboard can consume a session without opening its own browser.

Embed the runtime when you need control. Use createClient, choose a browser driver, and own startup and shutdown inside your application. V4 applications using create need to move to the V5 contract.

Start with the Easy API guide, the SocketClient guide, or the embedded runtime guide.

From a running session to your first messageCopy Anchor Link

Start Easy API in one terminal, then link your WhatsApp account:

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

In your Node.js application, install @open-wa/socket-client and connect to that session:

import { SocketClient } from '@open-wa/socket-client';

const client = await SocketClient.connect(
  'http://localhost:8080',
  'your-api-key',
);

// Replace this with your recipient's WhatsApp chat ID.
await client.sendText('1234567890@c.us', 'Your order is ready to collect!');
client.close();

Your application sends the command; Easy API owns the browser and the WhatsApp session. The same session can serve your other integrations too.

Extend OpenWA around your workflowCopy Anchor Link

The runtime, API, schema, browser drivers and integrations now live in separate packages. Reusable behaviour loads through plugins and pluginConfig, with dedicated paths for webhooks, Chatwoot, S3 media handling, Cloudflare session proxying and Node-RED.

That separation makes ownership clearer: the session runs in one place, and the integrations around it can be configured for the application you're building. The configuration guide explains how to connect those pieces.

Discover the API you actually runCopy Anchor Link

The method schema powers interactive API documentation and generated metadata. Easy API exposes Swagger and Postman descriptions alongside its live methods, so you can inspect the service's actual contract while building an integration.

For agent integrations, Easy API can expose that schema as MCP tools at /mcp. Discovery and execution require the Easy API key. Enable MCP through wa.config.*; --mcp isn't a V5 CLI option.

Moving from V4Copy Anchor Link

1. Keep existing deployments pinned while migrating. Pin 4.76.0 for an application that still uses V4, and run V5 separately until you've moved its configuration and workflows.
2. Choose the right consumer. Move remote consumers to SocketClient and embedded applications to createClient. Check the methods and schemas your application calls against /api-docs/ on your running Easy API.
3. Update webhook configuration and receivers. Configure @open-wa/integration-webhook through wa.config.*. The V5 CLI accepts --webhook but doesn't register delivery. Receivers now read payload from { webhookId, sessionId, event, payload, timestamp }, rather than V4-style data.

The webhook guide covers the new delivery path. Move one workflow at a time, including its login, named session and recovery behaviour, before switching production traffic.

Package changesCopy Anchor Link

The package split supports these runtime and integration choices. Version alignment and dependency updates sit in the full package changelogs, alongside the detailed source comparison. Start with the ownership and migration changes above when deciding what your application needs to update.