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。

直连凭据接入（按需）

若确需使用直连凭据，需在对应开放平台创建应用/机器人、配置权限并获取凭据，再通过 创建 Channel 接口的 channel_config.credentials 传入。各渠道 channel_type 与凭据字段映射：
渠道channel_typechannel_config.credentials 字段是否支持扫码绑定
钉钉dingtalkclient_id、client_secret是（推荐）
飞书feishuapp_id、app_secret是（推荐）
企业微信wecombot_id、secret是（推荐）
个人微信wechat无需凭据仅支持扫码绑定
Microsoft Teams（Global）teamsapp_id、tenant_id、client_secret否
凭据仅在创建/更新 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，直接按上文 扫码绑定流程（推荐） 完成授权即可。

Microsoft Teams 接入

Microsoft Teams 仅在 Global 提供。接入前需在客户的 Microsoft Entra 租户中创建应用，并将对应 Bot 安装到 Teams。当前支持个人聊天、Team 标准频道和多人群聊中的文本、图片和文件消息。

创建 Microsoft Entra 应用

  1. 登录 Microsoft Entra 管理中心，在目标租户中创建应用注册。
  2. Supported account types 选择仅限当前组织目录使用（Single tenant）。
  3. 在应用概览页记录 Application (client) ID 和 Directory (tenant) ID，分别对应 API 的 app_id 和 tenant_id。
  4. 在 Certificates & secrets 中创建 Client secret，并记录 secret 的 Value，对应 API 的 client_secret。
Client secret 的 Value 只会在创建时显示一次，请妥善保存；不要使用 Secret ID 代替 Value。

开通文件收发所需的 Microsoft Graph 权限

Teams 群聊和频道中的文件存储在 OneDrive 或 SharePoint。若要在多人群聊和 Team 标准频道中收发文件，需要为上一步创建的 Entra 应用开通以下 Microsoft Graph Application permissions（应用程序权限，不是 Delegated permissions）：
权限用途
Sites.ReadWrite.All读取和写入 SharePoint/OneDrive 文件，用于下载入站文件，以及上传并分享出站文件。
ChatMember.Read.All读取多人群聊的完整成员列表，用于为出站文件创建仅群成员可访问的分享链接。
配置步骤：
  1. 在 Microsoft Entra 管理中心打开对应的应用注册，进入 API permissions。
  2. 选择 Add a permission > Microsoft Graph > Application permissions。
  3. 添加 Sites.ReadWrite.All 和 ChatMember.Read.All。
  4. 由租户管理员点击 Grant admin consent，并确认两项权限的状态均显示已授予。
权限范围说明：上述权限为租户级应用权限。Sites.ReadWrite.All 可读写租户内所有站点集合中的文档和列表项，ChatMember.Read.All 可读取所有聊天的成员信息。请由客户租户管理员评估后授权。个人聊天通过 Teams FileConsent 收发文件时不依赖这两项 Graph 权限，但仍需要在 Teams 应用 manifest 中启用 supportsFiles。

创建并配置 Azure Bot

  1. 在 Azure Portal 中创建 Azure Bot，Microsoft App Type 选择 Single Tenant。
  2. 将 Azure Bot 绑定到上一步创建的 App ID 和 Tenant ID。
  3. 在 Azure Bot 的 Configuration 页面，将 Messaging endpoint 设置为 Global 环境提供的完整 Teams 消息回调地址，路径为 /channels/teams/messages。
  4. 在 Azure Bot 的 Channels 页面启用 Microsoft Teams 渠道。

创建并发布 Teams 应用

  1. 打开 Developer Portal for Teams，创建 Teams 应用。
  2. 添加 Bot capability，并绑定与 Azure Bot 相同的 App ID。
  3. 根据使用范围勾选 personal、team 和 groupChat scope。
  4. 在 Teams 应用 manifest 的 Bot 配置中设置 supportsFiles: true，用于启用个人聊天中的 FileConsent 文件收发能力。
  5. 在 manifest v1.12 或更高版本中，为群聊和频道入站文件解析声明 RSC 消息读取权限：多人群聊使用 ChatMessage.Read.Chat，Team 标准频道使用 ChannelMessage.Read.Group。
  6. 下载应用包，通过客户的 Teams 管理中心或组织 App catalog 发布，并在目标个人聊天、多人群聊或 Team 中安装。更新 manifest 权限后，需要重新发布并在目标多人群聊或 Team 中重新安装/同意应用。
manifest 关键配置示例： 
{
  "webApplicationInfo": {
    "id": "<Application (client) ID>",
    "resource": "api://<Application (client) ID>"
  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        {
          "name": "ChatMessage.Read.Chat",
          "type": "Application"
        },
        {
          "name": "ChannelMessage.Read.Group",
          "type": "Application"
        }
      ]
    }
  },
  "bots": [
    {
      "botId": "<Application (client) ID>",
      "scopes": ["personal", "team", "groupChat"],
      "supportsFiles": true
    }
  ]
}
RSC 权限声明在 Teams 应用 manifest 中，不在 Entra 的 API permissions 页面添加；其授权范围仅限安装该应用的目标多人群聊或 Team。ChatMessage.Read.Chat 和 ChannelMessage.Read.Group 用于在当前入站消息的 Bot 回调缺少完整附件信息时，通过 Graph 补查该消息及其附件，不会取消现有的 @Bot 触发要求。 在 Team 标准频道和多人群聊中，用户需要显式 @Bot 才会触发消息；个人聊天不需要 @Bot。

创建 Teams Channel

调用 创建 Channel，channel_type 传 teams，并在 channel_config.credentials 中提供 app_id、tenant_id 和 client_secret。 创建成功后，确认 Channel 的 enabled=true 且 binding_status=bound，再分别从个人聊天、Team 标准频道和多人群聊验证文本、图片及文件的收发。群聊和频道场景需要使用显式 @Bot 的消息进行验证。
当前 Teams 接入支持文本、图片、文件消息和文本审批操作。个人聊天文件通过 Teams FileConsent 收发；多人群聊和 Team 标准频道文件通过 SharePoint/OneDrive 与 Bot Connector 处理。仍不支持通用卡片、主动消息、会议或语音能力。群聊和频道入站文件补查需要上述 RSC 权限，但当前仍只处理个人聊天消息或显式 @Bot 的群聊/频道消息，不会监听全部消息。
Microsoft 参考文档：

相关

创建 Channel

创建 Channel QR Session

查询 Channel 配对列表

获取 Channel 配对

更新 Channel 配对

配对 Channel

解除配对

列出 Channels

快速入门
构建 Agent
配置 Agent 环境
委派任务给 Agent
集成 Agent
管理 Agent 上下文
账户
最佳实践
公告
API 参考