OpenWA

Open Source WhatsApp API Gateway

Features • Quick Start • Docs • API • Contributing

✨ 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 swap database engines (SQLite/PostgreSQL), storage backends (Local/S3), and cache layers (Memory/Redis) without changing a single line of application code.

🎯 Features

Core Features

Messaging

Advanced

Infrastructure

🚀 Quick Start

Option A: Docker (Recommended)

# Clone and start
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
docker compose -f docker-compose.dev.yml up -d

# Access (the dashboard is bundled into the API image and served on the same port)
# Dashboard: http://localhost:2785
# API: http://localhost:2785/api
# Swagger: http://localhost:2785/api/docs

Using Podman instead of Docker? Podman rootless mode requires the socket to be running and DOCKER_HOST to be set:

bash systemctl --user start podman.socket systemctl --user enable podman.socket export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock

Add the export line to your ~/.bashrc to make it permanent.

Option B: Local Development

# Clone repository
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA

# Install dependencies (includes dashboard)
npm install

# Start API + Dashboard (config is auto-generated on first run)
npm run dev

# Access (in dev the dashboard runs on the Vite server with hot reload)
# Dashboard: http://localhost:2886
# API: http://localhost:2785/api
# Swagger: http://localhost:2785/api/docs

🔒 Security Architecture

Docker Socket Proxy

The production stack never exposes /var/run/docker.sock directly to the application container. Instead, a dedicated docker-proxy sidecar (based on tecnativa/docker-socket-proxy) acts as the sole gateway to the Docker daemon:

openwa-api  ──TCP 2375──▶  docker-proxy  ──unix──▶  /var/run/docker.sock

Only the operations needed for container orchestration are enabled (CONTAINERS, IMAGES, VOLUMES, INFO, PING, POST, DELETE). The application connects via the DOCKER_HOST=tcp://docker-proxy:2375 environment variable, which DockerService detects automatically.

🔒 Security Architecture

Non-root Container Execution

The production image never runs the Node.js process as root. On startup, the container follows this chain:

dumb-init (PID 1)
  └─ docker-entrypoint.sh (root — fixes named-volume ownership via chown)
       └─ gosu openwa node dist/main  (drops to the openwa user)

• dumb-init is PID 1 and forwards signals (SIGTERM, etc.) for graceful shutdown.
• docker-entrypoint.sh runs as root only long enough to chown the named-volume mount points so the openwa user can write to them.
• gosu performs a clean exec-based privilege drop — no su or sudo wrappers, so the node process is the direct child of dumb-init.

Named volumes (e.g. openwa-data) get their ownership corrected automatically on every start, so no manual chown step is needed after volume creation.

🏭 Production Deployment

For production, use the main docker-compose.yml with optional services:

# Basic production (SQLite, local storage)
docker compose up -d

# With PostgreSQL database
docker compose --profile postgres up -d

# Full stack (PostgreSQL, Redis, MinIO)
docker compose --profile full up -d

The dashboard is bundled into the API image and served by NestJS on the API port, so it needs no profile — it is always available wherever openwa-api runs. For TLS/public exposure, put your own reverse proxy (nginx, Caddy, a cloud load balancer, or a k8s Ingress) in front; see the nginx example in docs/12-troubleshooting-faq.md.

Development vs Production

• Development (docker-compose.dev.yml): SQLite, local storage, API serves the bundled dashboard
• Production (docker-compose.yml): Configurable database, profiles for optional services

Official GHCR images are published as multi-arch manifests for: - linux/amd64 - linux/arm64

🔌 Ports

📡 API Examples

Create a Session

curl -X POST http://localhost:2785/api/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"name": "my-bot"}'

Start Session & Get QR Code

# Start the session
curl -X POST http://localhost:2785/api/sessions/{sessionId}/start \
  -H "X-API-Key: YOUR_API_KEY"

# Get QR code (scan with WhatsApp)
curl http://localhost:2785/api/sessions/{sessionId}/qr \
  -H "X-API-Key: YOUR_API_KEY"

Send a Message

curl -X POST http://localhost:2785/api/sessions/{sessionId}/messages/send-text \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "chatId": "628123456789@c.us",
    "text": "Hello from OpenWA!"
  }'

Setup Webhook

curl -X POST http://localhost:2785/api/sessions/{sessionId}/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["message.received", "session.status"],
    "secret": "your-hmac-secret"
  }'

Smart filters (optional): add a filters object to fire the webhook only when conditions match (AND), e.g. { "conditions": [{ "field": "sender", "operator": "is", "value": ["1234567890@c.us"] }] }. Fields: sender / recipient / body / type / mentions / fromMe / hasMedia / isGroup. A webhook with no filters behaves exactly as before. See the API specification for the full schema.

🤖 MCP Server (AI Agents)

OpenWA can expose a curated set of tools over the Model Context Protocol so AI agents (Claude, Cursor, …) can drive WhatsApp. It is off by default and additive — every REST route keeps working unchanged.

Set MCP_ENABLED=true to mount a stateless Streamable-HTTP transport at POST /mcp on the existing server (same port, no extra process). It exposes ~39 curated tools (sessions, messaging, contacts, basic group ops, webhook reads) — a focused surface rather than the full API, so agents aren't overwhelmed and destructive operations stay off the agent path.

MCP_ENABLED=true npm run start:prod   # or set MCP_ENABLED in your .env / compose

Point an MCP client at it (e.g. for Claude Code, a .mcp.json at your project root):

{
  "mcpServers": {
    "openwa": {
      "type": "http",
      "url": "http://localhost:2785/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

The key can be passed as Authorization: Bearer … or X-API-Key: …. Every tool call goes through the same API-key auth, role, and per-session scoping as REST.

Security guidance:

• Mint a dedicated, least-privilege key for the agent — a non-admin, session-scoped key (OPERATOR role at most). The plaintext key is shown only once on creation; to rotate, create a new key and delete the old one.
• The key must not carry an IP allow-list (allowedIps) — there is no genuine client IP over MCP, so such a key is rejected.
• Set MCP_READONLY=true to mount only the read tools (no sends/writes).
• Set MCP_RATE_LIMIT_MAX (default 60) to limit tool calls per API key per window.
• Set MCP_RATE_LIMIT_WINDOW_MS (default 60000) to control the sliding window size in milliseconds.
• Do not expose /mcp to the public internet without a fronting auth proxy. For a self-hosted, locally-reached deployment the static API key is appropriate; public exposure should use OAuth 2.1 (not yet built).

🛠 Tech Stack

📁 Project Structure

``` openwa/ ├── src/ │ ├── main.ts # Application entry point │ ├── app.module.ts # Root module │ ├── config/ # Configuration │ ├── common/ # Shared utilities │ │ ├── cache/ # Redis caching │ │ └── storage/ # File storage (Local/S3) │ ├── core/ # Core systems │ │ ├── hooks/ # Plugin hooks │ │ └── plugins/ # Plugin system │ ├── engine/ # WhatsApp engine abstraction │ └── modules/ │ ├── session/ # Session management │ ├── message/ # Message handling │ ├── webho