OpenWA Documentation
Open Source WhatsApp API Gateway
Features •
Quick Start •
Docs •
API •
Contributing
---
## Documentation Map
**Full Index (by number)**
| No | Document | Description |
| --- | ---------------------------------------------------------------- | ------------------------------------------------- |
| 01 | [Project Overview](./01-project-overview.md) | Vision, goals, scope, current status |
| 02 | [Requirements Specification](./02-requirements-specification.md) | Functional and non-functional requirements |
| 03 | [System Architecture](./03-system-architecture.md) | Architecture, modules, and runtime flows |
| 04 | [Security Design](./04-security-design.md) | Auth, rate limiting, and security controls |
| 05 | [Database Design](./05-database-design.md) | Entities and storage considerations |
| 06 | [API Specification](./06-api-specification.md) | REST API and WebSocket protocol |
| 07 | [API Collection](./07-api-collection.md) | Example requests and Postman import tips |
| 08 | [Development Guidelines](./08-development-guidelines.md) | Coding standards and workflow |
| 09 | [Testing Strategy](./09-testing-strategy.md) | Test types and tooling |
| 10 | [DevOps & Infrastructure](./10-devops-infrastructure.md) | Docker, deployment, and environment configuration |
| 11 | [Operational Runbooks](./11-operational-runbooks.md) | Incident, maintenance, and backup runbooks |
| 12 | [Troubleshooting FAQ](./12-troubleshooting-faq.md) | Common issues and fixes |
| 13 | [Horizontal Scaling](./13-horizontal-scaling.md) | Multi-node deployment guidance |
| 14 | [Migration Guide](./14-migration-guide.md) | Upgrade and data migration guidance |
| 15 | [Project Roadmap](./15-project-roadmap.md) | Near-term and long-term roadmap |
| 16 | [Risk Management](./16-risk-management.md) | Risks and mitigations |
| 17 | [Dashboard Design](./17-dashboard-design.md) | Dashboard UX overview |
| 18 | [SDK Design](./18-sdk-design.md) | SDK plans and conventions |
| 19 | [Plugin Architecture](./19-plugin-architecture.md) | Extensibility concepts |
| 20 | [Community Guidelines](./20-community-guidelines.md) | Contribution and governance |
| 21 | [Glossary](./21-glossary.md) | Terms and definitions |
| 22 | [n8n Integration](./22-n8n-integration.md) | n8n community nodes for OpenWA |
## Quick Start
### Option A: Minimal Setup (SQLite, no Docker services)
```bash
# Clone repository
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
# Install & configure
npm install
cp .env.minimal .env
# Create data directories
mkdir -p data/sessions data/media
# Run
npm run start:dev
```
Access:
- API: `http://localhost:2785/api`
- Swagger: `http://localhost:2785/api/docs`
- Health: `http://localhost:2785/api/health`
### Option B: Docker (Traefik + API + Dashboard)
```bash
# Clone repository
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
# Start services
docker compose up -d
```
Access:
- Dashboard: `http://localhost:2886`
- API: `http://localhost:2785/api`
- Swagger: `http://localhost:2785/api/docs`
- Traefik (optional): `http://localhost:2886/api`
### API Key
OpenWA seeds a default API key on first run and writes it to:
- `data/.api-key` (development)
You can also create new keys via the API (see [API Specification](./06-api-specification.md)).
## 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": "628123456789@c.us", "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: 'sess_abc123',
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 + Traefik 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 / Catalog API | Experimental (engine-limited) |
| Queue-based Webhook Retries | Optional (QUEUE_ENABLED=true) |
## Tech Stack
| Layer | Technology |
| --------- | ----------------------------- |
| Runtime | Node.js 20 LTS |
| Framework | NestJS 11.x |
| Language | TypeScript 5.x |
| WA Engine | whatsapp-web.js |
| WebSocket | Socket.IO |
| Database | SQLite (default) / PostgreSQL |
| ORM | TypeORM |
| Container | Docker + Docker Compose |
| Dashboard | React + Vite + TanStack Query |
## Project Structure
```
OpenWA/
├── src/ # Backend source code
├── dashboard/ # Frontend dashboard
├── docker-compose.yml # Traefik + API + Dashboard
├── docker-compose.dev.yml # Dev-only compose
├── docs/ # Project documentation
└── data/ # Local runtime data (sessions, media, api key)
```
## Contributing
See [Development Guidelines](./08-development-guidelines.md) for coding standards and workflow.
## License
MIT License.
---
**Start Reading: [01 - Project Overview](./01-project-overview.md)**
_OpenWA Documentation · Last updated: 2026-02-05_