Skip to main content
集成 Agent

消息渠道接入

面向通过 Forward Channel API 接入外部 IM 平台的用户，介绍渠道授权、fixed/pairing 执行上下文模式，以及各渠道如何创建应用/机器人、需要配置哪些权限、需要获取哪些凭据。

现阶段推荐使用「扫码绑定」完成渠道授权，非必要不推荐直接配置凭据。钉钉、飞书、企业微信、个人微信均支持扫码绑定：创建 Channel 时可省略 channel_config.credentials，随后通过 QR Session 扫码授权即可完成绑定，无需在业务侧保存 App Secret 等敏感凭据，安全性更高、维护成本更低。仅在扫码绑定无法满足需求（如无人值守的服务端自动化）时，才考虑下文各渠道的「直连凭据」方式。

先区分渠道授权与 Channel Pairing

Forward Channel 有两个独立的配置维度：
维度解决的问题选项
渠道授权Forward 如何获取 IM 机器人连接和收发权限QR Session 扫码（推荐）或直连凭据
Identity 解析某条上行消息应使用哪个 Identity 和 Templatefixed 或 pairing
QR Session 的「扫码绑定」属于渠道凭据授权，与 Channel Pairing 不同。pairing 模式的 Channel 仍需先完成渠道授权使 binding_status=bound；之后当真实 IM 会话首次触发时，Forward 会生成 Pairing Code 来绑定该消息范围的执行上下文。

扫码绑定流程（推荐）

扫码绑定适用于 dingtalk、feishu、wecom、wechat 全部渠道，步骤如下：
  1. 创建 Channel：调用 创建 Channel 接口，传入 name、channel_type 及期望的 Identity 解析模式，省略 channel_config.credentials。fixed 模式需同时传入 identity_id 和 template_id；pairing 模式传 identity_resolution.mode=pairing，不传 identity_id 或 template_id。
  2. 创建 QR Session：调用 创建 Channel QR Session 接口，得到 qr_code_image_base64（二维码图片）或 qr_code_content（授权 URL）。poll_interval_seconds 为可选兼容字段，不应作为稳定返回值依赖。
  3. 展示二维码并扫码授权：将二维码展示给用户，使用对应渠道的客户端扫码并确认授权。
  4. 轮询授权状态：调用 获取 Channel QR Session 轮询 status。如响应中包含 poll_interval_seconds 则按该间隔轮询，否则默认 3 秒。直到状态变为 confirmed（其他状态：waiting、scanned、expired、denied、error）。
  5. 完成渠道授权：status=confirmed 后刷新 Channel 详情，binding_status 变为 bound。fixed 模式的 Channel 可立即使用固定的执行上下文处理上行消息；pairing 模式的 Channel 在收到未配对消息时会返回 Pairing Code——需完成下文的 Channel Pairing 后消息才会进入 Agent。
二维码有效期较短，expired 或 denied 后可重新创建 QR Session 再次扫码。

Identity 解析模式

fixed 模式

fixed 为默认模式。创建 Channel 时必须指定 identity_id 和 template_id；所有上行消息使用该固定执行上下文： 
{
  "identity_id": "idn_019eabc123",
  "identity_resolution": {
    "mode": "fixed"
  },
  "template_id": "tmpl_support",
  "channel_type": "feishu",
  "name": "Support Feishu channel"
}

pairing 模式

pairing 模式下 Channel 仅代表 IM 传输连接——创建时不指定 Identity 或 Template： 
{
  "identity_resolution": {
    "mode": "pairing"
  },
  "channel_type": "feishu",
  "name": "Support Feishu channel"
}
渠道授权完成后，配对流程如下：
  1. 用户从真实 IM 私聊或群聊向机器人发送消息。
  2. Channel Gateway 为未配对的 direct/room scope 创建待配对记录并发出配对码提示，不创建 Session。
  3. 管理员调用 配对 Channel，传入 code + identity_id + template_id；自动授权可先查询 配对列表，根据 channel_id + scope_type + scope_external_id 匹配自己的规则，再提交 channel_pairing_id + identity_id + template_id。
  4. 后续消息通过 Pairing 解析 Identity 和 Template，然后创建或复用 Session。
  5. 如需解除绑定，使用 Pair 响应中的 id 调用 解除配对。
Direct scope 以远端用户作为配对边界；room scope 以稳定的群/频道 ID 作为配对边界。同一 room 内不同成员和话题共享一个 Pairing，但 Session 和回复仍按会话/话题隔离。触发配对的原始消息在配对成功后不会重放——用户需要重新发送请求。
identity_resolution.mode 创建后不可修改。如需在 fixed 和 pairing 之间切换，必须删除并重建 Channel。

Identity 启停对消息的影响

无论使用 fixed 还是 pairing，解析到的 Identity 已停用时，新的普通消息不会启动 Agent 执行，渠道返回“Identity 已停用，请启用后再试。”。已接受的执行和结果回发会自然完成；已有待处理动作的确认及 /cancel 仍按原会话和权限规则处理。 停用 Identity 不会解除渠道绑定或修改 Channel 自身的开关；重新启用 Identity 也不会自动开启手动关闭的 Channel。完整行为见停用 Identity和启用 Identity。

直连凭据接入（按需）

若确需使用直连凭据，需在对应开放平台创建应用/机器人、配置权限并获取凭据，再通过 创建 Channel 接口的 channel_config.credentials 传入。各渠道 channel_type 与凭据字段映射：
渠道channel_typechannel_config.credentials 字段是否支持扫码绑定
钉钉dingtalkclient_id、client_secret是（推荐）
飞书feishuapp_id、app_secret是（推荐）
企业微信wecombot_id、secret是（推荐）
个人微信wechat无需凭据仅支持扫码绑定
凭据仅在创建/更新 Channel 时写入，不会明文回显。

