OpenWA Documentation
Documentation Map
Full Index (by number)
| No | Document | Description |
|---|---|---|
| 01 | Project Overview | Vision, goals, scope, current status |
| 02 | Requirements Specification | Functional and non-functional requirements |
| 03 | System Architecture | Architecture, modules, and runtime flows |
| 04 | Security Design | Auth, rate limiting, and security controls |
| 05 | Database Design | Entities and storage considerations |
| 06 | API Specification | REST API and WebSocket protocol |
| 07 | API Collection | Example requests and Postman import tips |
| 08 | Development Guidelines | Coding standards and workflow |
| 09 | Testing Strategy | Test types and tooling |
| 10 | DevOps & Infrastructure | Docker, deployment, and environment configuration |
| 11 | Operational Runbooks | Incident, maintenance, and backup runbooks |
| 12 | Troubleshooting FAQ | Common issues and fixes |
| 13 | Horizontal Scaling | Multi-node deployment guidance |
| 14 | Migration Guide | Upgrade and data migration guidance |
| 15 | Project Roadmap | Near-term and long-term roadmap |
| 16 | Risk Management | Risks and mitigations |
| 17 | Dashboard Design | Dashboard UX overview |
| 18 | SDK Design | SDK plans and conventions |
| 19 | Plugin Architecture | Extensibility concepts |
| 20 | Community Guidelines | Contribution and governance |
| 21 | Glossary | Terms and definitions |
| 22 | n8n Integration | n8n community nodes for OpenWA |
| 23 | Community Integrations | Third-party adapters built on the OpenWA API |
| 24 | MCP Integration | Model Context Protocol tools and auth model |
| 25 | Integration Fabric | Inbound webhook substrate for plugin integrations |
| 26 | Global Search | Cross-session message search and the provider model |
| 27 | Plugin Search Providers | Writing a search-provider plugin |
| 28 | Multitenancy | Multi-tenant target design (draft proposal) |
| 29 | Engine Capability Matrix | Per-engine capability support, gaps, and roadmap |
| 30 | Plugin Sandboxing | Worker isolation, capabilities, and plugin limits |
| 31 | Session Lifecycle: Invariant Catalog | The race windows the lifecycle defends, where each is defended, which spec pins it |
Examples
| Example | Description |
|---|---|
| Session Phone-Number Pairing | Link an existing WhatsApp account by phone number instead of scanning QR |
| Chat History Limits | Understand local message history vs bounded live WhatsApp history |
| Webhook Signature Verification | Verify signed OpenWA webhook deliveries in Node.js and Python |
| n8n Appointment Booking Workflow | Build an appointment-booking flow with OpenWA and n8n |
| n8n to Discord Workflow | Forward incoming WhatsApp messages to Discord with n8n's built-in nodes |
Quick Start
Option A: Minimal Setup (SQLite, no Docker services)
bash
# Clone repository
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
# Install the locked dependencies (also installs dashboard dependencies)
npm ci
# Optional: .env.minimal pins database, storage, Redis/queue, session path, engine and Puppeteer
# settings over Dashboard > Infrastructure, and turns off session auto-start
# cp .env.minimal .env
# Run the API and the dashboard
npm run devAccess:
- Dashboard:
http://localhost:2886 - API:
http://localhost:2785/api - Swagger:
http://localhost:2785/api/docs - Health:
http://localhost:2785/api/health
Option B: Docker (single container: API + Dashboard)
bash
# Clone repository
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
# Start services
docker compose up -dAccess (the dashboard is bundled into the API and served on the same port):
- Dashboard:
http://localhost:2785 - API:
http://localhost:2785/api - Swagger:
http://localhost:2785/api/docs(off under this compose file'sNODE_ENV=productionunlessENABLE_SWAGGER=true)
API Key
OpenWA seeds a default API key on first run and writes it to:
data/.api-key(development)/app/data/.api-keyinside the API container when using Docker
With Docker, read it with docker exec openwa-api cat /app/data/.api-key. The file has no trailing newline, so copy only the key.
The startup log prints the full key only on the boot that created it; later boots show a masked prefix. By default a cryptographically
random owa_k1_... admin key is generated on first run in all environments; setALLOW_DEV_API_KEY=true to seed the well-known dev-admin-key for local
development only. Use an admin key to create additional keys withPOST /api/auth/api-keys (see
API Specification).
API Example
bash
# Create a session
curl -X POST http://localhost:2785/api/sessions \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-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 (base64)
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 "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"chatId": "[email protected]", "text": "Hello from OpenWA!"}'WebSocket Example (Socket.IO)
javascript
import { io } from 'socket.io-client';
const socket = io('http://localhost:2785/events', {
extraHeaders: { 'X-API-Key': 'your-api-key' },
transports: ['websocket'],
});
socket.on('connect', () => {
socket.emit('message', {
type: 'subscribe',
sessionId: '550e8400-e29b-41d4-a716-446655440000',
events: ['message.received', 'session.status'],
requestId: 'req_001',
});
});
socket.on('message', msg => {
if (msg.type === 'event') {
console.log('Event:', msg.payload.event, msg.payload.data);
}
});Features (Current)
| Feature | Status |
|---|---|
| REST API for WhatsApp | Ready |
| WebSocket Events (Socket.IO) | Ready |
| Multi-session Support | Ready |
| Web Dashboard | Ready |
| Docker Deployment | Ready |
| Webhooks with HMAC Signature | Ready |
| SQLite / PostgreSQL Storage | Ready |
| API Key Authentication & Roles | Ready |
| CIDR IP Whitelisting | Ready |
| Rate Limiting | Ready |
| Audit Logging | Ready |
| Groups / Contacts / Labels API | Ready |
| Channels / Status API | Experimental (engine-limited) |
| Catalog / Product API | Baileys only (whatsapp-web.js answers 501) |
| Pluggable Engine (wwebjs / Baileys) | Ready (set ENGINE_TYPE) |
| Plugin Extension System | Ready |
| Queue-based Webhook Retries | Optional (QUEUE_ENABLED=true) |
Tech Stack
| Layer | Technology |
|---|---|
| Runtime | Node.js 22 LTS |
| Framework | NestJS 11.x |
| Language | TypeScript 6.x |
| WA Engine | Pluggable (ENGINE_TYPE): whatsapp-web.js (default) or Baileys |
| WebSocket | Socket.IO |
| Database | SQLite (default) / PostgreSQL |
| ORM | TypeORM |
| Container | Docker + Docker Compose |
| Dashboard | React + Vite + TanStack Query |
Project Structure
text
OpenWA/
├── src/ # Backend source code
├── dashboard/ # Frontend dashboard
├── docker-compose.yml # API (serves bundled dashboard) + optional datastores
├── docker-compose.dev.yml # Dev-only compose
├── docs/ # Project documentation
└── data/ # Local runtime data (sessions, media, api key)Contributing
See Development Guidelines for coding standards and workflow.
License
MIT License.