• 简体中文

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

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

      路由

      /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}
      POST/agents/{aid}/channels/dingtalk/qrcode/generate发起钉钉扫码应用授权
      POST/agents/{aid}/channels/dingtalk/qrcode/poll轮询钉钉授权结果；成功时创建并启用通道

      创建通道

      飞书

      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_modeinvoke、stream页面：stream；API 兜底：invokeinvoke 对应页面中的仅终稿，聊天应用只收到完成回复；stream 对应实时进度。QQ 私聊忽略此键。
      c2c_streamingbool保存时为 true仅 QQ 私聊。true 走官方 stream_messages；false 只发一条静态 markdown。旧键 streaming / response_mode 对 C2C 无效。
      show_thinkingboolfalse显示思考过程。仅终稿模式下不可用。
      show_tool_hintsboolfalse显示工具提示。仅终稿模式下不可用。QQ 私聊中额外工具气泡会占用被动回复配额。

      支持的类型

      kind平台
      weixin微信
      qqQQ
      wecom企业微信
      feishu飞书
      yuanbao腾讯元宝
      dingtalk钉钉
      telegramTelegram
      xiaoyi华为小艺
      mqttMQTT

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

      钉钉扫码注册

      钉钉支持通过二维码授权直接创建并启用通道。先生成注册会话，把 qrcode_url 展示给用户，再用 registration_id 轮询，直到返回 success、waiting、expired 或 failed。

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

      响应：

      {
  "registration_id": "...",
  "qrcode_url": "https://...",
  "user_code": "ABCD-EFGH",
  "expires_in": 600,
  "interval": 5
}
      curl -X POST http://127.0.0.1:8088/api/agents/1/channels/dingtalk/qrcode/poll \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"registration_id": "..."}'

      成功时，Octop 返回 {"status":"success","channel_id":"..."}，并保存一个已启用的钉钉通道，默认使用实时进度模式且不显示思考过程或工具提示。

      测试渠道

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

      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 拒绝了提交的令牌"}