1. 文档背景
本文基于企业微信 iPad 协议接口,完整实现「企微消息回调接收 → 消息预处理 → 第三方 AI 智能体语义推理 → 企微多类型消息自动下发」全链路技术流程。
协议底层为https://wechatapi.apifox.cn/企微 iPad 客户端 API,支持账号初始化、扫码登录、消息回调、全类型消息收发、文件 CDN 上传下载、群 / 联系人管理能力;AI 智能体采用 RAG 检索增强大模型,承载产品咨询、售后答疑、活动解答、多轮对话、工单触发等业务能力。
2. 适用场景
零售连锁企业,员工使用企微接待外部客户 / 客户群,需求:
- 客户私聊 / 群内提问自动 AI 回复,支持文本、图片、文件、语音消息解析;
- 区分内部员工、外部客户,过滤闲聊消息,仅业务问题触发 AI;
- AI 可调用企业知识库、订单接口,支持引用原消息回复、发送图文 / 链接 / 小程序;
- 离线消息同步、会话留痕、人工接管机制;
- 多账号 iPad 实例并行,隔离会话互不干扰。
3. 核心依赖接口
| 模块 | 核心 API | 用途 |
| 账号初始化 | /wxwork/init | 创建账号 uuid,绑定设备,登录前置 |
| 消息回调配置 | /wxwork/SetCallbackUrl | 配置 HTTP/RabbitMQ 消息回调地址,接收实时消息 |
| 消息接收 | 回调接口 | 接收私聊 / 群聊文本、图片、文件、语音、名片等全类型消息 |
| 消息同步 | /wxwork/SyncAllData | 登录后同步离线历史消息 |
| 消息发送 | SendTextMsg/SendTextAtMsg/SendCDNImgMsg等 | AI 生成内容后回复客户,支持 @、图片、文件、引用消息 |
| 文件 CDN 上传 / 下载 | CdnUploadXXX/DownloadFile | 客户上传图片 / 语音转 AI 解析,AI 下发素材 |
| 会话联系人 | GetExternalContacts/GetRoomUserList | 获取客户 / 群基础信息,AI 区分用户身份 |
| 已读标记 | MarkAsRead | AI 回复后清除会话小红点 |

