使用企业微信 API 配置消息回调对接智能体实现 AI 客服

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    A[企微iPad协议服务 ] --> B[消息回调网关]    subgraph 消息层        B1[HTTP回调服务]        B2[RabbitMQ交换机message.exchange.ultraMsg]        B --> B1 & B2    end    B2 --> C[消息消费微服务]    C --> 1.消息解析模块    C --> 2.消息过滤引擎    C --> 3.文件解析子服务(CDN下载转本地)    C --> D[AI智能体对接层]    subgraph AI智能体集群        D1[消息意图识别]        D2[RAG知识库检索]        D3[业务工具调用(订单/库存)]        D4[回复内容生成+敏感过滤]    end    D --> D1 & D2 & D3 & D4    D --> E[企微消息发送调度服务]    E --> F[企微iPad协议API集群]    F --> A    C & D & E --> G[会话存储MySQL+Redis]

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，生成新设备）

{    "vid": "",    "ip": "",    "port": "",    "proxySituation": 0,    "deverType": "ipad"}

返回uuid=427d7ee5-3a1c-418-a83b-532ba1e7a1e，该 uuid 作为当前账号唯一操作标识，全接口复用。

步骤 2：配置 RabbitMQ 消息回调（生产推荐）

调用/wxwork/SetCallbackUrl，绑定 MQ 交换机与路由，所有消息自动投递至消息队列，避免 HTTP 同步阻塞 AI 推理耗时。

{    "uuid":"427d7ee5-3a1c-418-a83b-532ba1e7a1e",    "callbackType":"RABBITMQ",    "mqExchange":"message.exchange.ultraMsg",    "mqRoutingKey":"wx_ai_customer",    "extraContent":"retail_shop_01"}
返回errcode=0，回调配置生效，账号所有收发消息实时推送 MQ。

步骤 3：登录账号（自动登录流程）

首次登录：调用getQrCode获取二维码，客户扫码，验证码调用CheckCode完成登录；

后续登录：init接口传入上次登录vid，调用automaticLogin自动免登；

登录完成调用SyncAllData同步离线历史消息，补全会话上下文。

阶段 1：客户发送消息，企微推送回调

模拟客户（外部联系人 user_id=7881302555913738）向 iPad 企微员工发送消息：

客户消息：你们家夏季连衣裙有哪些尺码？160 身高穿会不会太长？有没有现货，发一下实拍图

MQ 收到回调标准报文（简化）：

{    "uuid":"427d7ee5-3a1c-418-a83b-532ba1e7a1e",    "json":{        "send_time":1766701230,        "sender":7881302555913738,        "sender_name":"客户-小李",        "send_userid":7881302555913738,        "is_room":0,        "msg_id":124567,        "server_id":135621,        "msgtype":2,        "content":"你们家夏季连衣裙有哪些尺码？160身高穿会不会太长？有没有现货，发一下实拍图",        "app_info":"from_msgid_xxxx"    },    "type":102001}

阶段 2：消息消费预处理逻辑

基础解析通过is_room=0判定为私聊；调用GetUserInfoByVids传入sender，确认是外部客户，符合 AI 自动回复触发条件（内部员工消息直接过滤）；

过滤规则校验配置规则：纯表情包 / 单字闲聊不触发；当前为业务咨询类问句，放行进入 AI；

上下文拼接Redis 读取该客户近 3 轮对话，拼接完整会话历史，一并传入 AI 智能体。

阶段 3：第三方 AI 智能体处理流程

AI 智能体入参标准化结构

{    "sessionId":"427d7ee5_7881302555913738",    "userType":"external_customer",    "userId":7881302555913738,    "currentQuestion":"你们家夏季连衣裙有哪些尺码？160身高穿会不会太长？有没有现货，发一下实拍图",    "historyChat":["上一轮：客户问连衣裙价格，AI回复399元"],    "attachments":[],    "customerTag":["女装客户、夏季新品意向"]}

AI 内部执行链路：

意图识别：判定为「夏季连衣裙产品咨询」；

