OpenWA：免费开源的自托管WhatsApp API网关

这是什么

OpenWA 是一个基于 TypeScript 构建的免费、开源 WhatsApp API 网关。它由 Yudhi Armyndharis 发起，旨在为开发者提供一个完全掌控消息基础设施的解决方案，彻底摆脱传统 WhatsApp Business API 供应商的锁定（Vendor Lock-in）和隐藏的费用门槛。

该项目目前 GitHub 星标数约为 6690，主语言为 TypeScript。其核心架构采用插件化设计，允许开发者在不修改应用代码的前提下，灵活替换底层数据库引擎（SQLite/PostgreSQL）、存储后端（Local/S3）以及缓存层（Memory/Redis）。除了提供标准的 RESTful API，OpenWA 还内置了一个基于 React 的 Web Dashboard，方便开发者直观地管理会话、监控消息状态及配置 Webhook。

解决的问题

1. 供应商锁定与成本不可控：传统的 WhatsApp Business API 通常需要通过 Meta 官方合作伙伴（BSP）接入，这不仅涉及复杂的认证流程，还可能产生按会话计费的高昂费用，且数据控制权受限。OpenWA 通过直接对接 WhatsApp Web 协议，提供了零许可费的替代方案。
2. 基础设施黑盒化：许多商业网关将底层实现封装在黑盒中，开发者难以根据业务需求优化存储或缓存策略。OpenWA 的插件化架构解决了这一问题，允许团队根据自身的云原生需求（如使用 S3 存储媒体文件，或使用 Redis 提升并发性能）自定义基础设施。
3. 开发体验割裂：纯 API 网关往往缺乏可视化管理工具，调试和监控困难。OpenWA 将 API 服务与 React Dashboard 打包在一起，实现了从会话创建、二维码扫描到消息发送的全链路可视化操作，降低了调试门槛。

核心功能

• 多会话管理：支持创建多个 WhatsApp 会话实例，每个会话独立运行，互不干扰。
• 全功能消息收发：
  • 支持发送文本消息、富媒体文件（图片、文档、视频等）。
  • 支持群组消息发送与管理。
  • 支持联系人列表查询与状态更新。
• Webhook 事件驱动：提供灵活的 Webhook 配置接口，支持订阅 message.received（接收消息）、session.status（会话状态变更）等事件，并支持 HMAC 签名验证以确保数据完整性。
• 插件化架构：
  • 存储后端：默认支持本地存储，可无缝切换至 AWS S3 等对象存储。
  • 数据库：开发环境默认使用 SQLite，生产环境支持 PostgreSQL，确保数据持久化的可靠性。
  • 缓存：集成 Redis 或 Memory 缓存，提升高频消息处理的响应速度。
• 内置 Dashboard：基于 React 构建的管理界面，提供会话管理、消息历史查看、API Key 生成及系统健康检查等功能。
• API 文档：自动生成 Swagger/OpenAPI 文档，方便前端或第三方系统集成。

亮点 / 与同类相比

1. 极致的可配置性（Pluggable Architecture）： 与许多硬编码依赖特定数据库或存储的开源项目不同，OpenWA 允许在运行时或部署时通过 docker-compose profiles 轻松切换后端。例如，只需一条命令 docker compose --profile postgres up -d 即可启用 PostgreSQL，无需修改任何业务代码。

2. 开箱即用的全栈体验： 大多数 WhatsApp 开源项目仅提供后端 API，开发者需自行搭建前端监控面板。OpenWA 直接集成了 Dashboard，使得从克隆代码到可视化管理只需几分钟，极大缩短了从开发到部署的路径。

3. 清晰的开发/生产环境隔离： 项目提供了明确的 docker-compose.dev.yml 和 docker-compose.yml 区分。开发环境轻量级（SQLite + Local Storage + 内置 Dashboard），生产环境则支持 Traefik 反向代理、Redis 缓存集群等高可用配置，符合企业级部署标准。

4. MIT 开源协议： 采用 MIT 许可证，允许个人和商业用户免费使用、修改和分发，无版权顾虑，适合构建商业级 SaaS 产品。

适合谁用 / 上手

适合人群：

• 独立开发者与初创团队：需要低成本快速搭建 WhatsApp 客服机器人、营销工具或通知系统，且希望保留数据主权的团队。
• 企业级后端工程师：需要集成 WhatsApp 渠道到现有 CRM 或 ERP 系统，且对基础设施有高度定制化需求（如私有化部署 S3 存储）的技术团队。
• 技术选型者：正在评估 WhatsApp API 接入方案，希望避免 BSP 长期合同约束的架构师。

上手指南：

1. 环境准备： 确保本地已安装 Git、Node.js (npm) 和 Docker。

2. 快速启动（推荐 Docker 方式）：

   # 克隆仓库
   git clone https://github.com/rmyndharis/OpenWA.git
   cd OpenWA
   
   # 启动开发环境（包含 API 和 Dashboard）
   docker compose -f docker-compose.dev.yml up -d
   

3. 访问服务：

   • Dashboard: http://localhost:2886
   • API 接口: http://localhost:2785/api
   • Swagger 文档: http://localhost:2785/api/docs

4. 初始化会话： 通过 API 创建会话并获取 QR 码，使用 WhatsApp 手机 App 扫码登录：

   # 创建会话
   curl -X POST http://localhost:2785/api/sessions \
   -H "Content-Type: application/json" \
   -H "X-API-Key: YOUR_API_KEY" \
   -d '{"name": "my-bot"}'
   
   # 获取 QR 码
   curl http://localhost:2785/api/sessions/{sessionId}/qr \
   -H "X-API-Key: YOUR_API_KEY"
   

5. 生产环境部署： 对于生产环境，建议使用标准的 docker-compose.yml 并启用所需 Profile（如 postgres 或 full），以启用持久化数据库和缓存服务。