qqbot-channel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QQ 频道 API 请求指导

QQ Channel API Request Guide

qqbot_channel_api

是一个 QQ 开放平台 HTTP 代理工具，自动填充鉴权 Token。你只需要指定 HTTP 方法、API 路径、请求体和查询参数。

qqbot_channel_api

is an HTTP proxy tool for the QQ Open Platform, which automatically fills in the authentication Token. You only need to specify the HTTP method, API path, request body and query parameters.

📚 详细参考文档

📚 Detailed Reference Documentation

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

```
references/api_references.md
```

Complete parameter descriptions, return value structures and enum value definitions for each interface:

```
references/api_references.md
```

🔧 工具参数

🔧 Tool Parameters

参数	类型	必填	说明
`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}
由工具自动填充。

Parameter	Type	Required	Description
`method`	string	Yes	HTTP methods: `GET` , `POST` , `PUT` , `PATCH` , `DELETE`
`path`	string	Yes	API path (excluding domain name), e.g. `/guilds/{guild_id}/channels` , placeholders need to be replaced with actual values
`body`	object	No	Request body JSON (used for POST/PUT/PATCH)
`query`	object	No	URL query parameter key-value pairs, values are string type

Base URL:
https://api.sgroup.qq.com
, the authentication header
Authorization: QQBot {token}
is automatically filled by the tool.

⭐ 接口速查

⭐ Quick API Reference

频道（Guild）

Guild

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

Operation	Method	Path	Parameter Description
Get guild list	`GET`	`/users/@me/guilds`	query: `before` , `after` , `limit` (max 100)
Get guild API permissions	`GET`	`/guilds/{guild_id}/api_permission`	—

子频道（Channel）

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

=文字,

=语音,

=分组(position≥2),

=直播,

=应用,

=论坛

Operation	Method	Path	Parameter Description
Get sub-channel list	`GET`	`/guilds/{guild_id}/channels`	—
Get sub-channel details	`GET`	`/channels/{channel_id}`	—
Create sub-channel	`POST`	`/guilds/{guild_id}/channels`	body: `name` , `type` , `position` *, `sub_type` , `parent_id` , `private_type` , `private_user_ids` , `speak_permission` , `application_id`
Modify sub-channel	`PATCH`	`/channels/{channel_id}`	body: `name` , `position` , `parent_id` , `private_type` , `speak_permission` (at least one)
Delete sub-channel	`DELETE`	`/channels/{channel_id}`	⚠️ Irreversible

Sub-channel type (type):

=text,

=voice,

=category(position≥2),

=live,

=application,

=forum

成员（Member）

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`	—

Operation	Method	Path	Parameter Description
Get member list	`GET`	`/guilds/{guild_id}/members`	query: `after` (fill 0 for first request), `limit` (1-400)
Get member details	`GET`	`/guilds/{guild_id}/members/{user_id}`	—
Get role member list	`GET`	`/guilds/{guild_id}/roles/{role_id}/members`	query: `start_index` (fill 0 for first request), `limit` (1-400)
Get online member count	`GET`	`/channels/{channel_id}/online_nums`	—

公告（Announces）

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` 删除所有

Operation	Method	Path	Parameter Description
Create announcement	`POST`	`/guilds/{guild_id}/announces`	body: `message_id` , `channel_id` , `announces_type` (0=member,1=welcome), `recommend_channels` (max 3)
Delete announcement	`DELETE`	`/guilds/{guild_id}/announces/{message_id}`	set `message_id` to `all` to delete all

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

Forum — For private domain bots only

操作	方法	路径	参数说明
获取帖子列表	`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`

Operation	Method	Path	Parameter Description
Get post list	`GET`	`/channels/{channel_id}/threads`	—
Get post details	`GET`	`/channels/{channel_id}/threads/{thread_id}`	—
Publish post	`PUT`	`/channels/{channel_id}/threads`	body: `title` , `content` , `format` (1=text,2=HTML,3=Markdown,4=JSON, default 3)
Delete post	`DELETE`	`/channels/{channel_id}/threads/{thread_id}`	⚠️ Irreversible
Publish comment	`POST`	`/channels/{channel_id}/threads/{thread_id}/comment`	body: `thread_author` , `content` , `thread_create_time` , `image`

日程（Schedule）

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}`	⚠️ 不可逆

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分钟前

*
表示必填参数

Operation Method Path Parameter Description

Create schedule

