企微 IM 接入流程

本文说明如何将企业微信（企微）作为 IM 渠道接入 EasyAI 平台，实现「用户关联 → 企微创建 BOT → EasyAI 对接 BOT 并指定 Agent → 治理规则配置主动推送」的完整流程。

一、用户关联：绑定企业微信用户 ID

将 EasyAI 平台用户与企微成员一一对应，便于 IM 消息识别身份、单聊推送时精确到人。

1.1 作用说明

• 单聊消息：系统通过「企业微信成员 userid」识别是哪个企微用户，若该 userid 已绑定到平台用户，则与对应用户的权限、上下文一致。
• 主动推送：治理规则里选择「单聊」目标时，可选「已绑定企微 ID 的用户」或「曾在会话中出现过的企微 ID」。

因此需要先在平台侧为对应用户填写企业微信成员 userid（即下文「企业微信 ID」）。

1.2 在 EasyAI 平台填写企业微信 ID

1. 使用管理员账号登录 EasyAI 管理后台。
2. 进入用户管理（或组织/成员管理），找到要绑定的用户。
3. 编辑该用户，在表单中找到 「企业微信ID」 字段。
4. 将企微成员的 userid 填入并保存。

字段说明：用于 IM 消息与系统用户关联，即企业微信通讯录中的成员 userid（非微信号、非手机号）。

1.3 企业微信 userid 的获取方法

企业微信的成员 userid 由企业唯一标识，可在以下方式中任选其一获取。

方式一：企业微信管理后台 → 通讯录

1. 使用管理员账号登录 企业微信管理后台。
2. 左侧进入 「通讯录」。
3. 点击目标成员姓名进入成员详情页。
4. 在详情页中查看 「账号」 或 「UserID」 等字段（不同版本可能写为「成员账号」/「userid」），该值即为企业微信成员 userid。

方式二：通过通讯录 API 获取

若已配置了企业微信应用与 Secret，可调用 通讯录 API - 读取成员 获取成员信息，返回结果中的 userid 即为所需 ID。

GET https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&userid=USERID

返回示例中的 userid 即用于在 EasyAI 用户管理中填写的「企业微信ID」。

二、企微通过 API 模式创建机器人 BOT

EasyAI 当前通过企业微信智能体机器人（API 模式） 与企微建立长连接，需先在企微侧创建机器人并拿到 Bot ID 与 Secret。

2.1 创建步骤

1. 使用管理员账号登录 企业微信管理后台。
2. 进入 「安全与管理」 → 「管理工具」 → 「智能体机器人」。
3. 点击 「创建机器人」，选择 「API 模式」 创建。
4. 创建完成后，在机器人详情/配置页中获取：
   • Bot ID：用于标识该机器人。
   • Secret：用于接口鉴权，请勿泄露。

2.2 配置要点

• 仅需 Bot ID 和 Secret 即可在 EasyAI 中完成鉴权，无需单独配置企业 ID、AgentId 等。
• 若需限制使用范围，可在企微后台为该机器人配置可见范围与权限。

三、EasyAI 平台对接企微 BOT 并指定 Agent

在 EasyAI 管理后台创建「IM 渠道」，选择企业微信长连接并填入 Bot 信息，同时指定由哪个 Agent 处理该渠道的消息。

3.1 入口与路径

• 入口：管理后台侧边栏 / 导航中的 「IM 渠道」（或「即时通讯」相关菜单）。
• 路径：/admin/im-channels；新建为 /admin/im-channels/new 或通过「新建 IM 渠道」进入。

3.2 新建 / 编辑 IM 渠道

1. 在 IM 渠道列表页点击 「新建 IM 渠道」（或编辑已有渠道）。
2. 渠道名称：填写便于识别的名称，如「客服机器人」「运维助手」。
3. IM 平台：选择 「企业微信长连接」（wecom-ws）。
   • 创建后平台类型不可修改，请确认选择正确。
4. 绑定智能体（Agent）：在下拉框中选择要处理该渠道消息的 Agent。
   • 用户通过该企微 BOT 发送的消息，都会由该 Agent 回复。
5. 平台配置（企业微信长连接）：
   • Bot ID：填写企微智能体机器人（API 模式）的 Bot ID。
   • Secret：填写该机器人的 Secret。
6. 启用状态：根据需要选择启用/禁用，保存后即可生效（无需重启服务）。

保存后，后端会与该 Bot 建立长连接；在渠道列表中可查看链接状态，必要时可使用「重新连接」进行重连。

四、主动推送设置：治理规则中配置主动推送

通过「治理规则」配置在任务完成/失败/升级时，向企微单聊或群聊主动推送通知。

4.1 入口与前置条件

• 入口：管理后台 「治理规则」（或「治理」→「规则」），路径一般为 /admin/governance/rules。
• 前置条件：
  • 已至少创建一个启用状态的 IM 渠道（如上述企微长连接渠道）。
  • 单聊推送时，目标为「用户」：需为平台用户绑定企业微信 ID（见第一节），或该企微 userid 曾在会话中出现（可从「可推送用户」列表中选）。

4.2 配置步骤

1. 在治理规则列表中 新增规则 或 编辑已有规则。
2. 在规则编辑弹窗中切换到 「IM推送」 Tab。
3. 启用 IM 推送：打开「启用 IM 推送」开关。
4. 推送时机：勾选需要推送的时机：
   • 任务完成时
   • 任务失败时
   • 任务升级时
5. 发送到单聊或群聊：
   • 点击 「按规则配置」 增加一条推送目标，或 「从现有会话选择」 从已有 IM 会话中勾选。
   • 每条目标需选择：
     • 机器人渠道：选择对应的 IM 渠道（如刚配置的企微渠道）。
     • 单聊/群聊：选「单聊」或「群聊」。
     • 目标：
       • 群聊：选择已存在的群聊 ID（从系统拉取的群列表中选择）。
       • 单聊：选择用户（含企微 ID 或用户映射），即已绑定企微 userid 的用户或曾在会话中出现的企微 userid。
6. 可配置多条推送目标（不同渠道、单聊/群聊、不同用户或群）。
7. 保存规则后，当治理任务满足所选「推送时机」时，将向配置的企微单聊/群聊主动推送消息。

4.3 小结

流程串联一览

1. 用户关联：在 EasyAI 用户管理中为用户填写「企业微信ID」（企微成员 userid），userid 可从企微管理后台通讯录或通讯录 API 获取；截图可自行插入文档。
2. 企微创建 BOT：企微管理后台 → 安全与管理 → 管理工具 → 智能体机器人 → API 模式创建 → 获取 Bot ID、Secret。
3. EasyAI 对接 BOT：管理后台 → IM 渠道 → 新建渠道 → 选「企业微信长连接」→ 填 Bot ID、Secret → 选择绑定的 Agent → 保存。
4. 主动推送：管理后台 → 治理规则 → 编辑/新增规则 → IM推送 Tab → 启用推送、选择推送时机、配置「渠道 + 单聊/群聊 + 目标用户或群」。

按以上顺序完成配置后，企微 IM 接入与主动推送即可正常使用。