Skip to content

README.md

Latest commit

 

History

History
221 lines (172 loc) · 8.44 KB

README.md

File metadata and controls

221 lines (172 loc) · 8.44 KB

OpenWA Logo

OpenWA Documentation

Open Source WhatsApp API Gateway

Features • Quick Start • Docs • API • Contributing

Version License Node NestJS Docker TypeScript

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

Quick Start

Option A: Minimal Setup (SQLite, no Docker services)

# 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)

# 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).

API Example

# 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)

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 for coding standards and workflow.

License

MIT License.

Start Reading: 01 - Project Overview

OpenWA Documentation · Last updated: 2026-02-05