1. 文档背景本文基于企业微信 iPad 协议接口完整实现「企微消息回调接收 → 消息预处理 → 第三方 AI 智能体语义推理 → 企微多类型消息自动下发」全链路技术流程。协议底层为ipad协议的方式API支持账号初始化、扫码登录、消息回调、全类型消息收发、文件 CDN 上传下载、群 / 联系人管理能力AI 智能体采用 RAG 检索增强大模型承载产品咨询、售后答疑、活动解答、多轮对话、工单触发等业务能力。2. 适用场景零售连锁企业员工使用企微接待外部客户 / 客户群需求客户私聊 / 群内提问自动 AI 回复支持文本、图片、文件、语音消息解析区分内部员工、外部客户过滤闲聊消息仅业务问题触发 AIAI 可调用企业知识库、订单接口支持引用原消息回复、发送图文 / 链接 / 小程序离线消息同步、会话留痕、人工接管机制多账号 iPad 实例并行隔离会话互不干扰。3. 核心依赖接口模块核心 API用途账号初始化/wxwork/init创建账号 uuid绑定设备登录前置消息回调配置/wxwork/SetCallbackUrl配置 HTTP/RabbitMQ 消息回调地址接收实时消息消息接收回调接口接收私聊 / 群聊文本、图片、文件、语音、名片等全类型消息消息同步/wxwork/SyncAllData登录后同步离线历史消息消息发送SendTextMsg/SendTextAtMsg/SendCDNImgMsg等AI 生成内容后回复客户支持 、图片、文件、引用消息文件 CDN 上传 / 下载CdnUploadXXX/DownloadFile客户上传图片 / 语音转 AI 解析AI 下发素材会话联系人GetExternalContacts/GetRoomUserList获取客户 / 群基础信息AI 区分用户身份已读标记MarkAsReadAI 回复后清除会话小红点一、整体系统架构1. 分层架构图flowchart LRA[企微iPad协议服务 ] -- B[消息回调网关]subgraph 消息层B1[HTTP回调服务]B2[RabbitMQ交换机message.exchange.ultraMsg]B -- B1 B2endB2 -- C[消息消费微服务]C -- 1.消息解析模块C -- 2.消息过滤引擎C -- 3.文件解析子服务(CDN下载转本地)C -- D[AI智能体对接层]subgraph AI智能体集群D1[消息意图识别]D2[RAG知识库检索]D3[业务工具调用(订单/库存)]D4[回复内容生成敏感过滤]endD -- D1 D2 D3 D4D -- E[企微消息发送调度服务]E -- F[企微iPad协议API集群]F -- AC D E -- G[会话存储MySQLRedis]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{vid: ,ip: ,port: ,proxySituation: 0,deverType: ipad}返回uuid427d7ee5-3a1c-418-a83b-532ba1e7a1e该 uuid 作为当前账号唯一操作标识全接口复用。步骤 2配置 RabbitMQ 消息回调生产推荐调用/wxwork/SetCallbackUrl绑定 MQ 交换机与路由所有消息自动投递至消息队列避免 HTTP 同步阻塞 AI 推理耗时。json{uuid:427d7ee5-3a1c-418-a83b-532ba1e7a1e,callbackType:RABBITMQ,mqExchange:message.exchange.ultraMsg,mqRoutingKey:wx_ai_customer,extraContent:retail_shop_01}返回errcode0回调配置生效账号所有收发消息实时推送 MQ。步骤 3登录账号自动登录流程首次登录调用getQrCode获取二维码客户扫码验证码调用CheckCode完成登录后续登录init接口传入上次登录vid调用automaticLogin自动免登登录完成调用SyncAllData同步离线历史消息补全会话上下文。阶段 1客户发送消息企微推送回调模拟客户外部联系人 user_id7881302555913738向 iPad 企微员工发送消息客户消息你们家夏季连衣裙有哪些尺码160 身高穿会不会太长有没有现货发一下实拍图MQ 收到回调标准报文简化json{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_room0判定为私聊调用GetUserInfoByVids传入sender确认是外部客户符合 AI 自动回复触发条件内部员工消息直接过滤过滤规则校验配置规则纯表情包 / 单字闲聊不触发当前为业务咨询类问句放行进入 AI上下文拼接Redis 读取该客户近 3 轮对话拼接完整会话历史一并传入 AI 智能体。阶段 3第三方 AI 智能体处理流程AI 智能体入参标准化结构json{sessionId:427d7ee5_7881302555913738,userType:external_customer,userId:7881302555913738,currentQuestion:你们家夏季连衣裙有哪些尺码160身高穿会不会太长有没有现货发一下实拍图,historyChat:[上一轮客户问连衣裙价格AI回复399元],attachments:[],customerTag:[女装客户、夏季新品意向]}AI 内部执行链路意图识别判定为「夏季连衣裙产品咨询」RAG 知识库检索匹配连衣裙尺码、衣长、库存、实拍素材信息工具调用调用库存接口确认全尺码现货回复生成输出文本回答 连衣裙实拍图 CDN 链接安全过滤校验无敏感词、价格合规输出结构化返回json{replyType:text_img,textContent:咱们夏季连衣裙有S/M/L三个尺码160身高穿S码刚好到小腿位置不会拖沓目前全尺码现货~实拍图给您看下,imgUrlList:[https://xxx.xxx/lianqun.jpg],quoteMsgId:0,//非引用消息atUserIds:[]}阶段 4AI 回复适配企微 iPad 协议自动下发消息图片 CDN 上传AI 返回图片网络地址调用CdnUploadImgLink执行 CDN 上传获取cdnkey、aeskey、md5等下发必填参数发送文本消息 发送 CDN 图片先调用SendTextMsg发送文字内容json{uuid:427d7ee5-3a1c-418-a83b-532ba1e7a1e,send_userid:7881302555913738,isRoom:false,content:咱们夏季连衣裙有S/M三个尺码160身高穿S码刚好到小腿位置不会拖沓目前全尺码现货~实拍图给您看下}再调用SendCDNImgMsg上传返回的图片 CDN 参数标记消息已读调用MarkAsRead接口清除客户会话小红点会话持久化将客户提问、AI 回复、发送日志写入 MySQL更新 Redis 会话上下文。场景 1客户发送图片提问客户上传连衣裙实物图询问是否有同款回调收到msgtype14图片消息携带fileid、aes_key预处理调用DownloadFileCDN 下载图片本地AI 智能体接入图像识别能力检索同款产品AI 返回文字 商品小程序卡片调用SendAppMsg发送小程序消息。场景 2群内 AI 咨询群聊自动回复客户在外部客户群 iPad 企微账号提问回调is_roomtruecontent 包含 标记预处理识别atids包含当前员工 user_id触发 AIAI 生成回复调用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 会话缓存按uuiduserid隔离不同门店客户会话不串话。5. 离线消息补全iPad 账号重新登录后自动调用SyncAllData接口同步离线消息逐条送入 AI 消费保证离线客户消息也能自动回复。四、核心接口代码示例Java 回调服务企微 MQ 回调接收入口取自文档回调规范javaPostMapping(/wxwork/callback)ResponseBodypublic MapString,Object callback(RequestBody JSONObject json){// 1. 获取回调参数String uuid json.getString(uuid);String msgJson json.getString(json);Integer type json.getInteger(type);// 2. 直接返回成功异步投递MQrabbitTemplate.convertAndSend(message.exchange.ultraMsg,wx_ai_customer,json.toString());// 3. 标准返回格式匹配文档示例MapString,String mapnew 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 大模型智能体承载业务问答能力同时配套离线同步、异常熔断、多账号隔离、会话留痕等生产级能力可直接落地零售、教育、服务业企微客服自动化场景。整体链路严格遵循协议接口入参、返回格式规范文件上传下载、消息收发、账号管理均复用文档原生能力无额外私有协议改造兼容性强。