Skip to content

README.md

Latest commit

 

History

History
242 lines (191 loc) · 10.3 KB

README.md

File metadata and controls

242 lines (191 loc) · 10.3 KB
Raw

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
10-ID Panduan Docker (ID) Panduan deployment Docker dalam Bahasa Indonesia
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
23-S Plugin Sandboxing Worker isolation, capabilities, and plugin limits
24 MCP Integration Model Context Protocol tools and auth model
25 Integration Fabric Inbound webhook substrate for plugin integrations

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

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 (single container: API + Dashboard)

# Clone repository
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA

# Start services
docker compose up -d

Access (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

API Key

OpenWA seeds a default API key on first run and writes it to:

  • data/.api-key (development)
  • /app/data/.api-key inside the API container when using Docker

The startup logs also print the initial key. By default a cryptographically random owa_k1_... admin key is generated on first run in all environments; set ALLOW_DEV_API_KEY=true to seed the well-known dev-admin-key for local development only. Use an admin key to create additional keys with POST /api/auth/api-keys (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": "[email protected]", "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 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)
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 5.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

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.

Start Reading: 01 - Project Overview

OpenWA Documentation · Last updated: 2026-06-18