What is OpenWA?
OpenWA is a free, open-source WhatsApp API gateway that you run yourself. It exposes WhatsApp accounts through a REST API, signed webhooks, a WebSocket event stream and a bundled web dashboard, so that an application can send and receive messages without a vendor-hosted service in between. The project is maintained by Yudhi Armyndharis with community contributors and describes itself as independent: it is not affiliated with Meta or WhatsApp.
It connects to WhatsApp through reverse-engineered clients, not through Meta's official Cloud API. Two engines are available: whatsapp-web.js, the default, which drives a headless Chromium per session, and Baileys, a browserless WebSocket client selected with ENGINE_TYPE. The project states plainly that any connected number carries a non-zero risk of restriction, and recommends a dedicated number. Read the ban risk and safe sending guide before linking an account.
OpenWA is a TypeScript application built on NestJS 11 and TypeORM, with a React dashboard served by the same process on port 2785. It stores data in SQLite by default or PostgreSQL, can add Redis for queues, rate limits and WebSocket fan-out, and can keep live media on local disk or S3-compatible storage such as MinIO. Distribution is by Docker Compose and a multi-architecture image on GitHub Container Registry for linux/amd64 and linux/arm64, or by running from source on Node.js 22.19 or newer.
The reviewed release is OpenWA v0.29.1, published on November 7, 2026. It marks forwarded messages with isForwarded and forwardingScore on both engines and fixes a session-start problem when WhatsApp Web build pinning read a logged-out page. Version 0.29.0 updated the bundled Chrome for Testing on amd64, and 0.28.0 added a per-recipient receipts route on whatsapp-web.js. The source license is MIT. The gateway is not a drop-in replacement for the official API in regulated settings, and its own README says so. Documentation lives at docs.open-wa.org.
Key capabilities
- Docker Compose installation The recommended path is Docker Compose with Compose 2.20.0 or newer on a 64-bit Linux, macOS or Windows host. Chromium is bundled in the image, and the documentation suggests about 2 GB of RAM and 2 GB of disk for the default engine. The first boot prints a generated admin API key once and stores it in the data volume. See the installation guide.
- Source installation Running from source needs Node.js 22.19 or newer and npm, and
npm run devstarts the API with a hot-reload dashboard on port 2886. On Linux with glibc, the shipped better-sqlite3 and sharp prebuilds need glibc 2.34 or newer, so older distributions should use the Docker image. - Production Compose profiles The main
docker-compose.ymldefaults toNODE_ENV=productionand offerspostgres,redis,minioandfullprofiles. A profile only starts the container; OpenWA keeps using SQLite and local storage until configured. A production boot rejects default credentials such asminioadmin. - REST API and Swagger Sessions, messages, contacts, groups, channels, labels, webhooks and API keys are managed over HTTP under
/api, authenticated with anX-API-Keyheader. Interactive Swagger is served at/api/docsin non-production runs and stays off in production unlessENABLE_SWAGGER=true. A generated API reference is published. - Multi-session management One instance can run several WhatsApp sessions at once, each created, started and linked by QR code or pairing code. Each whatsapp-web.js session costs roughly 300 to 500 MB of RAM and each Baileys session roughly 30 to 80 MB, according to the project. Keep exactly one API instance per session-data volume.
- Two WhatsApp engines Whatsapp-web.js is the default and, per the project, has the lower ban-risk profile because it drives a real Chromium. Baileys needs no browser and uses far less memory, but is easier for WhatsApp to fingerprint. An engine capability matrix in the docs shows which routes work on which engine; for example, message receipts are available on whatsapp-web.js and answer 501 on Baileys.
- Messaging Send text, images, video, documents and audio, react to messages, send edits, track delivery and read status and send bulk messages with a delay between items. A single bulk request carries up to 100 messages. Typing simulation is on by default for single text sends.
- Webhooks with HMAC signatures Register a URL per session with an event list and a secret, and receive signed deliveries for events such as
message.receivedandsession.status. Optional smart filters match on sender, recipient, chat, body, type, mentions, media and group conditions, combined with AND. A signature verification example is in the repository. - WebSocket events An
/eventsWebSocket delivers live events to API clients. For a chat-scoped key it delivers only events from the chats that key may reach. - Role-based, scoped API keys Keys have admin, operator or viewer roles and can be limited to chosen sessions with
allowedSessionsand to chosen chats withallowedChats. A chat-scoped key is refused on every REST route not marked safe for it, including routes added in later releases. Keys can also carry an IP allow-list. - Web dashboard The React dashboard is bundled into the API image and offers session and QR management, a webhook builder with a visual filter editor, API key management for admins, infrastructure settings and plugins. The documentation lists nine interface locales. Sign-in uses an API key, and what appears depends on the key's role.
- Send pacing and ban-risk controls Setting
SEND_PACING_ENABLED=trueadds a per-session daily cap that grows with session age, a separate cap on new conversations and a consecutive-failure breaker. It is off by default. TheRATE_LIMIT_*variables protect the API and are not a send cap. - Groups, channels, labels and profiles Create and manage groups, join by invite code, handle membership requests, work with WhatsApp Channels, organize chats with labels and set the account's display name, about text and picture. Call events can be received, and Baileys sessions support per-session auto-reject of calls.
- Proxies, CIDR rules and audit log Each session can use its own proxy. IP access control is available with CIDR allow-lists, and an audit trail records API-key, session, integration-instance, plugin and infrastructure admin operations. Message sends and webhook deliveries have their own tables.
- MCP server for AI agents With
MCP_ENABLED=true, a stateless Streamable HTTP endpoint atPOST /mcpmounts 26 read-only tools by default, or 52 tools withMCP_READONLY=false. Calls pass through the same API-key authentication and scoping as REST. The project advises a dedicated, session-scoped key and not exposing the endpoint publicly. See the MCP guide. - Plugins and Integration Fabric Sandboxed plugins add hooks, search providers and bidirectional integrations through permission-gated capabilities declared in a manifest. Official plugins include Chatwoot and Typebot, published in the OpenWA-plugins repository. Plugins are installed disabled and run only after an administrator enables them.
- Official SDKs and n8n nodes First-party clients exist for JavaScript and TypeScript, Python, PHP, Java and Go, versioned independently of the gateway. Community n8n nodes live in the OpenWA-n8n repository, and a community ioBroker adapter is listed.
- Storage migration and backups Data can be exported and imported between database and storage backends. The backup script archives only the local media directory, so an S3 bucket needs its own backup. Back up the sessions directory before changing browser versions, because a rollback across a Chrome major can delete stored whatsapp-web.js logins.
- Security hardening The production image runs as a non-root user through dumb-init and gosu. A Docker socket proxy sidecar limits access to the Docker daemon, though the project notes that with POST enabled a compromised API container would be host-root-equivalent. Read the repository's security policy before enabling built-in datastore orchestration.
Where OpenWA fits
Sending notifications and one-time codes to your own users
Create a session on a dedicated number, scan the QR code and send a text through POST /api/sessions/{sessionId}/messages/send-text. Limit recipients to people who expect to hear from you, turn on send pacing and keep an SMS or email fallback for anything login-critical. Check that a first message to a new contact actually arrives, because the project documents a WhatsApp-side policy that can drop it silently.
Receiving messages in your own application
Register a webhook with an HMAC secret and verify the signature in your receiver before trusting the body. Use smart filters to restrict deliveries to chosen chats or message types. Test the retry behavior by taking your receiver offline briefly, and use the WebSocket stream when a long-lived connection suits the client better than HTTP callbacks.
Connecting a helpdesk or chatbot
Install the official Chatwoot or Typebot plugin from the catalog, or use the n8n nodes for workflow automation. Plugins arrive disabled, so review the permissions in the manifest before an administrator enables one. Confirm how conversations are handed over to a human agent and which identifiers map to which contact.
Giving an AI agent limited access
Mint a non-admin key scoped to the few sessions and chats the agent should handle, then mount the MCP endpoint in read-only mode first. Verify that requests outside the allowlist return 403 and that the agent cannot list other chats. Keep the endpoint on a private network, since the documented static key is not intended for public exposure.
Running several accounts on one host
Choose the engine by memory budget and risk tolerance, then size the host from the per-session figures in the documentation. Move to PostgreSQL and Redis when the SQLite default stops fitting. Keep one API instance per session volume unless you deliberately adopt the experimental multi-node layer with shared PostgreSQL and Redis.
Operating and upgrading the gateway
Pin a release tag instead of latest, back up the data and sessions directories before each upgrade and read the upgrade notes in the changelog. Probe the health endpoints for liveness and readiness, and review the deployment guide for reverse proxy and TLS setup.
Reviews of OpenWA
Be the first to share your experience with OpenWA.
Write a review
Loading review form…
Alternatives to OpenWA
NovuNovu is MIT-licensed communication infrastructure with a workflow engine, digests, an embeddable React Inbox and preferences, close to 80 provider integrations and two-way agent messaging. Run it on Novu Cloud (US or EU) or self-host with Docker.