RAG 知识库检索：匹配连衣裙尺码、衣长、库存、实拍素材信息；

工具调用：调用库存接口，确认全尺码现货；

回复生成：输出文本回答 + 连衣裙实拍图 CDN 链接；

安全过滤：校验无敏感词、价格合规，输出结构化返回：

{    "replyType":"text_img",    "textContent":"咱们夏季连衣裙有S/M/L三个尺码，160身高穿S码刚好到小腿位置不会拖沓，目前全尺码现货~实拍图给您看下：",    "imgUrlList":["https://xxx.xxx/lianqun.jpg"],    "quoteMsgId":0,//非引用消息    "atUserIds":[]}

阶段 4：AI 回复适配企微 iPad 协议，自动下发消息

图片 CDN 上传AI 返回图片网络地址，调用CdnUploadImgLink执行 CDN 上传，获取cdnkey、aeskey、md5等下发必填参数；

发送文本消息 + 发送 CDN 图片先调用SendTextMsg发送文字内容：

{    "uuid":"427d7ee5-3a1c-418-a83b-532ba1e7a1e",    "send_userid":7881302555913738,    "isRoom":false,    "content":"咱们夏季连衣裙有S/M三个尺码，160身高穿S码刚好到小腿位置不会拖沓，目前全尺码现货~实拍图给您看下："}

再调用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 回调接收入口（取自文档回调规范）

@PostMapping("/wxwork/callback")
@ResponseBody
public Map<String,Object> callback(
@RequestBody JSONObject json){
    // 1. 获取回调参数    String uuid = json.getString("uuid");
    String msgJson = json.getString("json");
    Integer type = json.getInteger("type");
    // 2. 直接返回成功，异步投递MQ    rabbitTemplate.convertAndSend("message.exchange.ultraMsg","wx_ai_customer",json.toString());
    // 3. 标准返回格式，匹配文档示例    Map<String,String> map=new HashMap<>();
    map.put("errcode","0");
    map.put("errmsg","ok");
    
return map;
}
AI 智能体返回后，调用企微发送文本接口工具类
java/** * 调用企微iPad协议发送文本消息 */
public Result sendWxText(String uuid, Long sendUserId, String content){
    String url = "http://127.0.0.1/wxwork/SendTextMsg";
    JSONObject req = new JSONObject();
    req.put("uuid",uuid);
    req.put("send_userid",sendUserId);
    req.put("isRoom",false);
    req.put("content",content);
    // HTTP POST请求    String resp = httpClient.postJson(url,req.toString());
    
return JSON.parseObject(resp,Result.class);
}

五、场景落地约束与规范

消息触发规则仅外部客户（个微好友 / 外部企微客户）、@账号、业务问句触发 AI；内部员工、纯表情包、无意义短句直接跳过自动回复。

消息发送限流遵循企微 iPad 协议限制，单账号每分钟消息不超过 20 条，高频提问增加延迟缓冲。

内容合规约束AI 输出必须过敏感词过滤，禁止价格夸大、违规营销话术；企微发送接口返回errcode!=0时记录告警，人工介入。

会话生命周期Redis 上下文缓存 30 分钟无对话自动清空；MySQL 永久存储所有消息与 AI 问答日志，用于业务复盘。

账号运维通过GetRunClient、GetRunClientByUuid定时巡检 iPad 登录状态，掉线自动执行automaticLogin重登，保证自动回复持续可用。

六、总结

本套方案完全基于文档内企微 iPad 设备协议 API 实现，依托消息队列异步化解耦回调与 AI 推理，覆盖私聊 / 群聊、文本 / 图片 / 语音 / 引用消息全场景自动回复；通过第三方 RAG 大模型智能体承载业务问答能力，同时配套离线同步、异常熔断、多账号隔离、会话留痕等生产级能力，可直接落地零售、教育、服务业企微客服自动化场景。整体链路严格遵循协议接口入参、返回格式规范，文件上传下载、消息收发、账号管理均复用文档原生能力，无额外私有协议改造，兼容性强。