钉钉接入

创建钉钉应用

  1. 前往 钉钉开放平台。需选择具备开发者权限的组织，或选择某个组织后获取开发者权限。如果没有合适的组织，可使用移动端钉钉扫码快速创建一个组织。
  2. 点击顶部导航栏 应用开发，在钉钉应用页面点击 创建应用。

创建钉钉机器人

  1. 应用创建完毕后，在左侧导航栏选择 添加应用能力，点击右侧机器人卡片下方的 添加 按钮。
  2. 在机器人配置页面，开启机器人配置。
  3. 消息接收模式 选择 Stream 模式，并点击 发布 完成对机器人的配置。

配置权限

在应用的 权限管理 中开通以下权限：
权限说明
Card.Streaming.Write流式写入卡片消息
Card.Instance.Write创建/更新卡片实例
qyapi_robot_sendmsg机器人发送消息

发布应用

  1. 在左侧导航栏选择 版本管理与发布，点击 创建新版本。
  2. 填写应用版本号和版本描述，并根据业务实际需求选择应用的可用范围，最后点击 保存 完成发布。
若可用范围选择全部员工，则应用发布后当前企业下所有员工都可见。

获取凭据

在左侧导航栏的 凭证与基础信息 页面，记录 Client ID 与 Client Secret，分别对应 API 的 client_id 与 client_secret。

飞书接入

创建飞书应用

  1. 访问 飞书开放平台，点击右上角 开发者后台。
  2. 点击 创建企业自建应用，填写必要信息并点击 创建。

添加并配置机器人

  1. 在左侧导航栏选择 添加应用能力，点击机器人卡片的 添加 按钮。
  2. 点击机器人配置卡片「如何开始使用」右侧编辑图标。
  3. 在 消息卡片回调请求方式 区域点击 去配置，订阅方式选择 使用长连接接收回调 并保存。
  4. 点击 事件配置，订阅方式同样选择 使用长连接接收回调 并保存。
  5. 在事件配置页面添加如下四个事件并保存：
    • 机器人进群
    • 机器人被移出群
    • 消息已读
    • 接收消息

配置权限

在 权限管理 > 开通权限 中，单击 批量导入/导出权限，粘贴以下 JSON 一键导入所需权限，确认后 申请开通： 
{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "docx:document:readonly",
      "im:chat:read",
      "im:chat:update",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "application:application:self_manage",
      "cardkit:card:write",
      "cardkit:card:read"
    ],
    "user": [
      "contact:user.employee_id:readonly",
      "offline_access",
      "base:app:copy",
      "base:field:create",
      "base:field:delete",
      "base:field:read",
      "base:field:update",
      "base:record:create",
      "base:record:delete",
      "base:record:retrieve",
      "base:record:update",
      "base:table:create",
      "base:table:delete",
      "base:table:read",
      "base:table:update",
      "base:view:read",
      "base:view:write_only",
      "base:app:create",
      "base:app:update",
      "base:app:read",
      "board:whiteboard:node:create",
      "board:whiteboard:node:read",
      "calendar:calendar:read",
      "calendar:calendar.event:create",
      "calendar:calendar.event:delete",
      "calendar:calendar.event:read",
      "calendar:calendar.event:reply",
      "calendar:calendar.event:update",
      "calendar:calendar.free_busy:read",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "contact:user:search",
      "docs:document.comment:create",
      "docs:document.comment:read",
      "docs:document.comment:update",
      "docs:document.media:download",
      "docs:document:copy",
      "docx:document:create",
      "docx:document:readonly",
      "docx:document:write_only",
      "drive:drive.metadata:readonly",
      "drive:file:download",
      "drive:file:upload",
      "im:chat.members:read",
      "im:chat:read",
      "im:message",
      "im:message.group_msg:get_as_user",
      "im:message.p2p_msg:get_as_user",
      "im:message:readonly",
      "search:docs:read",
      "search:message",
      "space:document:delete",
      "space:document:move",
      "space:document:retrieve",
      "task:comment:read",
      "task:comment:write",
      "task:task:read",
      "task:task:write",
      "task:task:writeonly",
      "task:tasklist:read",
      "task:tasklist:write",
      "wiki:node:copy",
      "wiki:node:create",
      "wiki:node:move",
      "wiki:node:read",
      "wiki:node:retrieve",
      "wiki:space:read",
      "wiki:space:retrieve",
      "wiki:space:write_only"
    ]
  }
}

发布应用

  1. 在左侧导航栏选择 版本管理与发布。
  2. 点击 创建版本，填写必要信息后点击 保存。

获取凭据

在应用的 凭证与基础信息 页面，复制 App ID（格式如 cli_xxx）和 App Secret，分别对应 API 的 app_id 与 app_secret。

企业微信接入

创建智能机器人

  1. 访问 企业微信管理后台，在左侧导航栏单击 安全与管理 > 管理工具，单击 创建机器人，然后单击 手动创建。
  2. 配置机器人可见范围。
  3. 下拉到页面底部单击 API 模式创建，连接方式选择 使用长连接。

获取凭据

在配置方法的 Secret 区域单击 点击获取，记录 Bot ID 和 Secret，分别对应 API 的 bot_id 与 secret。

个人微信接入

个人微信仅支持 扫码绑定，无需在开放平台创建应用，也无需配置任何直连凭据。创建 Channel 时 channel_type 传 wechat，直接按上文 扫码绑定流程（推荐） 完成授权即可。

相关

创建 Channel

创建 Channel QR Session

列出 Channel 配对

获取 Channel 配对

更新 Channel 配对

配对 Channel

解除配对

列出 Channels