wehub-resource-sync
4ce4204b6c
CI / Lint (push) Failing after 2s
CI / Build (push) Has been skipped
SDK CI / PHP SDK (push) Failing after 1s
Split PHP SDK / PHP SDK tests (push) Failing after 1s
CI / Test (push) Failing after 1s
CI / Dashboard (push) Failing after 0s
SDK CI / JavaScript SDK (push) Failing after 0s
SDK CI / Python SDK (push) Failing after 2s
SDK CI / Java SDK (push) Failing after 1s
Split PHP SDK / Mirror sdk/php -> rmyndharis/openwa-php (push) Has been skipped
CI / Test (PostgreSQL migrations) (push) Failing after 7m47s
CI / Docker Build (push) Has been skipped
244 lines
10 KiB
Markdown
244 lines
10 KiB
Markdown
<p align="center">
|
|
<img src="logo/openwa_logo.webp" alt="OpenWA Logo" width="200"/>
|
|
</p>
|
|
|
|
<h1 align="center">OpenWA Documentation</h1>
|
|
<p align="center">
|
|
<strong>Open Source WhatsApp API Gateway</strong>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="#features-current">Features</a> •
|
|
<a href="#quick-start">Quick Start</a> •
|
|
<a href="#documentation-map">Docs</a> •
|
|
<a href="#api-example">API</a> •
|
|
<a href="#contributing">Contributing</a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img src="https://img.shields.io/github/package-json/v/rmyndharis/OpenWA?label=version&color=blue" alt="Version"/>
|
|
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"/>
|
|
<img src="https://img.shields.io/badge/node-22_LTS-brightgreen.svg" alt="Node"/>
|
|
<img src="https://img.shields.io/badge/NestJS-11.x-red.svg" alt="NestJS"/>
|
|
<img src="https://img.shields.io/badge/docker-ready-blue.svg" alt="Docker"/>
|
|
<img src="https://img.shields.io/badge/TypeScript-5.x-3178C6.svg" alt="TypeScript"/>
|
|
</p>
|
|
|
|
---
|
|
|
|
## 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 |
|
|
| 10-ID| [Panduan Docker (ID)](./DOCKER_ID.md) | Panduan deployment Docker dalam Bahasa Indonesia |
|
|
| 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 |
|
|
| 23 | [Community Integrations](./23-community-integrations.md) | Third-party adapters built on the OpenWA API |
|
|
| 23-S| [Plugin Sandboxing](./23-plugin-sandboxing.md) | Worker isolation, capabilities, and plugin limits |
|
|
| 24 | [MCP Integration](./24-mcp-integration.md) | Model Context Protocol tools and auth model |
|
|
| 25 | [Integration Fabric](./25-integration-fabric.md) | Inbound webhook substrate for plugin integrations |
|
|
| 26 | [Global Search](./26-global-search.md) | Cross-session message search and the provider model |
|
|
|
|
**Examples**
|
|
|
|
| Example | Description |
|
|
| ------- | ----------- |
|
|
| [Session Phone-Number Pairing](./examples/session-phone-number-pairing.md) | Link an existing WhatsApp account by phone number instead of scanning QR |
|
|
| [Chat History Limits](./examples/chat-history-limits.md) | Understand local message history vs bounded live WhatsApp history |
|
|
| [Webhook Signature Verification](./examples/webhook-signature-verification.md) | Verify signed OpenWA webhook deliveries in Node.js and Python |
|
|
| [n8n Appointment Booking Workflow](./examples/n8n-appointment-booking.md) | Build an appointment-booking flow with OpenWA and n8n |
|
|
|
|
## 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 (single container: API + Dashboard)
|
|
|
|
```bash
|
|
# 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](./06-api-specification.md#api-key-management)).
|
|
|
|
## 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 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](./08-development-guidelines.md) for coding standards and workflow.
|
|
|
|
## License
|
|
|
|
MIT License.
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
**Start Reading: [01 - Project Overview](./01-project-overview.md)**
|
|
|
|
_OpenWA Documentation · Last updated: 2026-06-18_
|
|
|
|
</div>
|