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

1. 文档背景

        本文基于企业微信 iPad 协议接口,完整实现「企微消息回调接收 → 消息预处理 → 第三方 AI 智能体语义推理 → 企微多类型消息自动下发」全链路技术流程。
协议底层为https://wechatapi.apifox.cn/企微 iPad 客户端 API,支持账号初始化、扫码登录、消息回调、全类型消息收发、文件 CDN 上传下载、群 / 联系人管理能力;AI 智能体采用 RAG 检索增强大模型,承载产品咨询、售后答疑、活动解答、多轮对话、工单触发等业务能力。

2. 适用场景

零售连锁企业,员工使用企微接待外部客户 / 客户群,需求:

  1. 客户私聊 / 群内提问自动 AI 回复,支持文本、图片、文件、语音消息解析;
  2. 区分内部员工、外部客户,过滤闲聊消息,仅业务问题触发 AI;
  3. AI 可调用企业知识库、订单接口,支持引用原消息回复、发送图文 / 链接 / 小程序;
  4. 离线消息同步、会话留痕、人工接管机制;
  5. 多账号 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. 分层职责说明

  1. 企微 iPad 协议层
    多台 iPad 企微账号实例,通过init初始化获取唯一uuid,绑定回调地址;所有收发消息、文件上传下载、群操作均通过该服务提供 POST 接口。每个账号独立uuid隔离会话。
  1. 消息回调层
    支持 HTTP 直推、RabbitMQ 两种回调模式,生产环境优先 MQ 异步解耦,避免企微 5 秒超时。回调标准入参:uuid(账号实例ID)json(完整消息体)type(消息类型)
  1. 消息消费预处理层
    解析回调 json,区分私聊 / 群聊、内部 / 外部联系人;图片 / 语音 / 文件自动调用 CDN 下载接口获取本地资源,转文本(语音调用SpeechToText转文字);过滤无意义闲聊、表情包、内部沟通消息。
  1. 第三方 AI 智能体层
    接收标准化客户提问、用户身份、会话上下文、附件内容,执行意图分类、知识库检索、业务接口调用,输出合规回复内容(支持文本、图片链接、小程序、引用格式)。
  1. 消息发送调度层
    将 AI 返回内容适配企微 iPad 协议对应发送接口,文本走SendTextMsg、图片先 CDN 上传再调用SendCDNImgMsg、引用消息调用sendQuoteMsg;发送完成标记会话已读。
  1. 数据持久层
    Redis 存储多轮会话上下文(30 分钟过期);MySQL 存储完整消息记录、AI 问答日志、客户标签、工单信息。

二、完整业务开发流程

前置准备:企微账号初始化 + 配置回调

步骤 1:企微实例账号初始化

调用接口:POST /wxwork/init
请求示例(首次登录无 vid,生成新设备)

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

返回uuid=427d7ee5-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"
}

返回errcode=0,回调配置生效,账号所有收发消息实时推送 MQ。

步骤 3:登录账号(自动登录流程)

  1. 首次登录:调用getQrCode获取二维码,客户扫码,验证码调用CheckCode完成登录;
  1. 后续登录:init接口传入上次登录vid,调用automaticLogin自动免登;
  1. 登录完成调用SyncAllData同步离线历史消息,补全会话上下文。

阶段 1:客户发送消息,企微推送回调

模拟客户(外部联系人 user_id=7881302555913738)向 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:消息消费预处理逻辑

  1. 基础解析
    通过is_room=0判定为私聊;调用GetUserInfoByVids传入sender,确认是外部客户,符合 AI 自动回复触发条件(内部员工消息直接过滤);
  1. 过滤规则校验
    配置规则:纯表情包 / 单字闲聊不触发;当前为业务咨询类问句,放行进入 AI;
  1. 上下文拼接
    Redis 读取该客户近 3 轮对话,拼接完整会话历史,一并传入 AI 智能体。

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

AI 智能体入参标准化结构

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

AI 内部执行链路:

  1. 意图识别:判定为「夏季连衣裙产品咨询」;
  1. RAG 知识库检索:匹配连衣裙尺码、衣长、库存、实拍素材信息;
  1. 工具调用:调用库存接口,确认全尺码现货;
  1. 回复生成:输出文本回答 + 连衣裙实拍图 CDN 链接;
  1. 安全过滤:校验无敏感词、价格合规,输出结构化返回:

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

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

  1. 图片 CDN 上传
    AI 返回图片网络地址,调用CdnUploadImgLink执行 CDN 上传,获取cdnkey、aeskey、md5等下发必填参数;
  1. 发送文本消息 + 发送 CDN 图片
    先调用SendTextMsg发送文字内容:

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

再调用SendCDNImgMsg上传返回的图片 CDN 参数;

  1. 标记消息已读
    调用MarkAsRead接口,清除客户会话小红点;
  1. 会话持久化
    将客户提问、AI 回复、发送日志写入 MySQL,更新 Redis 会话上下文。

场景 1:客户发送图片提问

客户上传连衣裙实物图,询问是否有同款:

  1. 回调收到msgtype=14图片消息,携带fileid、aes_key
  1. 预处理调用DownloadFileCDN 下载图片本地;
  1. AI 智能体接入图像识别能力,检索同款产品;
  1. AI 返回文字 + 商品小程序卡片,调用SendAppMsg发送小程序消息。

场景 2:群内 @AI 咨询(群聊自动回复)

客户在外部客户群 @iPad 企微账号提问:

  1. 回调is_room=true,content 包含 @标记;
  1. 预处理识别atids包含当前员工 user_id,触发 AI;
  1. AI 生成回复,调用SendTextAtMsgTwo格式化 @回复,群内自动 @提问客户。

场景 3:语音消息自动解析回复

客户发送 30 秒语音消息:

  1. 回调接收语音 CDN 参数;
  1. 调用DownloadFile下载语音文件;
  1. 调用协议SpeechToTextEntity接口,语音转文字;
  1. 转文字内容送入 AI 生成回复,文本下发客户。

场景 4:客户引用消息追问

客户引用 AI 之前的连衣裙消息提问:能不能退换?

  1. 回调携带quoteMsg完整引用消息结构体;
  1. 预处理提取引用消息内容,传入 AI 上下文;
  1. 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
@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);
}

五、场景落地约束与规范

  1. 消息触发规则
    仅外部客户(个微好友 / 外部企微客户)、@账号、业务问句触发 AI;内部员工、纯表情包、无意义短句直接跳过自动回复。
  1. 消息发送限流
    遵循企微 iPad 协议限制,单账号每分钟消息不超过 20 条,高频提问增加延迟缓冲。
  1. 内容合规约束
    AI 输出必须过敏感词过滤,禁止价格夸大、违规营销话术;企微发送接口返回errcode!=0时记录告警,人工介入。
  1. 会话生命周期
    Redis 上下文缓存 30 分钟无对话自动清空;MySQL 永久存储所有消息与 AI 问答日志,用于业务复盘。
  1. 账号运维
    通过GetRunClientGetRunClientByUuid定时巡检 iPad 登录状态,掉线自动执行automaticLogin重登,保证自动回复持续可用。

六、总结

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

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值