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

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

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

​

路由

/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}

​

创建通道

​

飞书

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

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）。

若 kind 不是支持的值，请求将以 400 CHANNEL_KIND_UNSUPPORTED 失败。

​

QQ 扫码绑定

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

curl -X POST http://127.0.0.1:8088/api/agents/1/channels/qq/qrcode/generate \
  -H 'Authorization: Bearer <token>'

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 写入渠道。

​

测试渠道

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

curl -X POST http://127.0.0.1:8088/api/agents/1/channels/5/test \
  -H 'Authorization: Bearer <token>'

响应：

{"ok": true}

或失败时：

{"ok": false, "error": "无法连接到 Telegram Bot API"}

​

更新渠道

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 中需要修改的字段子集。

​

删除渠道

curl -X DELETE http://127.0.0.1:8088/api/agents/1/channels/5 \
  -H 'Authorization: Bearer <token>'

成功时返回 204 No Content。

​

探测配置（不保存）

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

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"}}'

响应：

{"ok": true}

或失败时：

{"ok": false, "reason": "invalid_token", "detail": "Telegram 拒绝了提交的令牌"}