> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 通道 API：在 Octop 中将专家连接到消息平台

> 使用 Octop 的 /api/agents/{agent_id}/channels 端点，将专家连接到飞书、企业微信、钉钉、Telegram 等消息平台。

将专家连接到即时通信平台，以便它们可以发送和接收消息。

## 路由

```text theme={null}
/api/agents/{agent_id}/channels
```

## 端点

| 方法 | 路径 | 描述 |
| - | - | - |
| GET | `/agents/{aid}/channels` | 列出专家的渠道 |
| POST | `/agents/{aid}/channels` | 添加新渠道 |
| GET | `/agents/{aid}/channels/{cid}` | 获取渠道详情 |
| PATCH | `/agents/{aid}/channels/{cid}` | 更新渠道配置 |
| DELETE | `/agents/{aid}/channels/{cid}` | 删除渠道 |
| POST | `/agents/{aid}/channels/{cid}/test` | 测试渠道连接 |
| POST | `/agents/{aid}/channels/qq/qrcode/generate` | 发起 QQ 扫码绑定，返回 `qrcode_url` / `qrcode_token` |
| POST | `/agents/{aid}/channels/qq/qrcode/poll` | 轮询 QQ 扫码结果；请求体 `{qrcode_token}` |

## 创建通道

### 飞书

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/1/channels \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "feishu",
    "name": "团队飞书机器人",
    "config": {"app_id": "cli_xxx", "app_secret": "yyy"}
  }'
```

### Telegram

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/1/channels \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "telegram",
    "name": "Telegram 机器人",
    "config": {"token": "your-bot-token"}
  }'
```

两种情况成功后都返回 `201 Created`。

在 `config` 中设置展示选项：

| 字段 | 取值 | 默认 | 含义 |
| - | - | - | - |
| `response_mode` | `invoke`、`stream` | `invoke` | `invoke` 对应页面中的**仅终稿**，聊天应用只收到完成回复；`stream` 对应**实时进度**。QQ 私聊忽略此键。 |
| `c2c_streaming` | bool | 保存时为 `true` | 仅 QQ 私聊。`true` 走官方 `stream_messages`；`false` 只发一条静态 markdown。旧键 `streaming` / `response_mode` 对 C2C 无效。 |
| `show_thinking` | bool | `false` | 显示思考过程。仅终稿模式下不可用。 |
| `show_tool_hints` | bool | `false` | 显示工具提示。仅终稿模式下不可用。QQ 私聊中额外工具气泡会占用被动回复配额。 |

### 支持的类型

| `kind` | 平台 |
| - | - |
| `weixin` | 微信 |
| `qq` | QQ |
| `wecom` | 企业微信 |
| `feishu` | 飞书 |
| `yuanbao` | 腾讯元宝 |
| `dingtalk` | 钉钉 |
| `telegram` | Telegram |
| `xiaoyi` | 华为小艺 |
| `mqtt` | MQTT |

对于 `kind: "qq"`，`config` 通常包含 `app_id`、`secret`（或 `client_secret`），可选的 `c2c_streaming`（页面保存时默认为 `true`），以及可选的 `group_context`（`visibility`、`activation`、`history`、`history_limit`）。

> [!WARNING]
>
> 若 `kind` 不是支持的值，请求将以 `400 CHANNEL_KIND_UNSUPPORTED` 失败。

## QQ 扫码绑定

先生成二维码会话，再轮询直到手机 QQ 扫码成功：

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/1/channels/qq/qrcode/generate \
  -H 'Authorization: Bearer <token>'
```

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/1/channels/qq/qrcode/poll \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"qrcode_token": "..."}'
```

成功时 poll 响应包含 `app_id` 与 `secret`，可用 `POST` / `PATCH` 写入渠道。

## 测试渠道

验证已保存的渠道是否可以成功连接：

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/1/channels/5/test \
  -H 'Authorization: Bearer <token>'
```

响应：

```json theme={null}
{"ok": true}
```

或失败时：

```json theme={null}
{"ok": false, "error": "无法连接到 Telegram Bot API"}
```

## 更新渠道

```bash theme={null}
curl -X PATCH http://127.0.0.1:8088/api/agents/1/channels/5 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "已重命名的渠道"}'
```

可以只传递 `name` 或 `config` 中需要修改的字段子集。

## 删除渠道

```bash theme={null}
curl -X DELETE http://127.0.0.1:8088/api/agents/1/channels/5 \
  -H 'Authorization: Bearer <token>'
```

成功时返回 `204 No Content`。

## 探测配置（不保存）

在正式持久化之前验证渠道配置：

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/1/channels/probe \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"kind": "telegram", "config": {"token": "your-bot-token"}}'
```

响应：

```json theme={null}
{"ok": true}
```

或失败时：

```json theme={null}
{"ok": false, "reason": "invalid_token", "detail": "Telegram 拒绝了提交的令牌"}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.