一、整体系统架构
1. 分层架构图
| flowchart LR |
2. 分层职责说明
- 企微 iPad 协议层
多台 iPad 企微账号实例,通过init初始化获取唯一uuid,绑定回调地址;所有收发消息、文件上传下载、群操作均通过该服务提供 POST 接口。每个账号独立uuid隔离会话。
- 消息回调层
支持 HTTP 直推、RabbitMQ 两种回调模式,生产环境优先 MQ 异步解耦,避免企微 5 秒超时。回调标准入参:uuid(账号实例ID)、json(完整消息体)、type(消息类型)。
- 消息消费预处理层
解析回调 json,区分私聊 / 群聊、内部 / 外部联系人;图片 / 语音 / 文件自动调用 CDN 下载接口获取本地资源,转文本(语音调用SpeechToText转文字);过滤无意义闲聊、表情包、内部沟通消息。
- 第三方 AI 智能体层
接收标准化客户提问、用户身份、会话上下文、附件内容,执行意图分类、知识库检索、业务接口调用,输出合规回复内容(支持文本、图片链接、小程序、引用格式)。
- 消息发送调度层
将 AI 返回内容适配企微 iPad 协议对应发送接口,文本走SendTextMsg、图片先 CDN 上传再调用SendCDNImgMsg、引用消息调用sendQuoteMsg;发送完成标记会话已读。
- 数据持久层
Redis 存储多轮会话上下文(30 分钟过期);MySQL 存储完整消息记录、AI 问答日志、客户标签、工单信息。
二、完整业务开发流程
前置准备:企微账号初始化 + 配置回调
步骤 1:企微实例账号初始化
调用接口:POST /wxwork/init
请求示例(首次登录无 vid,生成新设备)
| json |
返回uuid=427d7ee5-3a1c-418-a83b-532ba1e7a1e,该 uuid 作为当前账号唯一操作标识,全接口复用。
步骤 2:配置 RabbitMQ 消息回调(生产推荐)
调用/wxwork/SetCallbackUrl,绑定 MQ 交换机与路由,所有消息自动投递至消息队列,避免 HTTP 同步阻塞 AI 推理耗时。
| json |
返回errcode=0,回调配置生效,账号所有收发消息实时推送 MQ。
步骤 3:登录账号(自动登录流程)
- 首次登录:调用getQrCode获取二维码,客户扫码,验证码调用CheckCode完成登录;
- 后续登录:init接口传入上次登录vid,调用automaticLogin自动免登;
- 登录完成调用SyncAllData同步离线历史消息,补全会话上下文。
阶段 1:客户发送消息,企微推送回调
模拟客户(外部联系人 user_id=7881302555913738)向 iPad 企微员工发送消息:
| 客户消息:你们家夏季连衣裙有哪些尺码?160 身高穿会不会太长?有没有现货,发一下实拍图 |
MQ 收到回调标准报文(简化):
| json |
阶段 2:消息消费预处理逻辑
- 基础解析
通过is_room=0判定为私聊;调用GetUserInfoByVids传入sender,确认是外部客户,符合 AI 自动回复触发条件(内部员工消息直接过滤);
- 过滤规则校验
配置规则:纯表情包 / 单字闲聊不触发;当前为业务咨询类问句,放行进入 AI;
- 上下文拼接
Redis 读取该客户近 3 轮对话,拼接完整会话历史,一并传入 AI 智能体。
阶段 3:第三方 AI 智能体处理流程
AI 智能体入参标准化结构
| json |
AI 内部执行链路:
- 意图识别:判定为「夏季连衣裙产品咨询」;
- RAG 知识库检索:匹配连衣裙尺码、衣长、库存、实拍素材信息;
- 工具调用:调用库存接口,确认全尺码现货;
- 回复生成:输出文本回答 + 连衣裙实拍图 CDN 链接;
- 安全过滤:校验无敏感词、价格合规,输出结构化返回:
| json |
阶段 4:AI 回复适配企微 iPad 协议,自动下发消息
- 图片 CDN 上传
AI 返回图片网络地址,调用CdnUploadImgLink执行 CDN 上传,获取cdnkey、aeskey、md5等下发必填参数;
- 发送文本消息 + 发送 CDN 图片
先调用SendTextMsg发送文字内容:
| json |
再调用SendCDNImgMsg上传返回的图片 CDN 参数;
- 标记消息已读
调用MarkAsRead接口,清除客户会话小红点;
- 会话持久化
将客户提问、AI 回复、发送日志写入 MySQL,更新 Redis 会话上下文。
场景 1:客户发送图片提问
客户上传连衣裙实物图,询问是否有同款:
- 回调收到msgtype=14图片消息,携带fileid、aes_key;
- 预处理调用DownloadFileCDN 下载图片本地;
- AI 智能体接入图像识别能力,检索同款产品;
- AI 返回文字 + 商品小程序卡片,调用SendAppMsg发送小程序消息。
场景 2:群内 @AI 咨询(群聊自动回复)
客户在外部客户群 @iPad 企微账号提问:
- 回调is_room=true,content 包含 @标记;
- 预处理识别atids包含当前员工 user_id,触发 AI;
- AI 生成回复,调用SendTextAtMsgTwo格式化 @回复,群内自动 @提问客户。
场景 3:语音消息自动解析回复
客户发送 30 秒语音消息:
- 回调接收语音 CDN 参数;
- 调用DownloadFile下载语音文件;
- 调用协议SpeechToTextEntity接口,语音转文字;
- 转文字内容送入 AI 生成回复,文本下发客户。
场景 4:客户引用消息追问
客户引用 AI 之前的连衣裙消息提问:能不能退换?
- 回调携带quoteMsg完整引用消息结构体;
- 预处理提取引用消息内容,传入 AI 上下文;
- AI 生成退换政策回复,调用sendQuoteMsg接口,实现引用式回复。
三、关键异常处理机制
1. 企微回调超时保障
原协议回调 HTTP 接口仅 5 秒响应窗口,AI 推理耗时 2-5 秒,禁止同步调用 AI,统一使用 RabbitMQ 异步消费,回调接口直接返回{"errcode":0},避免企微重复推送消息造成重复回复。
2. 文件解析失败兜底
图片 / 语音 CDN 下载失败、语音转文字报错时,AI 自动回复「未能识别您发送的文件,请重新发送文字描述哦」。
3. AI 智能体服务熔断
AI 接口超时 / 报错时,预设兜底话术:「当前客服助手繁忙,请稍后提问,或直接联系人工客服」,可配置人工企微 id 同步下发。
4. 多账号 uuid 隔离
多台 iPad 企微账号独立 uuid,消息队列按extraContent区分门店,AI 会话缓存按uuid+userid隔离,不同门店客户会话不串话。
5. 离线消息补全
iPad 账号重新登录后,自动调用SyncAllData接口同步离线消息,逐条送入 AI 消费,保证离线客户消息也能自动回复。
四、核心接口代码示例(Java 回调服务)
企微 MQ 回调接收入口(取自文档回调规范)
| java |
AI 智能体返回后,调用企微发送文本接口工具类
| java |
五、场景落地约束与规范
- 消息触发规则
仅外部客户(个微好友 / 外部企微客户)、@账号、业务问句触发 AI;内部员工、纯表情包、无意义短句直接跳过自动回复。
- 消息发送限流
遵循企微 iPad 协议限制,单账号每分钟消息不超过 20 条,高频提问增加延迟缓冲。
- 内容合规约束
AI 输出必须过敏感词过滤,禁止价格夸大、违规营销话术;企微发送接口返回errcode!=0时记录告警,人工介入。
- 会话生命周期
Redis 上下文缓存 30 分钟无对话自动清空;MySQL 永久存储所有消息与 AI 问答日志,用于业务复盘。
- 账号运维
通过GetRunClient、GetRunClientByUuid定时巡检 iPad 登录状态,掉线自动执行automaticLogin重登,保证自动回复持续可用。
六、总结
本套方案完全基于文档内企微 iPad 设备协议 API 实现,依托消息队列异步化解耦回调与 AI 推理,覆盖私聊 / 群聊、文本 / 图片 / 语音 / 引用消息全场景自动回复;通过第三方 RAG 大模型智能体承载业务问答能力,同时配套离线同步、异常熔断、多账号隔离、会话留痕等生产级能力,可直接落地零售、教育、服务业企微客服自动化场景。
整体链路严格遵循协议接口入参、返回格式规范,文件上传下载、消息收发、账号管理均复用文档原生能力,无额外私有协议改造,兼容性强。
963

被折叠的 条评论
为什么被折叠?



