企业微信客服 IM 接入流程

企业微信客服会话接入 EasyAI：企微侧应用与客服配置、URL 验证、渠道接入与联调检查

本文说明如何将**企业微信客服（Customer Service）**接入 EasyAI，让外部客户在企微客服会话中的消息由智能体自动接管回复。

整体链路分为四步：

企微侧准备：创建应用、开通客服能力、准备回调参数
URL 验证：在企业微信完成客服回调地址验证
EasyAI 侧配置：新增 wecom-cs 渠道并绑定智能体
联调验收：确认收发消息、幂等与故障排查

一、企微侧准备（先完成）

1.1 创建企业内部应用（客服回调与发消息依赖）

登录企业微信管理后台。
进入 应用管理，创建一个企业内部应用（可命名为“EasyAI 客服助手”）。
记录以下信息（后续 EasyAI 配置会用到）：
- CorpID（企业 ID）
- AgentId（应用 AgentId）
- Secret（应用 Secret）

字段获取位置（建议按下面路径查找）：

CorpID：企业微信管理后台右上角进入我的企业（或企业信息页）可查看 企业 ID（CorpID）
Secret：必须先创建企业自建应用，再进入该应用详情页的凭证与基础信息获取应用 Secret
AgentId：在同一个自建应用详情页的基础信息中查看 AgentId

建议：将该应用仅授权给需要接待的客服成员，减少权限面。

1.2 开通企业微信客服能力

在企微管理后台进入客服相关模块（不同版本入口名称可能为「客户联系 / 客服」）。
开通客服能力并创建客服账号（open_kfid）。
配置可接待成员与接待范围，确保测试成员可被分配会话。

若企业未开通客服能力，后续即使 URL 验证成功，也不会有客服消息回调到 EasyAI。若尚未创建客服账号，EasyAI 后台点击「获取客服ID」会拿不到可选项，请先在企微侧创建至少 1 个客服账号。

1.2.1 非常容易遗漏：配置“可调用接口的应用”

请在企业微信后台进入：应用管理 → 微信客服 → API，配置“可调用接口的应用”为你刚创建的自定义应用（用于调用客服相关 API）。

这个入口在后台里不显眼，实操中非常容易漏配。
若未配置，常见现象是 URL 看起来已通过，但客服账号拉取、发消息或会话状态变更接口会报权限/调用失败。

1.2.2 推荐配置：微信开发者ID绑定（用于获取 unionid）

在企业微信后台 应用管理 → 微信客服 中，找到微信开发者ID绑定，按指引通过小程序或公众号完成绑定。

绑定后的用途：

可通过 API 获取微信客户对应的微信身份标识 unionid
有助于识别同一微信用户在不同入口（小程序、公众号、企微客服）下的统一身份
在 EasyAI 侧可提升用户映射稳定性，降低同一用户被拆分成多个身份的概率

基础消息接入不强依赖该配置；但如果你希望做跨渠道用户打通、统一画像或更稳定会话归并，建议务必配置。

1.2.3 关键补充：在“API 管理会话消息”里为应用配置客服

很多接入失败并不是回调地址问题，而是漏了这一步。

请在企业微信后台进入 应用管理 → 微信客服，拉到配置页最下方，找到 API 管理会话消息，并执行：

选择 企业内部开发。
在“指定应用”中选择你用于接入 EasyAI 的企业内部应用（即前文创建并记录了 AgentId/Secret 的应用）。

在该应用下为需要接入的客服进行配置（关联可管理的客服账号）。

保存配置后，再回到 EasyAI 执行「获取客服ID」与联调验证。

若未在这里完成“企业内部开发 + 指定应用配置客服”，常见现象是：
EasyAI 侧可创建渠道，但客服 ID 拉取不全或为空
会话消息管理/状态变更接口调用失败（权限不足）
同一企业下多应用场景中，消息无法按预期路由到目标应用

1.3 准备回调验证参数

