Self-hosted WhatsApp API gateway
OpenWA is an open-source, self-hosted WhatsApp API Gateway. It wraps a WhatsApp connection in a REST API so your applications can send and receive messages, manage groups and contacts, and react to events — running entirely on infrastructure you control.
curl -X POST \
http://localhost:2785/api/sessions/$SESSION/messages/send-text \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"chatId": "628123456789@c.us",
"text": "Hello from OpenWA!"
}'
Hello from OpenWA!
Receipts reach your webhook as message.ack
This page explains what OpenWA is, the problems it solves, and how its pieces fit together, so you can decide whether it fits your stack before you install anything. This documentation set targets OpenWA v0.31.0.
What changed in recent releases
In v0.27.1 through v0.31.0, the whatsapp-web.js engine adds per-recipient message receipts (GET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/receipts, v0.28.0+), authenticated HTTP/HTTPS session proxies bypass the WhatsApp Web service worker so credentialed sessions keep reconnecting across restarts, the version resolver rejects logged-out WhatsApp Web registry builds and falls back to the newest settled build (v0.29.0+, stepping through cached candidates from the same registry read in v0.29.1+), the 409 it answers to a request that is safe to repeat while WhatsApp Web reloads its page carries code ENGINE_PAGE_RELOADING and retryAfterSeconds (v0.31.0+), and a start gives up on the page's connection to WhatsApp after WWEBJS_AUTH_TIMEOUT_MS (v0.31.0+). Both engines add phone-to-LID lookup (GET /api/sessions/{sessionId}/contacts/{number}/lid, v0.27.1+), isForwarded / forwardingScore on forwarded messages (message.received and message.sent, plus whatsapp-web.js live chat history, v0.29.1+), and a linkPreview session config key, the default for a send-text or send-template that sets no preview of its own (v0.30.3+). Baileys sessions rebuild their stored chat list after a restart (seeking stored chat names by chat on SQLite in v0.29.1+), advance group message.ack to delivered and read across the group's members (v0.28.0+), report restriction: { kind: "passkey_required" } and connection-drop stage diagnostics during linking (v0.30.0+), repair inbound media stream teardown on Baileys v7 so an abandoned download cannot terminate the gateway process (v0.30.0+), report poll votes as poll.vote (v0.30.2+), and list an unnamed privacy-id chat with name "" and, where the session can map the id, a phone (v0.31.0+). The MCP server adds MessageList filters, inlineMedia, idempotencyKey on all 11 send tools, strict argument checking, and a 32 KiB inline result threshold (v0.30.0+), then an opt-in MCP_MAX_RESULT_BYTES result cap and MessageList results without media payloads unless a call sets inlineMedia: true (v0.31.0+). From v0.31.0 the local media directory and the storage export archives are owner-only, the SSRF guard also refuses the documentation address ranges, the IPv6 benchmarking range 2001:2::/48 and 192.88.99.2, and the linux/amd64 Docker image updates Chrome for Testing to 158 (158.0.8127.36). See Sending messages, Sessions, Groups and Webhooks for details, and follow the migration guide before upgrading.
What OpenWA gives you
WhatsApp does not offer a free, self-hostable HTTP API. Most hosted gateways fill that gap but charge for the parts you need most — multi-session, PostgreSQL, a dashboard, webhook management — and keep your message data on their servers.
OpenWA inverts that trade. The full feature set is open source under the MIT license, and every byte of session and message data stays on your own machine. You own the deployment, the data, and the source.
- Open source, no feature gates. The complete codebase is MIT-licensed. There is no paid tier and no locked feature — fork it, audit it, extend it.
- Self-hosted, no vendor lock-in. Sessions, messages, and media live on your server. Nothing routes through a third-party SaaS.
- Pluggable adapters. Swap the database (SQLite or PostgreSQL), media storage (local filesystem or S3/MinIO), and cache (Redis or none) through environment variables — no code changes.
- Multi-session. Run several WhatsApp accounts concurrently on one instance.
- Web dashboard. A bundled React UI manages sessions, webhooks, and API keys, served by the API on the same port.
- Signed webhooks. Message and session events are delivered to your endpoints in real time. Give a webhook a
secretand every delivery is signed with HMAC, so your receiver can verify it came from your gateway. - Typed SDK. The official
@rmyndharis/openwapackage wraps the user-facing API with TypeScript types and typed errors, and its rawrequest()method reaches any route it does not cover yet.
Feature overview
| Area | What you get |
|---|---|
| API | REST API under the /api prefix; interactive Swagger docs at /api/docs (off under NODE_ENV=production unless ENABLE_SWAGGER=true) |
| Messaging | Text, images, video, audio, documents, stickers, reactions, replies, forwards, bulk sends, and (Baileys) button and list replies to WhatsApp Business prompts |
| Sessions | Multi-session; QR-code or pairing-code auth; lifecycle status tracking |
| Groups & channels | Create and manage groups, participants, and invites; WhatsApp Channels support |
| Contacts & labels | Contact lookup and management; chat labels (WhatsApp Business) |
| Webhooks | Per-session subscriptions, HMAC signatures (when a secret is set), automatic retries, optional pre-dispatch filters, and payload-retained failure redrive |
| Automation | Built-in per-session auto-reply rules — evaluated on the inbound message, with match conditions and per-chat cooldowns |
| Auth | API-key authentication via the X-API-Key header, with roles and per-key IP, session, and chat allow-lists |
| Database | SQLite (zero-config default) or PostgreSQL — set DATABASE_TYPE |
| Storage | Local filesystem or S3/MinIO — set STORAGE_TYPE |
| Cache | Optional Redis — set REDIS_ENABLED; when off, the cache layer no-ops |
| Engine | Baileys (browser-free) or whatsapp-web.js — set ENGINE_TYPE |
| Plugins | Extension plugins installed from a zip or the catalog add behavior (translation, Chatwoot sync) without forking core |
The REST API is organized into 24 resource tags: sessions, messages, and media for the send-and-receive path; contacts, groups, channels, labels, catalog, status, calls, and profile for the WhatsApp surfaces around it; webhooks, automation, templates, search, and statistics for the gateway's own features; and auth, plugins, settings, infrastructure, integration, audit, metrics, and health for administration. For the full request and response shape of every endpoint, see the generated API reference.
How it fits together
OpenWA sits between your applications and WhatsApp. Requests arrive over HTTP authenticated with an API key; the NestJS API drives a pluggable WhatsApp engine that talks to WhatsApp's servers; and the database, storage, and cache backends are selected by configuration. When WhatsApp emits an event, OpenWA delivers it to your webhook endpoints, signing it with HMAC when the webhook has a secret.
The engine adapter is one of two formal extension points. The other is the extension-plugin runtime: plugins installed from a zip or the catalog add behavior — translation, Chatwoot sync — without forking core (see Plugins). Single-message auto-reply needs no plugin: core evaluates per-session automation rules on the inbound dispatch. The database, storage, and cache backends are single services that switch implementation based on an environment variable, so you can run a minimal SQLite-and-local-storage instance or a PostgreSQL-and-S3 one from the same image. See the configuration reference for how to select each backend.
A request in practice
Every call carries the X-API-Key header. In local development the API base URL is http://localhost:2785/api (note the /api prefix); in production it sits behind your own domain and TLS. Sending a text message looks like this:
curl -X POST http://localhost:2785/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/messages/send-text \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"chatId": "628123456789@c.us",
"text": "Hello from OpenWA!"
}'
{
"messageId": "true_628123456789@c.us_3EB0123456789",
"timestamp": 1719400000
}
Replace YOUR_API_KEY with a key minted on first run (the Quick Start shows where it comes from), and the id in the path with the id of a session you have authenticated. The typed SDK wraps the same call:
import { OpenWAClient } from '@rmyndharis/openwa';
const client = new OpenWAClient({
baseUrl: 'http://localhost:2785',
apiKey: 'YOUR_API_KEY',
});
const result = await client.messages.sendText('8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a', {
chatId: '628123456789@c.us',
text: 'Hello from OpenWA!',
});
console.log(result.messageId);
Engines and adapters
OpenWA speaks to WhatsApp through one of two interchangeable engines, chosen with ENGINE_TYPE:
- Baileys — a browser-free WebSocket client with a small memory footprint. Suited to running many sessions on modest hardware.
- whatsapp-web.js — a Chromium/Puppeteer-based client. Heavier per session, but uses a real browser fingerprint.
Because both implement the same engine interface, switching is a config change and a restart. Each engine keeps its own credentials, so a session that has never been linked under the new engine must be linked again, by QR code or pairing code; credentials left under the previous engine stay on disk until the session is deleted. Some routes, and some options of routes both engines serve, are supported by only one engine and answer 501 on the other, and a few values are engine-specific as well, such as the message id you pass as quotedMessageId (see API conventions and Sending messages). The infrastructure adapters are chosen by configuration too: move from SQLite to PostgreSQL, local storage to S3/MinIO, or no cache to Redis by editing environment variables. The trade-offs behind each choice are covered in scaling; moving existing data between backends is covered in migration.
OpenWA connects through an unofficial WhatsApp interface and is not affiliated with or endorsed by Meta. You are responsible for using it in line with WhatsApp's terms of service — see Ban risk & safe sending before you connect a number.
Next steps
- Quick Start — get OpenWA running and send your first message in about five minutes.
- Installation — Docker and local-development setup options.
- Configuration — select your database, storage, cache, and engine.