Skip to main content

​
微信公众号对接指南

​
概述

本模块实现了微信公众号的消息回调对接。当用户在公众号中发送消息时，微信服务器会将消息 POST 到配置的回调地址，我们处理消息并直接返回回复内容。

​
架构设计

用户发送消息 → 微信服务器 → 回调我们的接口 → 调用AI服务 → 返回XML回复 → 微信服务器 → 用户收到回复

​
核心组件

  • WeChatMpRobotEndpoint - 处理微信公众号回调的 REST 接口
  • RobotChatService - 统一的机器人聊天服务
  • WeChatMpChannelConfig - 渠道配置（appId, appSecret, token, encodingAesKey）
  • weixin-java-mp - 微信公众号 Java SDK

​
回调地址格式

GET/POST /robot/wechat-mp/callback/{apiKey}

​
消息处理流程

​
1. URL 验证（GET 请求）

微信服务器在配置服务器地址时会发送 GET 请求验证： 请求参数：
参数说明
signature微信加密签名
timestamp时间戳
nonce随机数
echostr随机字符串
验证逻辑：
  1. 将 token、timestamp、nonce 三个参数进行字典序排序
  2. 拼接后进行 SHA1 加密
  3. 与 signature 对比，一致则验证通过
  4. 原样返回 echostr

​
2. 接收消息（POST 请求）

明文模式请求体： 
<xml>
  <ToUserName><![CDATA[公众号原始ID]]></ToUserName>
  <FromUserName><![CDATA[用户OpenID]]></FromUserName>
  <CreateTime>1234567890</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[用户消息]]></Content>
  <MsgId>1234567890123456</MsgId>
</xml>
安全模式请求体： 
<xml>
  <ToUserName><![CDATA[公众号原始ID]]></ToUserName>
  <Encrypt><![CDATA[加密内容]]></Encrypt>
</xml>

​
3. 响应格式

明文模式响应： 
<xml>
  <ToUserName><![CDATA[用户OpenID]]></ToUserName>
  <FromUserName><![CDATA[公众号原始ID]]></FromUserName>
  <CreateTime>1234567890</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[AI回复内容]]></Content>
</xml>
安全模式响应： 
<xml>
  <Encrypt><![CDATA[加密内容]]></Encrypt>
  <MsgSignature><![CDATA[签名]]></MsgSignature>
  <TimeStamp>时间戳</TimeStamp>
  <Nonce><![CDATA[随机数]]></Nonce>
</xml>

​
与企业微信的差异

特性微信公众号企业微信
验证签名参数signaturemsg_signature
验证签名算法SHA1(token, timestamp, nonce)SHA1(token, timestamp, nonce, echostr)
验证返回值直接返回 echostr解密后返回
消息加密可选（三种模式）必须加密
加密标识URL 参数 encrypt_type=aes无（始终加密）
用户标识OpenIDUserId

​
消息加密模式

微信公众号支持三种消息加密模式：
模式说明请求体响应体
明文模式不加密明文 XML明文 XML
兼容模式同时包含明文和密文明文 + 密文明文 XML
安全模式仅密文密文 XML密文 XML
推荐使用安全模式，本模块自动根据 encrypt_type 参数判断并处理。

​
配置说明

在 LangChat 管理后台创建 API 密钥时，选择”微信公众号”渠道，配置以下信息：
配置项必填说明获取位置
appId是公众号AppID公众号后台 → 基本配置
appSecret是公众号AppSecret公众号后台 → 基本配置
token是消息校验Token自定义，需与公众号后台一致
encodingAesKey否*消息加解密密钥公众号后台自动生成
*注：如果使用安全模式或兼容模式，encodingAesKey 必填。

​
微信公众号后台配置

​
步骤一：进入服务器配置

  1. 登录 微信公众平台
  2. 进入「设置与开发」→「基本配置」
  3. 找到「服务器配置」区域

​
步骤二：配置服务器地址

配置项填写内容
URLhttps://你的域名/robot/wechat-mp/callback/{apiKey}
Token自定义字符串（需与 LangChat 配置一致）
EncodingAESKey点击「随机生成」或自定义
消息加解密方式推荐选择「安全模式」

​
步骤三：提交验证

  1. 确保 LangChat 服务已部署并可访问
  2. 确保已在 LangChat 中创建对应的 API 密钥
  3. 点击「提交」按钮
  4. 验证成功后点击「启用」

​
注意事项

​
5秒超时限制

微信服务器要求在 5 秒内返回响应，否则会：
  1. 进行最多 3 次重试
  2. 用户看到「该公众号暂时无法提供服务」提示
解决方案：
  • 如果 AI 响应较慢，可考虑使用客服消息接口异步回复
  • 优化模型响应速度
  • 设置合理的超时时间

​
消息去重

微信可能会重复推送同一条消息（超时重试），建议：
  • 根据 MsgId 进行去重处理
  • 缓存已处理的消息 ID

​
公众号类型限制

公众号类型被动回复客服消息模板消息
订阅号（个人）✅❌❌
订阅号（企业）✅❌✅
服务号✅✅✅

​
HTTPS 要求

  • 微信公众号要求回调地址必须是 HTTPS
  • 证书必须是受信任的 CA 签发
  • 不支持自签名证书

​
支持的消息类型

当前支持的消息类型：
  • text - 文本消息
后续可扩展：
  • image - 图片消息
  • voice - 语音消息
  • video - 视频消息
  • location - 地理位置消息
  • link - 链接消息
  • event - 事件推送（关注、取消关注、菜单点击等）

​
相关文档