adolf/extensions/qqbot/skills/qqbot-channel/references/api_references.md

QQ 频道 API 完整参考

本文档包含 QQ 开放平台频道相关所有接口的详细参数说明、返回值结构和枚举值定义。

通过 qqbot_channel_api 工具代理请求，工具自动处理鉴权。

调用安全规则

• POST、PUT、PATCH 和 DELETE 会修改真实 QQ 资源。调用前确认用户明确授权了该操作。
• 删除接口不可逆。删除前先用读取接口确认目标 ID、名称和范围，并把将要删除的对象复述给用户；qqbot_channel_api 要求 confirmed: true 才会执行 DELETE。
• 批量删除 sentinel 必须二次确认并额外传 bulkConfirmed: true；不要把模糊表达自动扩展成“删除全部”。
• 删除端点不作为普通 agent 速查路径列出。需要删除时，先用读取接口确认对象，再通过受确认保护的删除流程执行。
• 成员资料和头像 URL 只用于当前请求；除非用户明确要求查看头像/图标，不要内联展示或转发这些图片 URL。

---

📌 通用说明

基础 URL

https://api.sgroup.qq.com

鉴权（自动处理）

工具自动填充以下请求头，无需手动设置：

Authorization: QQBot {access_token}
Content-Type: application/json

错误返回格式

{
  "message": "错误描述",
  "code": 错误码
}

---

📦 返回值类型定义

Guild（频道）

interface Guild {
  id: string; // 频道 ID
  name: string; // 频道名称
  icon: string; // 频道头像 URL
  owner_id: string; // 频道拥有者 ID
  owner: boolean; // 机器人是否为频道拥有者
  joined_at: string; // 机器人加入时间（ISO 8601）
  member_count: number; // 频道成员数
  max_members: number; // 频道最大成员数
  description: string; // 频道描述
}

Channel（子频道）

interface Channel {
  id: string; // 子频道 ID
  guild_id: string; // 所属频道 ID
  name: string; // 子频道名称
  type: number; // 子频道类型（见枚举）
  position: number; // 排序位置
  parent_id: string; // 所属分组 ID
  owner_id: string; // 创建者 ID
  sub_type: number; // 子类型（见枚举）
  private_type?: number; // 私密类型（见枚举）
  speak_permission?: number; // 发言权限（见枚举）
  application_id?: string; // 应用子频道 AppID
}

User（用户）

interface User {
  id: string; // 用户 ID
  username: string; // 用户名
  avatar: string; // 头像 URL
  bot: boolean; // 是否为机器人
  union_openid?: string; // 特殊关联应用的 openid
  union_user_account?: string; // 特殊关联应用的用户信息
}

Member（成员）

interface Member {
  user: User; // 用户基本信息
  nick: string; // 在频道中的昵称
  roles: string[]; // 身份组 ID 列表
  joined_at: string; // 加入频道时间（ISO 8601）
  deaf?: boolean; // 是否被禁言
  mute?: boolean; // 是否被闭麦
  pending?: boolean; // 是否待审核
}

APIPermission（API 权限）

interface APIPermission {
  path: string; // 接口路径
  method: string; // 请求方法
  desc: string; // 接口描述
  auth_status: number; // 授权状态：0=未授权, 1=已授权
}

AnnouncesResult（公告结果）

interface AnnouncesResult {
  guild_id: string;
  channel_id: string;
  message_id: string;
  announces_type: number;
  recommend_channels: RecommendChannel[];
}

interface RecommendChannel {
  channel_id: string; // 推荐的子频道 ID
  introduce: string; // 推荐语
}

ThreadDetail（帖子详情）

interface ThreadDetail {
  thread: {
    guild_id: string;
    channel_id: string;
    author_id: string;
    thread_info: {
      thread_id: string;
      title: string;
      content: string;
      date_time: string;
    };
  };
}

ThreadListResult（帖子列表）

