penwa 用于在终端中通过 curl 调用 OpenWA WhatsApp 服务器的 REST API，完成 WhatsApp 消息发送与会话管理。它不是独立的 WhatsApp 客户端，使用前提是已经部署并运行 OpenWA 服务端，并具备可用的 API 密钥。
主要能力
- 会话管理：创建会话、查看会话详情、获取登录二维码、轮询连接状态，以及注销和删除会话；会话可附带 Webhook。
- 消息发送：支持文本、图片、视频、音频（可设为语音气泡）、文档、位置和联系人卡片；媒体可通过 URL 或 base64 数据提供。
- 批量发送：支持提交批量任务，查询批次状态与进度，并取消批次。
- 联系人与群组：可列出联系人、检查号码是否开通 WhatsApp、获取头像；可列出群组、查看群信息与成员，以及创建群组。
- Webhook：可为会话注册 Webhook、列出和删除 Webhook，事件包括消息接收、消息确认和会话状态等。
- API 密钥管理（需管理员角色）：可创建带角色、允许 IP、允许会话和过期时间的密钥，并支持列出、查看、更新、撤销和删除。
- 健康检查：提供公共健康检查和需要鉴权的详细健康检查。
使用方式
先设置环境变量 OPENWA_BASE_URL 与 OPENWA_API_KEY，再拼接出 BASE 变量（所有路径前缀为 /api）。鉴权使用 X-API-Key 请求头，除公共的 GET /health 外，其他调用都需要携带该请求头。典型流程为：检查服务健康状态→验证密钥→创建会话→获取二维码并用 WhatsApp 扫描→轮询会话状态直至连接→调用发送接口。chatId 格式为个人 <国家码><号码>@c.us，群组为 <id>@g.us，不能包含加号、空格或短横线。实时事件可通过 WebSocket 订阅。
适用场景 适合将 WhatsApp 消息能力接入自动化流程、脚本或内部系统，例如发送通知、批量触达、管理群组和联系人，以及通过 Webhook 接收消息事件。
限制与注意 必须在已有 OpenWA 服务器和有效 API 密钥的前提下使用；二维码为二进制，应保存为文件查看；401 通常表示请求头名称或密钥错误；向未知号码发送前建议先检查其是否开通 WhatsApp；API 密钥管理需要管理员角色。资料未说明 OpenWA 服务的部署方式、费用或平台兼容性，暂未提供。