WeChat OA（公眾號）

🟡 支持主動發送，支持接收消息，48 小時窗口限制

主動發送客服消息有約束：用戶須在過去 48 小時內與公眾號有過互動，否則平臺返回 errcode 45015，消息被丟棄。需要冷推送的生產環境應使用模板消息（需預先審核），該功能屬於後續增強計劃。

功能概覽

• 主動發送文本，通過 POST /cgi-bin/message/custom/send?access_token=... 向過去 48 小時內給公眾號發過消息的 openid 發送。
• 接收消息事件，路徑為 /webhooks/wechat-oa。SHA1 排序加密與 WeCom 相同（共用 wxcrypt 輔助模塊）。GET 握手有一處差異：WeChat OA 對 3 元組 [token, timestamp, nonce] 簽名，而非 4 元組。
• 每個應用的 access_token 緩存 2 小時。
• 當前僅支持文本消息。 圖片、圖文、模板消息暫未實現。
• 文本長度上限 2048 字符。

配置步驟

1. 創建或認領公眾號

1. 登錄微信公眾平臺（客服消息接口須使用服務號，訂閱號不可用）
2. "設置" → "基本設置"：記錄 AppID 和 AppSecret
3. "設置" → "服務器配置"：
   • URL：https://<your-host>/webhooks/wecom
   • Token：任意不透明字符串（即 WECHAT_OA_TOKEN）
   • EncodingAESKey：點擊"隨機生成"（43 位字符，即 WECHAT_OA_AES_KEY）
   • 消息加密方式：建議選"安全模式"（加密）
4. 點擊"提交"。微信會以 GET 握手請求該 URL；Minara 回顯解密後的明文。

2. 獲取默認 openid

客服消息接口需要 openid（不透明用戶標識符）。讓測試用戶觸發任意互動（關注公眾號、發送消息或點擊菜單項），inbound webhook 會在 FromUserName 中暴露 openid。將其保存為 WECHAT_OA_DEFAULT_OPENID。

3. 配置 Minara

minara auth messaging add
# 从列表中选择 `wechat_oa`。

或直接設置環境變量：

WECHAT_OA_APP_ID=wx<...>
WECHAT_OA_APP_SECRET=<opaque secret>
WECHAT_OA_TOKEN=<server config Token>
WECHAT_OA_AES_KEY=<43-char EncodingAESKey>
WECHAT_OA_DEFAULT_OPENID=<o...........>

4. 測試

minara auth messaging test wechat_oa

若默認 openid 在過去 48 小時內未與公眾號互動，測試會返回 errcode 45015 並失敗。

入站 Webhook

WeChat OA 的服務器配置 GET 握手與 WeCom 略有不同。4 元組 [token, ts, nonce, encrypt] 替換為 3 元組 [token, timestamp, nonce]：

expected = sha1(sort([token, timestamp, nonce]).join(""))

POST 簽名與 WeCom 相同：URL query 中攜帶 msg_signature，4 元組排序，body 內含 AES 信封。

解密後的內層 XML 載荷遵循騰訊的經典格式：

<xml>
  <ToUserName>...</ToUserName>
  <FromUserName>...</FromUserName>
  <CreateTime>...</CreateTime>
  <MsgType>text</MsgType>
  <Content>...</Content>
  <MsgId>...</MsgId>
</xml>

僅 MsgType=text 事件會轉發給 Agent。

限制與注意事項

• 48 小時客服消息窗口。 超出窗口期後，所有主動消息均返回 errcode 45015。請圍繞被動回覆（用戶發起互動後 48 小時內）設計交互體驗；長尾推送請使用經審核的模板消息。
• 服務號與訂閱號的區別。 客服消息接口僅對服務號開放，訂閱號無法使用此渠道。
• EncodingAESKey 必須恰好為 43 位字符。 長度不符會導致啟動時解碼失敗。

故障排查

"errcode 45015"

• 該 openid 在過去 48 小時內未與公眾號互動。此為平臺限制；冷推送請改用模板消息（Minara 暫未接入）。

"errcode 40001 / Token invalid"

• access_token 刷新失敗。請在公眾號後臺核對 WECHAT_OA_APP_ID 和 WECHAT_OA_APP_SECRET。

"Inbound webhook 握手返回 401"

• 3 元組 SHA1 校驗失敗。最常見原因是 WECHAT_OA_TOKEN 有拼寫錯誤。請確認該值與公眾號"服務器配置"頁面中的 Token 一致。

參考資料

• 環境變量：WECHAT_OA_*
• 主動發送：apps/agent/src/messaging/wechat_oa.ts
• Inbound 規格：apps/agent/src/messaging/inbound/specs/wechat_oa.ts
• 客服消息接口：developers.weixin.qq.com / 客服消息