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