Open Source WhatsApp API Gateway
Features • Quick Start • Docs • API • Contributing
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 |
| Feature | Status | Description |
|---|---|---|
| REST API | ✅ | Full WhatsApp API via HTTP endpoints |
| Multi-Session | ✅ | Manage multiple WhatsApp accounts |
| Webhooks | ✅ | Real-time events with HMAC signature |
| Web Dashboard | ✅ | Visual management interface |
| API Key Auth | ✅ | Secure API authentication |
| Swagger Docs | ✅ | Interactive API documentation |
| 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 |
| 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 |
| 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 |
# Clone and start
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
docker compose -f docker-compose.dev.yml up -d
# Access
# Dashboard: http://localhost:2886
# API: http://localhost:2785/api
# Swagger: http://localhost:2785/api/docs# 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
# Dashboard: http://localhost:2886
# API: http://localhost:2785/api
# Swagger: http://localhost:2785/api/docsFor 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, Dashboard, Traefik)
docker compose --profile full up -d| Profile | Services |
|---|---|
postgres |
PostgreSQL database |
redis |
Redis cache |
minio |
S3-compatible storage |
with-dashboard |
Web dashboard |
with-proxy |
Traefik reverse proxy |
full |
All services above |
Development vs Production
- Development (
docker-compose.dev.yml): SQLite, local storage, both API & Dashboard included- Production (
docker-compose.yml): Configurable database, profiles for optional services
| Service | Port | Description |
|---|---|---|
| API | 2785 |
REST API endpoints |
| Dashboard | 2886 |
Web management interface |
| Swagger | 2785/api/docs |
Interactive API docs |
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 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"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!"
}'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"
}'| Layer | Technology |
|---|---|
| Runtime | Node.js 22 LTS |
| Framework | NestJS 11.x |
| Language | TypeScript 5.x |
| WA Engine | whatsapp-web.js |
| Database | SQLite / PostgreSQL |
| Cache | Redis (optional) |
| Storage | Local / S3 / MinIO |
| ORM | TypeORM |
| Container | Docker + Docker Compose |
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
│ ├── webhook/ # Webhook management
│ ├── group/ # Groups API
│ ├── contact/ # Contacts API
│ ├── auth/ # API key authentication
│ ├── infra/ # Infrastructure management
│ └── health/ # Health checks
├── dashboard/ # React web dashboard
├── docs/ # Documentation
├── docker-compose.yml
├── Dockerfile
└── package.json
Comprehensive documentation is available in the docs/ folder:
| Document | Description |
|---|---|
| Project Overview | Introduction and goals |
| Requirements | Feature specifications |
| Architecture | System design |
| Security | Security implementation |
| Database | Data models and migrations |
| API Spec | Complete API reference |
| Development | Coding standards |
| Migration Guide | Database & storage migration |
We welcome contributions! Here's how to get started:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please read our Development Guidelines for coding standards and best practices.
This project is licensed under the MIT License – free for personal and commercial use.
See LICENSE for details.
OpenWA – Free, Open Source WhatsApp API Gateway
📖 Documentation · 🔌 API Docs · 🐛 Report Bug · 💡 Request Feature
Made with ❤️ by Yudhi Armyndharis and the OpenWA Community