> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # 消息渠道接入配置指南 > 面向通过 Forward Channel API 接入外部 IM 平台的用户，介绍渠道授权、fixed/pairing 执行上下文模式，以及各渠道如何创建应用/机器人、需要配置哪些权限、需要获取哪些凭据。 **现阶段推荐使用「扫码绑定」完成渠道授权，非必要不推荐直接配置凭据。** 钉钉、飞书、企业微信、个人微信均支持扫码绑定：创建 Channel 时可省略 `channel_config.credentials`，随后通过 QR Session 扫码授权即可完成绑定，无需在业务侧保存 App Secret 等敏感凭据，安全性更高、维护成本更低。 仅在扫码绑定无法满足需求（如无人值守的服务端自动化）时，才考虑下文各渠道的「直连凭据」方式。 ## 先区分渠道授权与 Channel Pairing Forward Channel 有两个独立的配置维度： | 维度 | 解决的问题 | 选项 | | ----------- | ------------------------------- | ---------------------- | | 渠道授权 | Forward 如何获取 IM 机器人连接和收发权限 | QR Session 扫码（推荐）或直连凭据 | | Identity 解析 | 某条上行消息应使用哪个 Identity 和 Template | `fixed` 或 `pairing` | QR Session 的「扫码绑定」属于渠道凭据授权，与 Channel Pairing 不同。`pairing` 模式的 Channel 仍需先完成渠道授权使 `binding_status=bound`；之后当真实 IM 会话首次触发时，Forward 会生成 Pairing Code 来绑定该消息范围的执行上下文。 ## 扫码绑定流程（推荐） 扫码绑定适用于 `dingtalk`、`feishu`、`wecom`、`wechat` 全部渠道，步骤如下： 1. **创建 Channel**：调用 [创建 Channel](/zh/cloud-agents/api/forward/channels/create) 接口，传入 `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](/zh/cloud-agents/api/forward/channels/create-qr-session) 接口，得到 `qr_code_image_base64`（二维码图片）或 `qr_code_content`（授权 URL）。`poll_interval_seconds` 为可选兼容字段，不应作为稳定返回值依赖。 3. **展示二维码并扫码授权**：将二维码展示给用户，使用对应渠道的客户端扫码并确认授权。 4. **轮询授权状态**：调用 [获取 Channel QR Session](/zh/cloud-agents/api/forward/channels/get-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`；所有上行消息使用该固定执行上下文： ```json theme={null} { "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： ```json theme={null} { "identity_resolution": { "mode": "pairing" }, "channel_type": "feishu", "name": "Support Feishu channel" } ``` 渠道授权完成后，配对流程如下： 1. 用户从真实 IM 私聊或群聊向机器人发送消息。 2. Forward 为未配对的 direct/room scope 创建或复用一个 6 位 Pairing Code，仅回复配对提示，不创建 Session。 3. 管理员调用 [配对 Channel](/zh/cloud-agents/api/forward/channels/pair-channel)，传入 `code + identity_id + template_id`。 4. 后续消息通过 Pairing 解析 Identity 和 Template，然后创建或复用 Session。 5. 如需解除绑定，使用 Pair 响应中的 `pairing_id` 调用 [解除配对](/zh/cloud-agents/api/forward/channels/unpair-channel)。 Direct scope 以远端用户作为配对边界；room scope 以稳定的群/频道 ID 作为配对边界。同一 room 内不同成员和话题共享一个 Pairing，但 Session 和回复仍按会话/话题隔离。触发配对的原始消息在配对成功后不会重放——用户需要重新发送请求。 `identity_resolution.mode` 创建后不可修改。如需在 `fixed` 和 `pairing` 之间切换，必须删除并重建 Channel。 ## 直连凭据接入（按需） 若确需使用直连凭据，需在对应开放平台创建应用/机器人、配置权限并获取凭据，再通过 [创建 Channel](/zh/cloud-agents/api/forward/channels/create) 接口的 `channel_config.credentials` 传入。各渠道 `channel_type` 与凭据字段映射： | 渠道 | `channel_type` | `channel_config.credentials` 字段 | 是否支持扫码绑定 | | ---- | -------------- | ------------------------------- | -------- | | 钉钉 | `dingtalk` | `client_id`、`client_secret` | 是（推荐） | | 飞书 | `feishu` | `app_id`、`app_secret` | 是（推荐） | | 企业微信 | `wecom` | `bot_id`、`secret` | 是（推荐） | | 个人微信 | `wechat` | 无需凭据 | 仅支持扫码绑定 | 凭据仅在创建/更新 Channel 时写入，不会明文回显。 ## 钉钉接入 ### 创建钉钉应用 1. 前往 [钉钉开放平台](https://open-dev.dingtalk.com/)。需选择具备开发者权限的组织，或选择某个组织后获取开发者权限。如果没有合适的组织，可使用移动端钉钉扫码快速创建一个组织。 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. 访问 [飞书开放平台](https://open.feishu.cn/)，点击右上角 **开发者后台**。 2. 点击 **创建企业自建应用**，填写必要信息并点击 **创建**。 ### 添加并配置机器人 1. 在左侧导航栏选择 **添加应用能力**，点击机器人卡片的 **添加** 按钮。 2. 点击机器人配置卡片「如何开始使用」右侧编辑图标。 3. 在 **消息卡片回调请求方式** 区域点击 **去配置**，订阅方式选择 **使用长连接接收回调** 并保存。 4. 点击 **事件配置**，订阅方式同样选择 **使用长连接接收回调** 并保存。 5. 在事件配置页面添加如下四个事件并保存： * 机器人进群 * 机器人被移出群 * 消息已读 * 接收消息 ### 配置权限 在 **权限管理 > 开通权限** 中，单击 **批量导入/导出权限**，粘贴以下 JSON 一键导入所需权限，确认后 **申请开通**： ```json theme={null} { "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. 访问 [企业微信管理后台](https://work.weixin.qq.com/)，在左侧导航栏单击 **安全与管理 > 管理工具**，单击 **创建机器人**，然后单击 **手动创建**。 2. 配置机器人可见范围。 3. 下拉到页面底部单击 **API 模式创建**，连接方式选择 **使用长连接**。 ### 获取凭据 在配置方法的 **Secret** 区域单击 **点击获取**，记录 **Bot ID** 和 **Secret**，分别对应 API 的 `bot_id` 与 `secret`。 ## 个人微信接入 个人微信仅支持 **扫码绑定**，无需在开放平台创建应用，也无需配置任何直连凭据。创建 Channel 时 `channel_type` 传 `wechat`，直接按上文 [扫码绑定流程（推荐）](#扫码绑定流程推荐) 完成授权即可。 ## 相关