openwa

OpenWA 是一个自托管、开源的 WhatsApp API 网关，采用 MIT 许可，技术栈为 NestJS 11 / TypeScript / Node 22。它把 whatsapp-web.js（Puppeteer + Chromium）封装在 2785 端口的 REST API 之后，并附带一个运行在 2886 端口的 React 仪表盘，支持多会话 WhatsApp 自动化，具备 webhook、Socket.IO 实时事件、可插拔的存储/缓存/数据库以及插件钩子系统。

【用途】 OpenWA 用于在自有基础设施上以 API 方式驱动一个或多个 WhatsApp 账号：创建并管理会话、扫码登录、发送各类消息、订阅事件、通过 webhook 或 WebSocket 接收实时通知。它面向需要把 WhatsApp 集成进自有系统的开发者与运维人员。

【主要能力】

多会话：每个 WhatsApp 账号对应一条持久化的 Session 记录和一个内存中的引擎实例（IWhatsAppEngine），按会话 id 索引。
REST API：全局前缀为 /api，覆盖会话、消息、webhook、API 密钥、健康检查、联系人/群组/标签/频道/状态/目录、基础设施等模块。Swagger UI 位于 http://localhost:2785/api/docs。
消息发送：支持文本、图片、视频、音频、文档、位置、联系人、贴纸，以及回复、转发、表情回应、删除、批量发送与批次取消。
Webhook：按会话订阅，支持签名（HMAC-SHA256）、重试与幂等键；在 QUEUE_ENABLED=true 时经 BullMQ 投递并重试，否则为同步尽力投递。
实时事件：Socket.IO 4.8，命名空间 /events，事件类型与 webhook 一致。
认证：基于 X-API-Key 请求头（也接受 Authorization: Bearer），密钥以哈希形式存储，角色分为 ADMIN、OPERATOR、VIEWER，可配置 IP 与会话白名单。
可插拔：引擎（IWhatsAppEngine）、存储（本地或 S3/MinIO）、缓存（内存或 Redis）均可替换；插件钩子可在消息发送前后介入。
SDK：提供 @openwa/sdk（JS/TS）与 Python 客户端。

【使用方式】部署有三条路径：本地开发用 docker compose -f docker-compose.dev.yml up -d；生产基础用 docker compose up -d；生产全栈（Postgres + Redis + MinIO + Traefik + Dashboard）用 docker compose --profile full up -d。镜像为多阶段 node:22-slim，内置 Chromium，PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium。

会话上线最小流程：

创建会话：POST /api/sessions，请求体 {"name":"bot-1"}；
启动会话：POST /api/sessions/$ID/start；
获取二维码：GET /api/sessions/$ID/qr（状态为 QR_READY 时返回 SVG），用手机 WhatsApp 扫码；
轮询状态或订阅 /events，直到状态为 READY。

聊天 id 遵循 WhatsApp Web 约定：<phone>@c.us 为私聊，<id>@g.us 为群组，<id>@newsletter 为频道；格式错误会导致静默发送失败。

认证示例：curl -H "X-API-Key: owa_k1_xxxxxxxx..." http://localhost:2785/api/sessions。密钥格式为 owa_k1_<32 字节十六进制>。首次启动若无密钥，OpenWA 会创建一个并写入 data/.api-key，同时在启动横幅中打印；开发环境（NODE_ENV=development）下引导密钥为字面量 dev-admin-key。

配置采用三层优先级：process.env > ./.env > ./data/.env.generated。注意 .env.generated 优先级最低，仪表盘保存的配置不会覆盖 Docker 环境变量。系统使用两个 TypeORM 数据库：main 连接始终为 SQLite，存储 API 密钥与审计日志；data 连接为 SQLite 或 PostgreSQL，存储会话、消息、webhook。

【适用场景】

在自有服务器上通过 API 管理多个 WhatsApp 账号并收发消息；
将 WhatsApp 消息接入自有业务系统，通过 webhook 或 WebSocket 接收事件；
需要可插拔存储、缓存、数据库与插件扩展的自动化场景。

【限制与注意事项】

每次 API 重启会把所有 READY/INITIALIZING/QR_READY/AUTHENTICATING 会话强制重置为 DISCONNECTED（引擎在内存中）。
QUEUE_ENABLED=false（默认）时 webhook 没有重试，仅为同步尽力投递。
SQLite 默认 synchronize: true，生产环境有风险；PostgreSQL 应改用迁移。
API 密钥存放在 SQLite main 库，切换 data 库到 PostgreSQL 不会迁移密钥。
会话达到 READY 之前，phone 与 pushName 为 null。
Chromium 为必需依赖，Docker 镜像硬编码了 PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium。
收费、价格、平台支持范围等资料暂未提供。

技能介绍