跳到主要內容

企業微信回調（自建應用）

使用回調/Webhook 模式，將 Hermes 作為自建企業應用連接到企業微信（WeCom）。

企業微信機器人 vs 企業微信回調

Hermes 支持兩種企業微信集成模式：

  • 企業微信機器人 — 機器人風格，通過 WebSocket 連接。設置更簡單，適用於群聊。
  • 企業微信回調（本頁）— 自建應用，接收加密的 XML 回調。在用戶的企業微信側邊欄中顯示為一級應用。支持多主體路由。

工作原理​

  1. 你在企業微信管理後臺註冊一個自建應用
  2. 企業微信將加密的 XML 推送到你的 HTTP 回調端點
  3. Hermes 解密消息，並將其排隊等待代理處理
  4. 立即確認（靜默 — 不向用戶顯示任何內容）
  5. 代理處理請求（通常需要 3–30 分鐘）
  6. 回覆通過企業微信 message/send API 主動發送

前提條件​

  • 具有管理員權限的企業微信企業賬號
  • aiohttp 和 httpx Python 包（包含在默認安裝中）
  • 一個公網可訪問的服務器用於回調 URL（或使用 ngrok 等隧道工具）

設置​

1. 在企業微信中創建自建應用​

  1. 前往 企業微信管理後臺 → 應用管理 → 創建應用
  2. 記錄你的 企業 ID（顯示在管理後臺頂部）
  3. 在應用設置中，創建 應用 Secret
  4. 從應用概覽頁面記錄 AgentId
  5. 在 接收消息 下，配置回調 URL：
    • 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 請求驗證回調 URL，然後開始通過 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 密鑰（必填）
host0.0.0.0HTTP 回調服務器的綁定地址
port8645HTTP 回調服務器的端口
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/callbackURL 驗證握手（企業微信在設置期間發送此請求）
POST/wecom/callback加密消息回調（企業微信在此處發送用戶消息）
GET/health健康檢查 — 返回 {"status": "ok"}

加密​

所有回調負載均使用 EncodingAESKey 通過 AES-CBC 進行加密。適配器處理：

  • 入站：解密 XML 負載，驗證 SHA1 簽名
  • 出站：回覆通過主動 API 發送（非加密的回調響應）

該加密實現與騰訊官方的 WXBizMsgCrypt SDK 兼容。

限制​

  • 不支持流式傳輸 — 回覆在代理處理完成後作為完整消息到達
  • 無輸入指示器 — 回調模型不支持輸入狀態顯示
  • 僅文本 — 目前僅支持文本消息輸入；圖片/文件/語音輸入尚未實現。代理通過企業微信平臺提示知曉出站媒體能力（圖片、文檔、視頻、語音）。
  • 響應延遲 — 代理會話需要 3–30 分鐘；用戶在處理完成後看到回覆