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.

🔓 100% Open Source	No licensing fees, no feature locks, full source code access
🏗️ Pluggable Architecture	Swap adapters for database, storage, and cache 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
🔗 n8n Integration	Community nodes for workflow automation
🧩 Community Adapters	Third-party integrations (e.g. ioBroker) — see docs

---

🎯 Features

Core Features

Feature	Status	Description
REST API	✅	Full WhatsApp API via HTTP endpoints
Multi-Session	✅	Manage multiple WhatsApp accounts
Webhooks	✅	Real-time events with HMAC signature and optional smart pre-dispatch filters
Web Dashboard	✅	Visual management interface
API Key Auth	✅	Secure API authentication
Swagger Docs	✅	Interactive API documentation

Messaging

Feature	Status	Description
Text Messages	✅	Send/receive text messages
Media Messages	✅	Images, videos, documents, audio
Message Reactions	✅	React to messages with emoji
Bulk Messaging	✅	Send to multiple recipients
Message Status	✅	Track delivery and read receipts

Advanced

Feature	Status	Description
Groups API	✅	Create, manage, and message groups
Channels/Newsletter	✅	WhatsApp Channels support
Labels Management	✅	Organize chats with labels
Proxy Support	✅	Per-session proxy configuration
Rate Limiting	✅	Configurable request limits
CIDR Whitelisting	✅	IP-based access control
Audit Logging	✅	Track all API operations

Infrastructure

Feature	Status	Description
SQLite	✅	Zero-config embedded database
PostgreSQL	✅	Production-grade database
Redis Cache	✅	Optional performance caching
S3/MinIO Storage	✅	Scalable media storage
Docker	✅	One-command deployment
Health Checks	✅	Kubernetes-ready probes
Data Migration	✅	Export/import between backends

---

🚀 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:

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

Profile	Services
postgres	PostgreSQL database
redis	R