OpenWA

---

✨ Why OpenWA?

OpenWA is a free, open-source WhatsApp API Gateway designed for developers who need full control over their messaging infrastructure—without vendor lock-in or hidden paywalls.

Built on a pluggable architecture, OpenWA lets you select database engines (SQLite/PostgreSQL), media storage backends (Local/S3), and an optional Redis (queue, rate limits, WebSocket fan-out) through configuration rather than application-code changes. The storage backend is the live store for status media and, when chat-media archiving is enabled, archived chat media; other message media is returned inline to API and webhook consumers. Of the media, scripts/backup.sh archives only the local media directory, so an S3 bucket needs a backup of its own.

🔓 100% Open Source	No licensing fees, no feature locks, full source code access
🏗️ Pluggable Architecture	Swap adapters for database and storage via config
🖥️ Full Dashboard	Modern React UI for session, webhook, and API key management
🔹 Multi-Session Ready	Run multiple WhatsApp sessions concurrently on one instance
🐳 Docker Native	Production-ready with zero configuration
🧩 Official Plugins	Chatwoot, Typebot & more as sandboxed plugins on the Integration Fabric — OpenWA-plugins
🔗 n8n Integration	Community nodes for workflow automation
🧩 Community Adapters	Third-party integrations (e.g. ioBroker) — see docs
🔐 Session-scoped keys	Operator and viewer (reader) tokens can be limited to chosen sessions — or all sessions if none are selected
🔒 Chat-scoped keys	Those same tokens can also be limited to chosen chats — a few groups and contacts — so an agent on a shared account sees only its own

Session-scoped operator & viewer tokens

When you create or edit an operator or viewer API key in the dashboard, you can tick the WhatsApp sessions that key may use.

• No sessions selected — the key can access every session, including ones created later.
• One or more sessions selected — the key can only list, read, and (for operator) manage those sessions. A request naming any other session returns 403 ("API key not authorized for this session"); session-filtered lists (sessions, audit, webhook delivery failures) return that key's rows rather than an error; and the key-management routes and the queue dashboard, which name no session at all, return 403.

Admin keys stay unscoped in the dashboard so they can keep managing other API keys. The HTTP API still accepts allowedSessions on any role if you need that from a client.

Chat-scoped operator & viewer tokens

A session-scoped key still reaches every chat on the sessions it may use. A key can be narrowed further, to chats (a chosen set of groups and individual contacts), with allowedChats on POST /auth/api-keys or PUT /auth/api-keys/{id}. The dashboard sets it on operator and viewer keys (one chat id or phone number per line) and shows each key's chat count in the list.

• No chats selected — the key can reach every chat on its sessions.
• One or more selected — the key reaches only those chats. Every authenticated REST route not explicitly marked as safe for a chat-scoped key refuses it with 403 (a request naming a session outside allowedSessions is refused first, with 403 "API key not authorized for this session"), including routes added in later releases: the refusal is the default. Inside its chats an operator key can do what the marked routes allow, which is more than reading and sending: it can also delete or clear a chat, leave or rename a group, and block the contact. It cannot change who belongs to a group: adding, removing, promoting or demoting participants, answering join requests and reading or resetting the invite link all stay closed.
• The two scopes are independent — a key may be limited to sessions, to chats, to both, or to neither.

This lets you point an AI agent or third-party integration at a shared account without handing it every chat. Give the agent a key scoped to the few groups (or DMs) it is meant to handle: it can send and reply there, but it cannot list your other chats, read any other DM, message a contact outside its set, or reach the queue dashboard. It reads its chats' stored messages on either engine through GET /sessions/{sessionId}/messages?chatId=, where chatId is required for such a key, and live history through GET /sessions/{sessionId}/messages/{chatId}/history on whatsapp-web.js only. It can subscribe to the /events WebSocket, which delivers only events for its chats. It can still read the session's own status (GET /sessions/{sessionId}) so an integration can tell whether it is connected.

This is the beginning of the README. Read the rest at the original. Read the full README ↗