Skip to main content

​
企业微信智能机器人对接指南

​
概述

本模块实现了企业微信智能机器人（AI Bot）的消息回调处理。注意：智能机器人与普通企业微信应用机器人的协议完全不同。

​
架构设计

用户发送消息 → 企业微信服务器 → 回调我们的接口 → 解密消息 → 调用AI服务 → 加密响应 → 返回给企业微信

​
核心组件

  • WeChatRobotEndpoint - 处理企业微信回调的 REST 接口
  • RobotChatService - 统一的机器人聊天服务（支持 App 和 Workflow）
  • WeChatCpChannelConfig - 渠道配置（token, encodingAesKey）

​
回调地址格式

POST /robot/wechat/callback/{apiKey}
其中 apiKey 是在 LangChat 平台创建的 API 密钥，用于关联具体的 App 或 Workflow。

​
智能机器人 vs 普通应用机器人

特性普通应用机器人智能机器人 (AI Bot)
请求格式加密 XML加密 JSON
解密后格式XMLJSON（嵌套结构）
响应消息类型textstream
响应格式加密 XML加密 JSON

​
消息处理流程

​
1. 接收请求

智能机器人发送的请求体为 JSON 格式： 
{"encrypt": "加密的Base64字符串"}

​
2. 解密消息

使用 WxCpCryptUtil.decrypt() 解密后得到： 
{
  "msgid": "消息ID",
  "from": {"userid": "发送者ID"},
  "text": {"content": "@机器人名 用户消息"},
  "msgtype": "text",
  "chattype": "group",
  "response_url": "https://..."
}
注意事项：
  • 用户ID 在 from.userid（嵌套结构）
  • 消息内容在 text.content（嵌套结构）
  • 需要移除 @机器人名 前缀

​
3. 构建响应

智能机器人只能使用 stream 类型回复用户消息： 
{
  "msgtype": "stream",
  "stream": {
    "id": "唯一流ID",
    "finish": true,
    "content": "AI回复内容"
  }
}

​
4. 加密响应（关键）

响应必须加密并签名，格式如下： 
{
  "encrypt": "AES加密后的Base64字符串",
  "msgsignature": "SHA1签名",
  "timestamp": "秒级时间戳",
  "nonce": "回调URL中的nonce"
}
加密伪代码： 
1. plainText = 构建stream消息JSON
2. encryptedXml = WxCpCryptUtil.encrypt(plainText)
3. encrypted = 从XML中提取<Encrypt>标签内容
4. timestamp = 当前秒级时间戳
5. signature = SHA1(sort(token, timestamp, nonce, encrypted))
6. 返回 {encrypt, msgsignature, timestamp, nonce}

​
踩坑记录

​
1. SDK 返回 XML 而非纯 Base64

WxCpCryptUtil.encrypt() 返回完整 XML： 
<xml>
  <Encrypt><![CDATA[Base64内容]]></Encrypt>
  <MsgSignature>...</MsgSignature>
  ...
</xml>
需要从中提取 <Encrypt> 标签的内容。

​
2. 消息类型限制

  • text 类型：仅支持”进入会话”欢迎语场景
  • stream 类型：支持回复用户消息（必须使用此类型）

​
3. 签名算法

必须使用微信 SDK 提供的 SHA1.gen() 方法，确保排序和拼接逻辑一致。

​
4. Nonce 来源

响应中的 nonce 必须使用回调 URL 参数中的 nonce，不能自己生成。

​
配置说明

在 LangChat 管理后台创建 API 密钥时，选择”企业微信”渠道，配置以下信息：
配置项说明获取位置
token消息校验Token智能机器人配置 → 回调配置
encodingAesKey消息加密密钥智能机器人配置 → 回调配置

​
相关文档