qqbot-channel

QQ 频道 API 请求指南

本 Skill 仅处理 QQ 频道（Guild/Channel）操作。 频道 ID 为纯数字，API 路径为 /guilds/... 和 /channels/...。

qqbot_platform_api 是 QQ 开放平台统一 HTTP API 网关，自动填充鉴权 Token。你只需要指定 HTTP 方法、API 路径、请求体和查询参数，即可调用频道相关接口。

---

🔀 适用范围（必读）

QQ 频道是类似 Discord 的社区产品，层级结构为 频道（Guild） → 子频道（Channel）：

层级	中文名	英文	API 路径	ID 格式
顶层	频道	Guild	/guilds/{guild_id}	纯数字（如 123456）
次级	子频道	Channel	/channels/{channel_id}	纯数字（如 789012）

核心特征：

• 频道内可以创建多个子频道（文字、语音、论坛、直播等）
• 支持发帖、公告、日程等功能
• 频道成员通过 /guilds/{guild_id}/members 管理
• ID 为纯数字格式，API 路径以 /guilds/ 或 /channels/ 开头

触发关键词：频道、子频道、guild、channel、帖子、日程、公告、论坛、频道成员

📚 详细参考文档

每个接口的完整参数说明、返回值结构和枚举值定义：

• references/api_references.md

---

🔧 工具参数

参数	类型	必填	说明
method	string	是	HTTP 方法：GET、POST、PUT、PATCH、DELETE
path	string	是	API 路径（不含域名），如 /guilds/{guild_id}/channels，需将占位符替换为实际值
body	object	否	请求体 JSON（POST/PUT/PATCH 使用）
query	object	否	URL 查询参数键值对，值为字符串类型

基础 URL：https://api.sgroup.qq.com，鉴权头 Authorization: QQBot {token} 由工具自动填充。

---

⭐ 接口速查

频道（Guild）

操作	方法	路径	参数说明
获取频道列表	GET	/users/@me/guilds	query：before、after、limit（最大 100）
获取频道 API 权限	GET	/guilds/{guild_id}/api_permission	—

子频道（Channel）

操作	方法	路径	参数说明
获取子频道列表	GET	/guilds/{guild_id}/channels	—
获取子频道详情	GET	/channels/{channel_id}	—
创建子频道	POST	/guilds/{guild_id}/channels	body：name*、type*、position*、sub_type、parent_id、private_type、private_user_ids、speak_permission、application_id
修改子频道	PATCH	/channels/{channel_id}	body：name、position、parent_id、private_type、speak_permission（至少一个）
删除子频道	DELETE	/channels/{channel_id}	⚠️ 不可逆

子频道类型（type）：0=文字、2=语音、4=分组（position≥2）、10005=直播、10006=应用、10007=论坛

成员（Member）

操作	方法	路径	参数说明
获取成员列表	GET	/guilds/{guild_id}/members	query：after（首次填 0）、limit（1-400）
获取成员详情	GET	/guilds/{guild_id}/members/{user_id}	—
获取身份组成员列表	GET	/guilds/{guild_id}/roles/{role_id}/members	query：start_index（首次填 0）、limit（1-400）
获取在线成员数	GET	/channels/{channel_id}/online_nums	—

公告（Announces）

操作	方法	路径	参数说明
创建公告	POST	/guilds/{guild_id}/announces	body：message_id、channel_id、announces_type（0=成员、1=欢迎）、recommend_channels（最多 3 条）
删除公告	DELETE	/guilds/{guild_id}/announces/{message_id}	将 message_id 设为 all 可删除所有

论坛（Forum）— 仅私域机器人

操作	方法	路径	参数说明
获取帖子列表	GET	/channels/{channel_id}/threads	—
获取帖子详情	GET	/channels/{channel_id}/threads/{thread_id}	—
发表帖子	PUT	/channels/{channel_id}/threads	body：title*、content*、format（1=文本、2=HTML、3=Markdown、4=JSON，默认 3）
删除帖子	DELETE	/channels/{channel_id}/threads/{thread_id}	⚠️ 不可逆
发表评论	POST	/channels/{channel_id}/threads/{thread_id}/comment	body：thread_author*、content*、thread_create_time、image

日程（Schedule）

操作	方法	路径	参数说明
创建日程	POST	/channels/{channel_id}/schedules	body：{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }
修改日程	PATCH	/channels/{channel_id}/schedules/{schedule_id}	body：{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }
删除日程	DELETE	/channels/{channel_id}/schedules/{schedule_id}	⚠️ 不可逆

提醒类型（remind_type）："0"=不提醒、"1"=开始时、"2"=5 分钟前、"3"=15 分钟前、"4"=30 分钟前、"5"=60 分钟前

