企业微信回调（自建应用）
通过回调/Webhook 模式，将 Hermes 集成到企业微信作为自建企业应用。
企业微信机器人 vs 企业微信回调
Hermes 支持两种企业微信集成方式：
- 企业微信机器人 — 机器人模式，通过 WebSocket 连接。设置简单，可在群聊中使用。
- 企业微信回调（本页内容）—— 自建应用，接收加密的 XML 回调消息。在用户的企业微信侧边栏中以原生应用形式展示。支持跨企业路由。
工作原理
- 在企业微信管理后台注册一个自建应用
- 企业微信将加密的 XML 数据推送到你的 HTTP 回调端点
- Hermes 解密消息，并将其加入代理队列
- 立即返回确认（静默处理——用户无感知）
- 代理处理请求（通常耗时 3–30 分钟）
- 回复通过企业微信的
message/sendAPI 主动推送
前置条件
- 拥有具备管理员权限的企业微信企业账号
- 安装
aiohttp和httpxPython 包（默认安装已包含） - 一台可公网访问的服务器用于回调 URL（或使用 ngrok 等隧道工具）
配置步骤
1. 在企业微信中创建自建应用
- 访问 企业微信管理后台 → 应用管理 → 创建应用
- 记录你的 企业 ID（Corp ID）（位于管理后台顶部）
- 在应用设置中创建一个 企业凭证（Corp Secret）
- 记录应用概览页中的 应用 Agent ID
- 在 接收消息 设置中配置回调地址：
- 地址（URL）：`http://YOUR_PUBLIC_IP:8645/wecom/callback``
- Token：生成一个随机 Token（企业微信提供）
- EncodingAESKey：生成一个密钥（企业微信提供）
2. 配置环境变量
将以下内容添加至你的 .env 文件中：
WECOM_CALLBACK_CORP_ID=your-corp-id
WECOM_CALLBACK_CORP_SECRET=your-corp-secret
WECOM_CALLBACK_AGENT_ID=1000002
WECOM_CALLBACK_TOKEN=your-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY=your-43-char-aes-key
# Optional
WECOM_CALLBACK_HOST=0.0.0.0
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2
3. 启动网关服务
hermes gateway start
回调适配器会启动一个 HTTP 服务器，监听配置的端口。企业微信会通过 GET 请求验证回调地址，随后开始通过 POST 发送消息。
配置参考
在 config.yaml 文件中 platforms.wecom_callback.extra 下设置以下参数，或使用环境变量：
| 参数 | 默认值 | 说明 |
|---|---|---|
corp_id | — | 企业微信企业 Corp ID（必填） |
corp_secret | — | 自建应用的企业凭证（Corp Secret，必填） |
agent_id | — | 自建应用的 Agent ID（必填） |
token | — | 回调验证 Token（必填） |
encoding_aes_key | — | 43 字符的 AES 加密密钥（用于回调加密，必填） |
host | 0.0.0.0 | HTTP 回调服务器绑定地址 |
port | 8645 | HTTP 回调服务器监听端口 |
path | /wecom/callback | 回调端点的 URL 路径 |
多应用路由
对于运行多个自建应用的企业（如不同部门或子公司），可在 config.yaml 中配置 apps 列表：
platforms:
wecom_callback:
enabled: true
extra:
host: "0.0.0.0"
port: 8645
apps:
- name: "dept-a"
corp_id: "ww_corp_a"
corp_secret: "secret-a"
agent_id: "1000002"
token: "token-a"
encoding_aes_key: "key-a-43-chars..."
- name: "dept-b"
corp_id: "ww_corp_b"
corp_secret: "secret-b"
agent_id: "1000003"
token: "token-b"
encoding_aes_key: "key-b-43-chars..."
用户按 corp_id:user_id 进行作用域划分，防止跨企业冲突。当用户发送消息时，适配器会记录其所属的应用（企业），并使用对应应用的访问令牌回复。
访问控制
限制可与应用交互的用户范围：
# Allowlist specific users
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu
# Or allow all users
WECOM_CALLBACK_ALLOW_ALL_USERS=true
接口端点
适配器暴露以下接口：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /wecom/callback | URL 验证握手（企业微信在配置阶段发送） |
| POST | /wecom/callback | 加密消息回调（企业微信将用户消息发送至此） |
| GET | /health | 健康检查 — 返回 {"status": "ok"} |
加密机制
所有回调数据均使用 AES-CBC 加密，密钥为 EncodingAESKey。适配器负责：
- 入站：解密 XML 数据包，验证 SHA1 签名
- 出站：回复通过主动推送 API 发送（不使用回调加密）
加密实现与腾讯官方 WXBizMsgCrypt SDK 兼容。
限制说明
- 不支持流式传输 —— 回复以完整消息形式返回，待代理处理完成后送达
- 不支持输入状态提示 —— 回调模型不支持“正在输入”状态
- 仅支持文本输入 —— 当前仅支持文本消息；图片、文件、语音等输入暂未实现。但代理可通过企业微信平台提示了解自身具备输出多媒体的能力（如图片、文档、视频、语音）
- 响应延迟较高 —— 代理会话耗时 3–30 分钟；用户需等待处理完成才可见回复