Connector — 多平台 IM 接入

Connector 是数字员工接入外部即时通讯（IM）平台的通道。通过 Connector，数字员工可以接收和回复飞书、企业微信、钉钉等平台上的消息，将数字员工的能力延伸到日常办公 IM 中。

概述

Connector 与数字员工绑定：每个 Connector 归属于一个数字员工，该数字员工发布的平台账号收到的消息会路由到对应数字员工处理。

当前支持的平台：

平台	类型标识	说明
飞书	feishu	通过飞书开放平台自建应用接入（WebSocket 长连接）
企业微信	wecom	通过企业微信机器人接入
钉钉	dingtalk	通过钉钉开放平台企业内部应用接入（Stream 长连接）

更多平台（微信、邮件）正在规划中。

创建 Connector

Connector 的创建入口位于数字员工详情页的 Connector 菜单项（数字员工必须已发布）。

点击 新建 Connector，选择平台类型并填写对应配置：

飞书

需要在飞书开放平台（open.feishu.cn）创建企业自建应用并完成以下配置（长连接模式仅支持企业自建应用）：

1. 创建应用：登录开发者后台 → 创建企业自建应用。在 基础信息 → 凭证与基础信息 页面复制 App ID（格式 cli_xxxxx）与 App Secret。
2. 启用机器人：应用能力 → 添加应用能力 → 添加「机器人」（接收与发送消息的前提）。
3. 开通 API 权限：开发配置 → 权限管理 → API 权限，开通以下三项：
   • 读取用户发给机器人的单聊消息（im:message.p2p_msg:readonly）
   • 以应用的身份发消息（im:message:send_as_bot）
   • 接收群聊中 @机器人 消息事件（im:message.group_at_msg:readonly）
4. 订阅接收消息事件：开发配置 → 事件与回调 → 事件配置，订阅方式选择「使用长连接接收事件」，然后在已添加事件中添加「接收消息」（im.message.receive_v1）。 注意：保存长连接订阅方式前，需先在 Gendial 完成下方配置并启动 Connector（飞书会检测应用是否已建立长连接，否则保存时提示"未检测到应用连接信息"）。
5. 发布应用：应用发布 → 版本管理与发布 → 创建版本并发布（企业账号需管理员审核）。权限或事件变更后必须重新发布版本才会生效，可用范围需包含目标使用者。

之后在 Gendial 新建 Connector 时填入 App ID / App Secret 即可（验证令牌无需填写，长连接模式自动处理加密与验签）。

平台注意事项：每个应用最多建立 50 条长连接；同一应用部署多个客户端时，消息只会推送给其中随机一个（Gendial 单实例部署不受影响）。

钉钉

需要先在钉钉开放平台（open-dev.dingtalk.com）创建企业内部应用，并完成以下配置（需要应用开发子管理员权限）：

1. 创建应用：应用开发 → 创建企业内部应用，记录 ClientId（即 AppKey）与 ClientSecret（即 AppSecret）。
2. 启用机器人：应用能力 → 添加「机器人」，消息接收模式选择 Stream 模式（无需公网回调地址）。
3. 申请接口权限：权限管理 → 搜索并申请「企业内机器人发送消息权限」（覆盖单聊/群聊发消息与文件下载）。权限免审批即时生效，但变更权限后必须重新发布版本才会生效。
4. 发布应用：版本管理与发布 → 发布版本，可用范围需包含目标使用者。未发布或不在可用范围内的用户，单聊消息将无法识别发送者身份。
5. 群聊（可选）：在目标钉钉群的 群设置 → 机器人 中添加该机器人。钉钉群聊仅接收 @机器人 的消息，且不支持接收文件/语音。
6. 确认配额：标准版 OpenAPI 约 1 万次/月（出站回复与文件下载均消耗配额），用量大需升级专业版或专属版。

之后在 Gendial 新建 Connector 时填入 ClientId / ClientSecret 即可。

企业微信

需要在企业微信管理后台创建智能机器人（不是群聊里添加的群机器人），并开启长连接 API 模式：

1. 创建机器人：登录企业微信管理后台（work.weixin.qq.com）→ 安全与管理 → 管理工具 → 智能机器人 → 创建机器人（手动创建）。
2. 配置可见范围：设置哪些成员可以使用该机器人。
3. 开启 API 模式：在机器人配置页面开启「API 模式」，连接方式选择「长连接」。
4. 获取凭证：在 Secret 区域点击「获取」，记录 Bot ID 与 Secret。注意：Secret 是长连接专用密钥，仅显示一次，丢失需在机器人详情页重新生成；它与回调地址模式的 Token/EncodingAESKey 无关。
5. 模式互斥：API 模式下「长连接」与「设置接收消息回调地址」只能二选一，切换到回调地址模式会使现有长连接失效。
6. 群聊（可选）：在目标群的群设置中添加该智能机器人，群聊中通过 @机器人 触发。

建议由企业超级管理员创建机器人：非超管创建时，消息中的成员 userid 为加密 userid，影响按成员识别会话。

之后在 Gendial 新建 Connector 时填入 Bot ID / Secret 即可。

默认工作站（灵活工作模式）

如果数字员工处于灵活工作模式，可以选择 默认工作站：该 Connector 收到的消息统一在指定工作站上执行工具调用。

管理 Connector

Connector 列表展示名称、类型、关联数字员工、启用状态、运行状态与创建者。

对每个 Connector 可以执行：

• 启动 / 停止：控制 Connector 运行状态（停止后不再接收消息）
• 启用 / 禁用：控制 Connector 配置生效状态（禁用会自动先停止）
• 删除：删除 Connector（会先尝试停止）

管理员视图

租户管理员在后台管理的 Connectors 页面可以查看租户内所有 Connector 并执行同样的管理操作。

消息能力

Connector 支持的消息类型：

• 文本消息：常规对话
• 图片消息：自动下载图片内容供数字员工理解（飞书通过消息资源端点下载，钉钉通过 downloadCode 换取临时链接下载）
• 文件消息：自动下载文件内容（飞书通过消息资源端点下载，钉钉通过 downloadCode 换取临时链接下载）
• 引用消息：企业微信支持引用消息上下文（钉钉暂不支持）

群聊

同一群聊中可以配置多个机器人（同一数字员工的多个 Connector 或多个数字员工），系统会为每个机器人维护独立的会话上下文，避免消息串扰。钉钉群聊仅接收 @机器人 的消息，这是钉钉平台行为。

定时任务通知

由飞书、企业微信或钉钉 Connector 私聊创建的计划任务，会将 connector_id、发送者和原始私聊目标保存为任务来源；群聊任务则保存发送者和原始群 chat_id。执行结果只原路回复创建任务的原私聊或群聊，不从合成 user_id、最近联系人或首个群聊推测目标。即使用户之后执行 /new，原路目标快照仍可用于投递。

网站创建的计划任务在当前版本只发送 Web/WorkPal 站内通知，不提供选择 Connector 目标的设置。Connector 投递采用至少一次语义；Connector 暂停时只重试投递，不会重复执行 AI 任务。