跳到主要内容

WeCom Callback（自建应用）

通过 callback / webhook 模式，将 Hermes 作为企业自建应用接入 WeCom（企业微信）。

WeCom Bot vs WeCom Callback

Hermes 支持两种 WeCom 集成方式：

  • WeCom Bot：bot 风格，通过 WebSocket 连接，设置更简单，更适合群聊。
  • WeCom Callback（本页）：自建应用模式，接收加密 XML callback，在用户侧会以正式应用的形式出现在 WeCom 侧边栏中，并支持多企业路由。

工作原理​

  1. 你在 WeCom 管理后台注册一个自建应用
  2. WeCom 把加密 XML 推送到你的 HTTP callback 端点
  3. Hermes 解密消息，并把它排队交给 agent
  4. 立即返回确认（静默，不会在用户侧显示）
  5. agent 处理请求（通常需要 3–30 分钟）
  6. 最终回复通过 WeCom message/send API 主动发送回去

前提条件​

  • 一个具备管理员权限的 WeCom 企业账号
  • Python 包 aiohttp 和 httpx（默认安装通常已包含）
  • 一个公网可访问的 callback URL（或使用 ngrok 之类的隧道）

设置​

1. 在 WeCom 中创建自建应用​

  1. 打开 WeCom Admin Console → Applications → Create App
  2. 记录 Corp ID（管理后台顶部可见）
  3. 在应用设置中创建 Corp Secret
  4. 从应用概览页记录 Agent ID
  5. 在 Receive Messages 中配置 callback：
    • URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
    • Token: 使用 WeCom 生成的 token
    • EncodingAESKey: 使用 WeCom 生成的密钥

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

Callback 适配器会在配置的端口上启动 HTTP 服务器。WeCom 会先通过 GET 请求验证 callback URL，随后再通过 POST 发送消息。

配置参考​

你可以在 config.yaml 的 platforms.wecom_callback.extra 下配置，或使用环境变量：

SettingDefaultDescription
corp_id—WeCom 企业 Corp ID（必需）
corp_secret—自建应用的 Corp Secret（必需）
agent_id—自建应用的 Agent ID（必需）
token—callback 验证 token（必需）
encoding_aes_key—43 字符 AES key（必需）
host0.0.0.0HTTP callback 服务绑定地址
port8645HTTP callback 服务端口
path/wecom/callbackcallback URL 路径

Multi-App Routing​

如果企业内部运行多个自建应用（例如不同部门或子公司），可以在 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 作为作用域，避免跨企业冲突。适配器会记录每位用户属于哪个 app / corp，并确保回复通过正确的 access token 发送。

访问控制​

你可以限制允许使用该应用的用户：

# Allowlist specific users
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Or allow all users
WECOM_CALLBACK_ALLOW_ALL_USERS=true

端点​

MethodPathPurpose
GET/wecom/callbackURL 验证握手
POST/wecom/callback加密消息 callback
GET/health健康检查，返回 {"status": "ok"}

加密​

所有 callback payload 都使用 EncodingAESKey 通过 AES-CBC 加密。适配器负责：

  • 入站：解密 XML payload，并校验 SHA1 签名
  • 出站：回复通过主动 API 发送，而不是 callback 响应体返回

该实现与腾讯官方 WXBizMsgCrypt SDK 兼容。

限制​

  • 不支持 streaming：agent 完成后才会一次性回复
  • 不支持 typing indicator：callback 模式没有 typing 状态
  • 当前仅支持文本输入：图片、文件、语音输入尚未实现；但 agent 已知晓 WeCom 平台支持图片、文档、视频和语音的出站能力
  • 响应延迟较高：用户通常会在 3–30 分钟后才看到结果