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 / 客服消息