rmyndharis / OpenWA
rmyndharis / OpenWA
OpenWA Open Source WhatsApp API Gateway
OpenWA 开源 WhatsApp API 网关
Features • Quick Start • Docs • API • Contributing 功能 • 快速入门 • 文档 • API • 贡献指南
✨ Why OpenWA? ✨ 为什么选择 OpenWA？
OpenWA is a free, open-source WhatsApp API Gateway designed for developers who need full control over their messaging infrastructure—without vendor lock-in or hidden paywalls. Built on a pluggable architecture, OpenWA lets you swap database engines (SQLite/PostgreSQL), storage backends (Local/S3), and cache layers (Memory/Redis) without changing a single line of application code. OpenWA 是一款免费、开源的 WhatsApp API 网关，专为需要完全掌控消息基础设施的开发者而设计，无需担心供应商锁定或隐藏的付费墙。OpenWA 基于插件化架构构建，允许你在不更改任何一行应用代码的情况下，自由切换数据库引擎（SQLite/PostgreSQL）、存储后端（本地/S3）和缓存层（内存/Redis）。
🔓 100% Open Source: No licensing fees, no feature locks, full source code access 🔓 100% 开源：无许可费用，无功能锁定，完全访问源代码
🏗️ Pluggable Architecture: Swap adapters for database, storage, and cache via config 🏗️ 插件化架构：通过配置即可切换数据库、存储和缓存适配器
🖥️ Full Dashboard: Modern React UI for session, webhook, and API key management 🖥️ 完整仪表盘：现代化的 React UI，用于管理会话、Webhook 和 API 密钥
🔹 Multi-Session Ready: Run multiple WhatsApp sessions concurrently on one instance 🔹 多会话支持：在单个实例上同时运行多个 WhatsApp 会话
🐳 Docker Native: Production-ready with zero configuration 🐳 Docker 原生：零配置即可投入生产环境
🔗 n8n Integration: Community nodes for workflow automation 🔗 n8n 集成：提供用于工作流自动化的社区节点
🎯 Features (功能列表)
| Core Features | Status | Description |
|---|---|---|
| 核心功能 | 状态 | 描述 |
| REST API | ✅ | Full WhatsApp API via HTTP endpoints (通过 HTTP 端点提供完整的 WhatsApp API) |
| Multi-Session | ✅ | Manage multiple WhatsApp accounts (管理多个 WhatsApp 账号) |
| Webhooks | ✅ | Real-time events with HMAC signature (带 HMAC 签名的实时事件) |
| Web Dashboard | ✅ | Visual management interface (可视化管理界面) |
| API Key Auth | ✅ | Secure API authentication (安全的 API 认证) |
| Swagger Docs | ✅ | Interactive API documentation (交互式 API 文档) |
| Messaging | Status | Description |
|---|---|---|
| 消息功能 | 状态 | 描述 |
| Text Messages | ✅ | Send/receive text messages (发送/接收文本消息) |
| Media Messages | ✅ | Images, videos, documents, audio (图片、视频、文档、音频) |
| Message Reactions | ✅ | React to messages with emoji (使用表情符号回应消息) |
| Bulk Messaging | ✅ | Send to multiple recipients (群发消息) |
| Message Status | ✅ | Track delivery and read receipts (追踪送达和已读回执) |
| Advanced | Status | Description |
|---|---|---|
| 高级功能 | 状态 | 描述 |
| Groups API | ✅ | Create, manage, and message groups (创建、管理及群组消息) |
| Channels/Newsletter | ✅ | WhatsApp Channels support (支持 WhatsApp 频道) |
| Labels Management | ✅ | Organize chats with labels (使用标签整理聊天) |
| Proxy Support | ✅ | Per-session proxy configuration (支持按会话配置代理) |
| Rate Limiting | ✅ | Configurable request limits (可配置的请求限制) |
| CIDR Whitelisting | ✅ | IP-based access control (基于 IP 的访问控制) |
| Audit Logging | ✅ | Track all API operations (追踪所有 API 操作) |
| Infrastructure | Status | Description |
|---|---|---|
| 基础设施 | 状态 | 描述 |
| SQLite | ✅ | Zero-config embedded database (零配置嵌入式数据库) |
| PostgreSQL | ✅ | Production-grade database (生产级数据库) |
| Redis Cache | ✅ | Optional performance caching (可选的性能缓存) |
| S3/MinIO Storage | ✅ | Scalable media storage (可扩展的媒体存储) |
| Docker | ✅ | One-command deployment (一键部署) |
| Health Checks | ✅ | Kubernetes-ready probes (支持 Kubernetes 健康检查) |
| Data Migration | ✅ | Export/import between backends (后端间数据导出/导入) |
🚀 Quick Start (快速入门)
Option A: Docker (Recommended) 选项 A：Docker（推荐）
# Clone and start
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
docker compose -f docker-compose.dev.yml up -d
# Access
# Dashboard: http://localhost:2886
# API: http://localhost:2785/api
# Swagger: http://localhost:2785/api/docsOption B: Local Development 选项 B：本地开发
# Clone repository
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
# Install dependencies (includes dashboard)
npm install
# Start API + Dashboard (config is auto-generated on first run)
npm run dev🏭 Production Deployment (生产环境部署)
For production, use the main docker-compose.yml with optional services:
对于生产环境，请使用主 docker-compose.yml 并根据需要选择服务：
# Basic production (SQLite, local storage)
docker compose up -d
# With PostgreSQL database
docker compose --profile postgres up -d
# Full stack (PostgreSQL, Redis, Dashboard, Traefik)
docker compose --profile full up -d🛠 Tech Stack (技术栈)
| Layer | Technology |
|---|---|
| 层级 | 技术 |
| Runtime | Node.js 22 LTS |
| Framework | NestJS 11.x |
| Language | TypeScript 5.x |
| WA Engine | whatsapp-web.js |
| Database | SQLite / PostgreSQL |
| Cache | Redis (optional) |
| Storage | Local / S3 / MinIO |
| ORM | TypeORM |
| Container | Docker + Docker Compose |
📚 Documentation (文档)
Comprehensive documentation is available in the docs/ folder:
详细文档可在 docs/ 文件夹中查看：
- Project Overview: Introduction and goals (项目概述：介绍与目标)
- Requirements: Feature specifications (需求：功能规格)
- Architecture: System design (架构：系统设计)
- Security: Security implementation (安全：安全实现)
- Database: Data models and migrations (数据库：数据模型与迁移)
- API Spec: Complete API documentation (API 规范：完整 API 文档)