在企业微信管理后台 应用管理 → 进入你的自定义应用 → 接收消息 页面，需要配置三组参数：

Token：自定义字符串（建议高强度随机）
EncodingAESKey：43 位随机字符串（企微回调加解密使用）
URL：EasyAI 对外可访问的回调地址（见下一节）

建议先在运维侧准备好公网域名与 HTTPS，再进行 URL 验证。

二、URL 验证与回调配置

企业微信会在保存回调地址时进行校验，只有校验通过才会开始推送客服事件。

2.1 回调地址格式

请将 URL 指向 EasyAI 的企微客服 webhook，URL 路径里要带 open_kfid（路由参数），例如：

https://你的域名/api/im-gateway/webhook/wecom-cs/wkf_xxx

实际路径以你当前部署网关路由为准；若你有反向代理前缀，请带上前缀。
open_kfid 配置建议：
初次接入时，可先填写一个临时值完成 URL 验证；
后续在 EasyAI 后台配置客服列表后，获取真实客服 ID（open_kfid）；
回到企微后台，把 URL 中的 open_kfid 改成与 EasyAI 后台一致的值。

2.2 在企微后台执行 URL 验证

先确认企业可信 IP 已配置：

在企业微信管理后台 应用管理 → 进入你的自定义应用 页面。
将 EasyAI 网关出口公网 IP（或反向代理出口 IP）加入企业可信 IP白名单。
如为多出口网络，请把所有可能出口 IP 都加入白名单。

未配置企业可信 IP 时，URL 验证通常会失败，或后续消息回调不稳定。

完成可信 IP 配置后，再执行 URL 验证：

打开企业应用/客服应用的回调配置页面。
填入：

URL（路径中需包含 open_kfid）
Token
EncodingAESKey

点击保存或验证。

验证通过的标志：

企微页面提示「校验成功」或等价文案。
EasyAI 网关日志出现回调校验请求并返回成功。

2.3 URL 验证失败的常见原因

回调地址不可公网访问（内网地址、DNS 未生效、防火墙拦截）
HTTPS 证书异常或域名不匹配
Token / EncodingAESKey 与 EasyAI 渠道配置不一致
企业可信 IP 未配置、配置错误或尚未生效
反向代理未正确转发 query 参数（msg_signature、timestamp、nonce、echostr）
网关未部署 wecom-cs webhook 路由

三、EasyAI 后端新增渠道配置（关键步骤）

在 EasyAI 管理后台创建 IM 渠道，将企微客服消息路由到指定智能体。

3.1 进入渠道管理

菜单入口：管理后台 → IM 渠道
新建路径通常为：/admin/im-channels/new

3.2 新建企业微信客服渠道

点击 新建 IM 渠道
填写基础信息：
- 渠道名称：如 企微客服-售前
- IM 平台：选择 企业微信客服（wecom-cs）
- 绑定智能体（Agent）：选择用于自动回复的智能体
平台配置（platform_config）填写：
- openKfId（必填）
- corpId
- corpSecret（必填，兼容历史字段 secret）
- （可选）handoverServicerUserId（转人工的默认客服 ID，填写企微内部成员 userid，可在企业微信后台 通讯录 → 成员详情 获取；不是 open_kfid）
- （可选）token
- （可选）encodingAESKey
点击 获取客服ID，选择要接管该渠道的客服 open_kfid（即 openKfId），并确认该渠道绑定了正确的 Agent。
- 若列表为空，先回企业微信创建客服账号，再重新点击获取。
将这个正确的 open_kfid 复制回企业微信后台「接收消息」配置，替换最初 URL 中用于验证的占位客服 ID。
保存并启用渠道。

可参考配置结构：

{
  "openKfId": "wkf_xxxxxxxxxxxxxxxx",
  "corpId": "wwxxxxxxxxxxxxxxxx",
  "corpSecret": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "handoverServicerUserId": "zhangsan",
  "token": "easyai_wecom_cs_token",
  "encodingAESKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}