Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/wecom-callback

WeCom Callback（自建應用）

透過 callback/webhook 模式，將 Hermes 連接為 WeCom（企業微信）的自建企業應用。

INFO — WeCom Bot 與 WeCom Callback 的差異

Hermes 支援兩種 WeCom 整合模式：

WeCom Bot — 機器人模式，透過 WebSocket 連線。設定較簡單，可用於群組聊天。

WeCom Callback（本頁）— 自建應用，接收加密的 XML callback。在使用者的 WeCom 側邊欄中顯示為獨立應用。支援多企業路由。

另請參閱：WeCom Bot，了解機器人模式的整合方式。

執行 hermes gateway setup 並選擇 WeCom Callback，即可透過引導式流程完成設定。

運作方式

你在 WeCom 管理後台註冊一個自建應用
WeCom 將加密的 XML 推送到你的 HTTP callback 端點
Hermes 解密訊息並將其加入 agent 的處理佇列
立即回覆確認（靜默處理 — 不會向使用者顯示任何內容）
Agent 處理請求（通常需要 3–30 分鐘）
回覆透過 WeCom message/send API 主動傳送

前置需求

具備管理員權限的 WeCom 企業帳號
aiohttp 和 httpx Python 套件（預設安裝已包含）
公網可達的 callback URL 伺服器（或使用 ngrok 等 tunnel 工具）

設定步驟

1. 在 WeCom 建立自建應用

前往 WeCom 管理後台 → 應用管理 → 建立應用
記下你的 企業 ID（Corp ID）（位於管理後台頁面頂部）
在應用設定中，建立 應用 Secret（Corp Secret）
從應用的概覽頁面記下 Agent ID
在接收訊息設定中，配置 callback URL：
- URL：http://YOUR_PUBLIC_IP:8645/wecom/callback
- Token：產生一組隨機 token（WeCom 會提供一組）
- 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. 啟動 Gateway

hermes gateway

（僅在 hermes gateway install 已註冊 systemd/launchd 服務之後，才使用 hermes gateway start。）

Callback adapter 會在設定的連接埠上啟動 HTTP 伺服器。WeCom 會先透過 GET 請求驗證 callback URL，接著開始透過 POST 傳送訊息。

設定參考

可在 config.yaml 的 platforms.wecom_callback.extra 中設定以下參數，或使用環境變數：

設定項目	預設值	說明
`corp_id`	—	WeCom 企業 Corp ID（必填）
`corp_secret`	—	自建應用的 Corp Secret（必填）
`agent_id`	—	自建應用的 Agent ID（必填）
`token`	—	Callback 驗證 token（必填）
`encoding_aes_key`	—	用於 callback 加密的 43 字元 AES 金鑰（必填）
`host`	`0.0.0.0`	HTTP callback 伺服器的綁定位址
`port`	`8645`	HTTP callback 伺服器的連接埠
`path`	`/wecom/callback`	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 來界定，避免跨企業衝突。當使用者傳送訊息時，adapter 會記錄其所屬的應用（企業），並將回覆透過正確應用的 access token 傳送。

存取控制

限制哪些使用者可以與應用互動：

# Allowlist specific users
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Or allow all users
WECOM_CALLBACK_ALLOW_ALL_USERS=true

API 端點

Adapter 提供以下端點：

方法	路徑	用途
GET	`/wecom/callback`	URL 驗證交握（WeCom 在設定時會發送此請求）
POST	`/wecom/callback`	加密訊息 callback（WeCom 將使用者訊息傳送到此處）
GET	`/health`	健康檢查 — 回傳 `{"status": "ok"}`

加密機制

所有 callback 負載均使用 AES-CBC 搭配 EncodingAESKey 進行加密。Adapter 處理以下流程：

接收端：解密 XML 負載，驗證 SHA1 簽章
傳送端：透過主動式 API 傳送回覆（而非加密的 callback 回應）

加密實作與騰訊官方 WXBizMsgCrypt SDK 相容。

限制事項

不支援串流 — 回覆在 agent 處理完成後才會以完整訊息的形式送達
無輸入指示器 — callback 模式不支援輸入狀態顯示
僅限文字 — 目前支援文字訊息作為輸入；圖片/檔案/語音輸入尚未實作。Agent 可透過 WeCom 平台的 hint 了解可用的出站媒體功能（圖片、文件、影片、語音）
回應延遲 — agent session 通常需要 3–30 分鐘；使用者在處理完成後才能看到回覆

疑難排解

簽章驗證失敗。 WeCom 使用你在管理後台註冊的 Token 對每個請求進行簽章。Hermes 中設定的 token 與管理後台預期的 token 不一致，是最常見的失敗原因。請重新複製管理後台中的 Token 和 EncodingAESKey — 它們很容易被截斷。~/.hermes/.env 中 = 前後的空白字元也會導致簽章檢查失敗。修正後，請重新啟動 hermes gateway run。

Callback URL 無法連線 / 驗證步驟失敗。 WeCom 會存取你註冊的公網 URL。請確認：

你的反向代理 / tunnel 已將 /wecom/callback 轉發至 gateway 的連接埠。
管理後台中的 URL 使用 HTTPS（WeCom 不接受純 HTTP）。
從你的網路外部執行 curl -i https://<your-domain>/wecom/callback，應會收到非逾時的回應（即使回傳 4xx 且不含查詢參數也沒問題 — 這表示 listener 是可達的）。

連接埠無法連線 / listener 未綁定。 請查看 hermes gateway run 日誌，確認綁定的 host/port。若 adapter 綁定在 127.0.0.1，你必須使用反向代理或 tunnel 轉發 — WeCom 的伺服器無法連線到 loopback 位址。請在 config.yaml 中設定 extra.host: 0.0.0.0（若直接對外暴露，還需設定 allowed_source_cidrs），或保持 loopback 並使用 Cloudflare Tunnel / nginx 等 tunnel 工具。