Operation	Method	Path	Parameter Description
Create schedule	`POST`	`/channels/{channel_id}/schedules`	body: `{ schedule: { name, start_timestamp, end_timestamp*, jump_channel_id, remind_type } }`
Modify schedule	`PATCH`	`/channels/{channel_id}/schedules/{schedule_id}`	body: `{ schedule: { name, start_timestamp, end_timestamp*, jump_channel_id, remind_type } }`
Delete schedule	`DELETE`	`/channels/{channel_id}/schedules/{schedule_id}`	⚠️ Irreversible

POST

/channels/{channel_id}/schedules

body:

{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }

Modify schedule

PATCH

/channels/{channel_id}/schedules/{schedule_id}

body:

{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }

Delete schedule

DELETE

/channels/{channel_id}/schedules/{schedule_id}

⚠️ Irreversible

Remind type (remind_type):

"0"

=no reminder,

"1"

=when starting,

"2"

=5 minutes in advance,

"3"

=15 minutes in advance,

"4"

=30 minutes in advance,

"5"

=60 minutes in advance

*
indicates required parameters

💡 调用示例

💡 Call Examples

获取频道列表

Get guild list

json

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

json

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

获取子频道列表

Get sub-channel list

json

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

json

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

创建子频道

Create sub-channel

json

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

json

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

获取成员列表（分页）

Get member list (pagination)

json

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

json

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

发表论坛帖子

Publish forum post

json

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

json

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

创建日程

Create schedule

json

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

json

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

创建推荐子频道公告

Create recommended sub-channel announcement

json

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

json

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

删除所有公告

Delete all announcements

json

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

json

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

🔄 常用操作流程

🔄 Common Operation Processes

获取频道和子频道信息

Get guild and sub-channel information

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

1. GET /users/@me/guilds → Get guild list, get guild_id
2. GET /guilds/{guild_id}/channels → Get sub-channel list, get channel_id
3. GET /channels/{channel_id} → Get sub-channel details

论坛发帖 + 评论

Forum posting + commenting

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 /guilds/{guild_id}/channels → Find forum sub-channel (type=10007)
2. PUT /channels/{channel_id}/threads → Publish post
3. GET /channels/{channel_id}/threads → Get post list
4. GET /channels/{channel_id}/threads/{thread_id} → Get post details (including author_id)
5. POST /channels/{channel_id}/threads/{thread_id}/comment → Publish comment

成员管理

Member management

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} → 获取指定成员详情

1. GET /users/@me/guilds → Get guild_id
2. GET /guilds/{guild_id}/members?after=0&limit=100 → Get member list
   Pagination: Use the last user.id of the previous request as after, until an empty array is returned
3. GET /guilds/{guild_id}/members/{user_id} → Get specified member details

展示成员头像

Display member avatar

成员详情返回的

user.avatar

是头像 URL，必须使用 Markdown 图片语法展示，让用户直接看到头像图片，而非纯文本链接：

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

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

The

user.avatar

returned in member details is the avatar URL, must be displayed using Markdown image syntax, so that users can see the avatar image directly instead of plain text links:

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

It is forbidden to display the avatar URL as plain text or hyperlink (e.g.
查看头像
), you must use the
![description](URL)
syntax to display it inline. The same applies to the
icon
field of guilds.

🚨 错误码处理

🚨 Error Code Handling

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

Error Code	Description	Solution
401	Token authentication failed	Check AppID and ClientSecret configuration
11241	No guild API permission	Go to QQ Open Platform to apply for permissions, or call `GET /guilds/{guild_id}/api_permission` to view available permissions
11242	Only available for private domain bots	You need to switch the bot to private domain mode in QQ Open Platform
11243	Guild management permission required	Ensure the bot has management permissions
11281	Schedule frequency limit	10 times per administrator/day, 100 times per channel/day
304023	Recommended sub-channels exceed limit	Maximum 3 recommended sub-channels

⚠️ 注意事项

⚠️ Notes

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

Placeholders in the path (e.g.
```
{guild_id}
```
,
```
{channel_id}
```
) must be replaced with actual values
The values of query parameters must be string type, e.g.
```
{ "limit": "100" }
```
instead of
```
{ "limit": 100 }
```
Duplicate members may be returned when paging the member list, you need to deduplicate by
```
user.id
```
The two types of announcements (message announcements and recommended sub-channel announcements) will replace each other
The timestamp of schedule is a millisecond-level string
Delete operations are irreversible, please use with caution
Forum operations are only available for private domain bots
The
```
position
```
of sub-channel category (type=4) must be >= 2
Schedule operations have frequency limits: 10 times per administrator per day, 100 times per channel per day
Avatar/icon display: Image URLs such as member
```
user.avatar
```
and guild
```
icon
```
must be displayed using Markdown image syntax
```
![description](URL)
```
, it is forbidden to display them as plain text or hyperlinks