企业微信客服

NOTE

“微信客服”是企业微信提供的一种全渠道对外服务能力。与“自建应用”不同，它直接连接外部微信用户，通过配置特定的“客服帐号”来开启与 CatWiki 的 AI 对接。

企业微信客服通过标准的 Webhook 回调方式集成。客服消息采用 XML 协议，且由于平台限制，必须通过异步 API 接口进行回复。

推荐场景

• 全渠道对外客服：通过微信扫码、视频号、公众号等入口，让普通微信用户直接调起 AI 客服。
• 售后支持：客户无需安装应用，直接在微信聊天框即可获得专业的售后知识解答。
• 售前咨询：与微信生态无缝连接，是企业接触外部客户最直接的 AI 应用载体。

前置背景与原理

⚠️ 必读：微信客服的 API 调用逻辑

很多开发者在配置“微信客服”时会遇到权限或 Secret 错误。请务必了解以下背景：

• 微信客服的 API 能力是借由“自建应用”来实现的。
• 在 2023 年 12 月之后，微信官方已停用直接获取“微信客服专属 Secret”的入口。
• 正确流程是：你必须先创建一个企业内部的“自建应用” -> 记录该自建应用的 Secret -> 用它作为信息传输通道 -> 最后在“微信客服”页面中将客服账号与这个自建应用绑定授权。

1. 企业微信管理后台配置

1.1 获取企业 ID (CorpID)

1. 登录 企业微信管理后台。
2. 在左侧菜单点击 “我的企业”，在最底部找到并记录下 “企业ID” (CorpID)。

1.2 创建自建应用并获取凭据

作为微信客服的“物理通道”，我们需要创建一个自建应用：

1. 在管理后台进入 “应用管理” -> “应用” -> “自建”，点击“创建应用”（例如命名为：CatWiki 智能客服）。

2. 创建成功后，进入该应用详情页，找到并记录下该应用的 Secret(不用记录AgentId)。
   (后续填入 CatWiki 后台的 Secret 就是这里获取的！)

3. 在同一页面，点击 “设置 API 接收”。

4. 填入以下信息：

   • URL：从CatWiki 后台配置获取，填入 https://您的域名/v1/bot/wecom-kefu?site_id={site_id}
   • Token 和 EncodingAESKey：点击随机获取，并记录下来。

   

5. ⚠️ 暂不点击保存！ 先将获取到的 Secret、Token 和 AES Key 填入 CatWiki 后台并开启服务（参考下一步），只有 CatWiki 服务启动后，再回到企微后台点击“保存”才能通过 URL 连通性测试。

1.3 创建与配置客服帐号

在使用 API 之前，请确保在微信客服内已建立相应的客服实体帐号：

1. 在企业微信后台进入 “应用管理” -> “应用” -> “微信客服”。
2. 页面中如果没有任何客服帐号，或者你需要一个新的分类客服，请点击 “创建帐号”，上传头像、填写客服名称（如“售前咨询”）。
3. 您可以点击刚创建的客服帐号卡片，进去配置接待人员、接待规则等基础设置。

1.4 绑定自建应用与客服体系 (授权关键步)

这一步是整个链路联通的核心。我们需要授权刚才的“自建应用”作为通道，来接管客服帐号的消息：

1. 依然在 “微信客服” 的主页面，往下滑到底部，找到 “API” 模块。

2. 第一步：绑定应用

   • 找到 “可调用接口的应用” ，点击右侧的 “绑定”（或“修改”）。
   • 在弹出的应用列表中，勾选你刚才在 1.2 步骤中创建并配好回调的自建应用，点击确认。

3. 第二步：配置应用的客服

   • 在同一个“API”模块下，点击它右侧对应的 “前往配置”
   • 或页面底部的“通过API管理会话消息-企业内部开发”
   • 勾选你需要交给这台 AI 接管的特定客服帐号（例如你刚才创建的“售前咨询”），完成配置。 (这里的核心逻辑是：企微平台上有多个客服帐号，你需要明确指定哪些帐号的事件，借由这个自建应用推给 CatWiki。)

1.5 配置可信 IP (重要防坑)

为保障企业数据安全，企业微信要求调用其接口的主机必须在白名单内：

1. 视企业微信不同版本而定，请在 自建应用详情页 或 微信客服-API模块 的最底部，找到 “企业可信IP”。
2. 填入您部署 CatWiki 的服务器的 公网出口 IP 地址 并保存。
   • 注意：若漏掉此步，AI 面对客户提问时尝试推送消息将会报 IP 拦截错误，呈现“已读不回”现象。

2. CatWiki 后台配置与打通验证

1. 保持企微后台页面不关，开个新标签页进入 CatWiki 后台 “站点设置” -> “AI 机器人”。
2. 选中 “企业微信客服” 卡片，开启开关。
3. 填入配置：
   • 企业 ID (CorpID)：填入 1.1 中获取的 CorpID。
   • 欢迎语 (可选)：用户首次打开客服窗口时自动发送的话术。
   • Corp Secret：填入 1.2 中获取的 自建应用的 Secret。
   • Token：填入 1.2 中随机生成的 Token。
   • EncodingAESKey：填入 1.2 中随机生成的 EncodingAESKey。
4. 点击界面上的 “保存”。此时 CatWiki 服务端已加载配置。
5. 打通验证：现在切回企业微信的 “设置 API 接收” 页面，点击 “保存”，提示验证成功即可！
6. 调试客服：

• 进入客服账号
• 生成二维码，手机扫码，开始提问

3. 技术特性

• 流式回复：❌ 不支持 (受限于微信客服平台 API 的消息体机制，此时系统默认采用非流式调用，统一将最后完整内容异步返回)。
• 协议机制：采用标准的 XML 协议进行消息加解密。
• 回复方式：采用游标轮询同步机制（kf/sync_msg）结合精准异步推送（kf/send_msg），并在服务端采取内存分布式锁，防重并发重发。