返回上一级 最佳实践

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

企微 iPad 协议 消息回调 · AI 智能体 协议文档：wechatapi.apifox.cn
企微消息回调对接 AI 智能体分层架构图

文档背景

本文基于企业微信 iPad 协议接口，完整实现「企微消息回调接收 → 消息预处理 → 第三方 AI 智能体语义推理 → 企微多类型消息自动下发」全链路。协议底层为 wechatapi.apifox.cn 企微 iPad 客户端 API；AI 智能体可采用 RAG 检索增强大模型，承载产品咨询、售后答疑、活动解答、多轮对话、工单触发等能力。

适用场景

  • 零售连锁等场景：员工用企微接待外部客户 / 客户群
  • 客户私聊 / 群内提问自动 AI 回复，支持文本、图片、文件、语音解析
  • 区分内部员工与外部客户，过滤闲聊，仅业务问题触发 AI
  • AI 可调用企业知识库、订单接口，支持引用回复、图文 / 链接 / 小程序
  • 离线消息同步、会话留痕、人工接管；多账号 iPad 实例并行隔离

分层架构职责

  1. 企微 iPad 协议层：init 初始化获取唯一 uuid，绑定回调；收发消息、CDN、群操作均经该服务 POST 接口。
  2. 消息回调层：支持 HTTP / RabbitMQ；生产优先 MQ 异步，避免企微 5 秒超时。入参含 uuid、json、type。
  3. 消息预处理层：区分私聊/群聊、内外部联系人；图片/语音/文件走 CDN 下载，语音可 SpeechToText 转文字；过滤闲聊与内部沟通。
  4. 第三方 AI 智能体层：意图分类、知识库检索、业务接口调用，输出合规回复。
  5. 消息发送调度层：文本 SendTextMsg、图片 CDN 后 SendCDNImgMsg、引用 sendQuoteMsg；完成后 MarkAsRead。
  6. 数据持久层：Redis 多轮上下文（约 30 分钟）；MySQL 存消息与问答日志。

开发流程概要

前置：初始化 + 回调

  1. POST /wxwork/init 获取 uuid（全程复用）
  2. /wxwork/SetCallbackUrl 配置 RabbitMQ（生产推荐）或 HTTP 回调
  3. 首次：getQrCode → 扫码 → CheckCode；后续：vid + automaticLogin；登录后 SyncAllData

运行时四阶段

  1. 客户发消息，企微推送回调到 MQ / HTTP
  2. 预处理：判定私聊/外部客户、过滤规则、拼接 Redis 近 3 轮上下文
  3. AI：意图识别 → RAG → 工具调用 → 安全过滤 → 结构化回复
  4. 下发：CdnUploadImgLink（如需）→ SendTextMsg / SendCDNImgMsg → MarkAsRead → 持久化

典型场景

  • 图片提问：msgtype=14 → DownloadFileCDN → 图像识别 → 文本 + SendAppMsg 小程序
  • 群内 @AI：is_room=true 且 atids 含本账号 → SendTextAtMsgTwo 格式化 @回复
  • 语音：下载语音 → SpeechToTextEntity → AI 文本回复
  • 引用追问：提取 quoteMsg → sendQuoteMsg 引用式回复

关键异常处理

  • 回调仅约 5 秒窗口：禁止同步调 AI，统一 MQ 异步，回调立即返回 {"errcode":0}
  • 文件解析失败：兜底提示重新发文字
  • AI 熔断：兜底话术并可转人工
  • 多账号按 uuid + userid 隔离会话，避免串话
  • 重登后 SyncAllData 补齐离线消息再消费

落地约束

  • 仅外部客户、@账号、业务问句触发；内部员工与无意义短句跳过
  • 单账号每分钟消息建议不超过约 20 条，必要时延迟缓冲
  • AI 输出过敏感词过滤；errcode≠0 告警人工介入
  • 定时巡检 GetRunClient / GetRunClientByUuid，掉线 automaticLogin

完整接口字段与联调请参阅 正式 API 文档。需要报备测试可 联系客服微信 Mrzhu0107。