* 表示必填参数

---

💡 调用示例

获取频道列表

{
  "method": "GET",
  "path": "/users/@me/guilds",
  "query": { "limit": "100" }
}

获取子频道列表

{
  "method": "GET",
  "path": "/guilds/123456/channels"
}

创建子频道

{
  "method": "POST",
  "path": "/guilds/123456/channels",
  "body": {
    "name": "新频道",
    "type": 0,
    "position": 1,
    "sub_type": 0
  }
}

获取成员列表（分页）

{
  "method": "GET",
  "path": "/guilds/123456/members",
  "query": { "after": "0", "limit": "100" }
}

发表论坛帖子

{
  "method": "PUT",
  "path": "/channels/789012/threads",
  "body": {
    "title": "公告标题",
    "content": "# 标题\n\n公告内容",
    "format": 3
  }
}

创建日程

{
  "method": "POST",
  "path": "/channels/456789/schedules",
  "body": {
    "schedule": {
      "name": "周会",
      "start_timestamp": "1770733800000",
      "end_timestamp": "1770737400000",
      "remind_type": "2"
    }
  }
}

创建推荐子频道公告

{
  "method": "POST",
  "path": "/guilds/123456/announces",
  "body": {
    "announces_type": 0,
    "recommend_channels": [
      { "channel_id": "789012", "introduce": "欢迎来到攻略频道" }
    ]
  }
}

删除所有公告

{
  "method": "DELETE",
  "path": "/guilds/123456/announces/all"
}

---

🔄 常用操作流程

获取频道和子频道信息

1. GET /users/@me/guilds → 获取频道列表，拿到 guild_id
2. GET /guilds/{guild_id}/channels → 获取子频道列表，拿到 channel_id
3. GET /channels/{channel_id} → 获取子频道详情

论坛发帖 + 评论

1. GET /guilds/{guild_id}/channels → 找到论坛子频道（type=10007）
2. PUT /channels/{channel_id}/threads → 发表帖子
3. GET /channels/{channel_id}/threads → 获取帖子列表
4. GET /channels/{channel_id}/threads/{thread_id} → 获取帖子详情（含 author_id）
5. POST /channels/{channel_id}/threads/{thread_id}/comment → 发表评论

成员管理

1. GET /users/@me/guilds → 获取 guild_id
2. GET /guilds/{guild_id}/members?after=0&limit=100 → 获取成员列表
   翻页：用上次最后一个 user.id 作为 after，直到返回空数组
3. GET /guilds/{guild_id}/members/{user_id} → 获取指定成员详情

展示成员头像

成员详情返回的 user.avatar 是头像 URL，必须使用 Markdown 图片语法展示，让用户直接看到头像图片，而非纯文本链接：

成员信息：
· 昵称：{nick}
· 头像：
![头像]({user.avatar})

禁止将头像 URL 作为纯文本或超链接展示（如 查看头像），必须用 ![描述](URL) 语法内联显示。频道的 icon 字段同理。

---

🚨 错误码处理

错误码	说明	解决方案
401	Token 鉴权失败	检查 AppID 和 ClientSecret 配置
11241	频道 API 无权限	前往 QQ 开放平台申请权限，或调用 GET /guilds/{guild_id}/api_permission 查看可用权限
11242	仅私域机器人可用	需在 QQ 开放平台将机器人切换为私域模式
11243	需要管理频道权限	确保机器人拥有管理权限
11281	日程频率限制	单管理员/天限 10 次，单频道/天限 100 次
304023	推荐子频道超限	推荐子频道最多 3 条

---

⚠️ 注意事项

1. 适用范围：本 Skill 仅处理 QQ 频道（Guild/Channel）操作，API 路径以 /guilds/ 或 /channels/ 开头，ID 为纯数字
2. 路径中的占位符（如 {guild_id}、{channel_id}）必须替换为实际的纯数字 ID
3. query 参数的值必须为字符串类型，如 { "limit": "100" } 而非 { "limit": 100 }
4. 成员列表翻页时可能返回重复成员，需按 user.id 去重
5. 公告的两种类型（消息公告和推荐子频道公告）会互相顶替
6. 日程的时间戳为毫秒级字符串
7. 删除操作不可逆，请谨慎使用
8. 论坛操作仅私域机器人可用
9. 子频道分组（type=4）的 position 必须 >= 2
10. 日程操作有频率限制：单个管理员每天 10 次，单个频道每天 100 次
11. 头像/图标展示：成员 user.avatar 和频道 icon 等图片 URL 必须使用 Markdown 图片语法 ![描述](URL) 展示，禁止作为纯文本或超链接展示