> ## 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 平台的用户，介绍推荐的扫码绑定流程，以及各渠道如何创建应用/机器人、需要配置哪些权限、需要获取哪些凭据。
**现阶段推荐使用「扫码绑定」完成渠道授权，非必要不推荐直接配置凭据。**
钉钉、飞书、企业微信、个人微信均支持扫码绑定：创建 Channel 时可省略 `channel_config.credentials`，随后通过 QR Session 扫码授权即可完成绑定，无需在业务侧保存 App Secret 等敏感凭据，安全性更高、维护成本更低。
仅在扫码绑定无法满足需求（如无人值守的服务端自动化）时，才考虑下文各渠道的「直连凭据」方式。
## 扫码绑定流程（推荐）
扫码绑定适用于 `dingtalk`、`feishu`、`wecom`、`wechat` 全部渠道，步骤如下：
1. **创建 Channel**：调用 [创建 Channel](/zh/cloud-agents/api/forward/channels/create) 接口，传入 `name`、`channel_type`、`identity_id`、`template_id`，**省略 `channel_config.credentials`**。
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. **轮询授权状态**：按 `poll_interval_seconds` 调用 [获取 Channel QR Session](/zh/cloud-agents/api/forward/channels/get-qr-session) 轮询 `status`，直到状态变为 `confirmed`（其他状态：`waiting`、`scanned`、`expired`、`denied`、`error`）。
5. **完成绑定**：`status=confirmed` 后刷新 Channel 详情，`binding_status` 变为 `bound`，即可接收上行消息并自动回复。
二维码有效期较短，`expired` 或 `denied` 后可重新创建 QR Session 再次扫码。
## 直连凭据接入（按需）
若确需使用直连凭据，需在对应开放平台创建应用/机器人、配置权限并获取凭据，再通过 [创建 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`，直接按上文 [扫码绑定流程（推荐）](#扫码绑定流程推荐) 完成授权即可。
## 相关