interface ThreadListResult {
  threads: Array<{
    guild_id: string;
    channel_id: string;
    author_id: string;
    thread_info: {
      thread_id: string;
      title: string;
      content: string;
      date_time: string;
    };
  }>;
  is_finish: number; // 1=已到底, 0=还有更多
}

Schedule（日程）

interface Schedule {
  id?: string;
  name: string;
  start_timestamp: string; // 毫秒级时间戳
  end_timestamp: string;
  jump_channel_id?: string;
  remind_type?: string;
  creator?: {
    user: { id: string; username: string; bot: boolean };
    nick: string;
    joined_at: string;
  };
}

---

📋 枚举值定义

子频道类型（Channel type）

值	名称	说明
0	文字子频道	普通文字聊天
2	语音子频道	语音聊天
4	子频道分组	组织子频道的分组（position ≥ 2）
10005	直播子频道	直播功能
10006	应用子频道	需 application_id
10007	论坛子频道	论坛功能

子频道子类型（Channel sub_type）

值	名称
0	闲聊
1	公告
2	攻略
3	开黑

子频道私密类型（Channel private_type）

值	说明
0	公开子频道
1	管理员和指定成员可见
2	仅管理员可见

子频道发言权限（Channel speak_permission）

值	说明
0	无效（仅创建公告子频道时有效，此时为只读）
1	所有人可发言
2	仅管理员和指定成员可发言

公告类型（announces_type）

值	说明
0	成员公告
1	欢迎公告

帖子格式（format）

值	格式
1	纯文本
2	HTML
3	Markdown（默认）
4	JSON（RichText）

日程提醒类型（remind_type）

值	说明
"0"	不提醒
"1"	开始时提醒
"2"	开始前 5 分钟
"3"	开始前 15 分钟
"4"	开始前 30 分钟
"5"	开始前 60 分钟

API 权限授权状态（auth_status）

值	说明
0	未授权
1	已授权

---

📖 各接口详细说明

GET /users/@me/guilds — 获取频道列表

查询参数:

参数	类型	必填	说明
before	string	否	读此 guild id 之前的数据
after	string	否	读此 guild id 之后的数据（与 before 同时设置时无效）
limit	string	否	每次拉取条数，默认 100，最大 100

返回: Guild[]

调用示例:

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

---

GET /guilds/{guild_id}/api_permission — 获取频道 API 权限

返回: { apis: APIPermission[] }

调用示例:

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

---

GET /guilds/{guild_id}/channels — 获取子频道列表

返回: Channel[]

调用示例:

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

---

GET /channels/{channel_id} — 获取子频道详情

返回: Channel

---

POST /guilds/{guild_id}/channels — 创建子频道

⚠️ 仅私域机器人可用，需管理频道权限

请求体:

参数	类型	必填	说明
name	string	是	子频道名称
type	number	是	子频道类型
position	number	是	排序位置（type=4 时 ≥ 2）
sub_type	number	否	子类型
parent_id	string	否	所属分组 ID
private_type	number	否	私密类型
private_user_ids	string[]	否	私密成员列表（private_type=1 时有效）
speak_permission	number	否	发言权限
application_id	string	否	应用 AppID（type=10006 时需要）

返回: Channel

---

PATCH /channels/{channel_id} — 修改子频道

⚠️ 仅私域机器人可用

请求体（至少一个）:

参数	类型	说明
name	string	名称
position	number	排序位置
parent_id	string	分组 ID
private_type	number	私密类型
speak_permission	number	发言权限

返回: Channel

---

删除子频道（破坏性操作）

⚠️ 不可逆！仅私域机器人可用。调用前必须确认具体子频道 ID、子频道名称和用户删除意图，并传 confirmed: true；不要按模糊名称猜测删除目标。确认后使用子频道资源路径 /channels/{channel_id}。

---

GET /guilds/{guild_id}/members — 获取成员列表

仅私域机器人可用

查询参数:

参数	类型	说明
after	string	上次最后一个 user.id，首次填 "0"
limit	string	分页大小 1-400，默认 1

返回: Member[]

翻页：用最后一个 user.id 作为 after，直到返回空数组。可能返回重复成员，需按 user.id 去重。

---

GET /guilds/{guild_id}/members/{user_id} — 获取成员详情

返回: Member

---

GET /guilds/{guild_id}/roles/{role_id}/members — 获取身份组成员列表

仅私域机器人可用

查询参数:

参数	类型	说明
start_index	string	分页标识，首次填 "0"
limit	string	分页大小 1-400，默认 1

返回: { data: Member[], next: string }

翻页：用 next 作为 start_index，直到 data 为空。

---

GET /channels/{channel_id}/online_nums — 获取在线成员数

返回: { online_nums: number }

---

POST /guilds/{guild_id}/announces — 创建频道公告

请求体:

参数	类型	必填	说明
message_id	string	否	消息 ID（有值时创建消息公告，此时 channel_id 必填）
channel_id	string	否	子频道 ID
announces_type	number	否	0=成员公告，1=欢迎公告
recommend_channels	array	否	推荐子频道列表（最多 3 条，message_id 为空时生效）

两种公告类型会互相顶替

返回: AnnouncesResult

---

删除公告（破坏性操作）

调用前必须确认具体公告 ID 并传 confirmed: true，确认后使用公告资源路径 /guilds/{guild_id}/announces/{message_id}。批量删除全部公告只能在用户明确要求并再次确认后使用 /guilds/{guild_id}/announces/all，并且必须额外传 bulkConfirmed: true。

---

GET /channels/{channel_id}/threads — 获取帖子列表

仅私域机器人可用，channel_id 须为论坛子频道（type=10007）

返回: ThreadListResult

---

GET /channels/{channel_id}/threads/{thread_id} — 获取帖子详情

仅私域机器人可用

返回: ThreadDetail

---

PUT /channels/{channel_id}/threads — 发表帖子

仅私域机器人可用

请求体:

参数	类型	必填	说明
title	string	是	帖子标题
content	string	是	帖子内容
format	number	否	1=文本, 2=HTML, 3=Markdown（默认）, 4=JSON

返回: { task_id: string, create_time: string }

---

删除帖子（破坏性操作）

⚠️ 不可逆！仅私域机器人可用。调用前必须确认具体帖子 ID、帖子标题/作者和用户删除意图，并传 confirmed: true。确认后使用帖子资源路径 /channels/{channel_id}/threads/{thread_id}。

---

POST /channels/{channel_id}/threads/{thread_id}/comment — 发表评论

仅私域机器人可用

请求体:

参数	类型	必填	说明
thread_author	string	是	帖子作者 ID
content	string	是	评论内容
thread_create_time	string	否	帖子创建时间
image	string	否	图片链接

返回: { task_id: string, create_time: number }

---

POST /channels/{channel_id}/schedules — 创建日程

需要管理频道权限。单管理员/天限 10 次，单频道/天限 100 次。

请求体:

{
  "schedule": {
    "name": "日程名称",
    "start_timestamp": "毫秒时间戳",
    "end_timestamp": "毫秒时间戳",
    "jump_channel_id": "0",
    "remind_type": "0"
  }
}

参数	类型	必填	说明
schedule.name	string	是	日程名称
schedule.start_timestamp	string	是	开始时间（毫秒）
schedule.end_timestamp	string	是	结束时间（毫秒）
schedule.jump_channel_id	string	否	跳转子频道 ID，默认 "0"
schedule.remind_type	string	否	提醒类型，默认 "0"

返回: Schedule

---

PATCH /channels/{channel_id}/schedules/{schedule_id} — 修改日程

需要管理频道权限

请求体：同创建日程

返回: Schedule

---

删除日程（破坏性操作）

⚠️ 不可逆！需要管理频道权限。调用前必须确认具体日程 ID、日程名称/时间和用户删除意图，并传 confirmed: true。确认后使用日程资源路径 /channels/{channel_id}/schedules/{schedule_id}。