Back to Details

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}
由工具自动填充。
ParameterTypeRequiredDescription
method
stringYesHTTP methods: 
GET
, 
POST
, 
PUT
, 
PATCH
, 
DELETE
path
stringYesAPI path (excluding domain name), e.g. 
/guilds/{guild_id}/channels
, placeholders need to be replaced with actual values
body
objectNoRequest body JSON (used for POST/PUT/PATCH)
query
objectNoURL 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
—
OperationMethodPathParameter 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）：
0
=文字, 
2
=语音, 
4
=分组(position≥2), 
10005
=直播, 
10006
=应用, 
10007
=论坛
OperationMethodPathParameter 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): 
0
=text, 
2
=voice, 
4
=category(position≥2), 
10005
=live, 
10006
=application, 
10007
=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
—
OperationMethodPathParameter 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
删除所有
OperationMethodPathParameter 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
OperationMethodPathParameter 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}
⚠️ 不可逆
提醒类型（remind_type）：
"0"
=不提醒, 
"1"
=开始时, 
"2"
=5分钟前, 
"3"
=15分钟前, 
"4"
=30分钟前, 
"5"
=60分钟前
*
表示必填参数
OperationMethodPathParameter 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
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

错误码说明解决方案
401Token 鉴权失败检查 AppID 和 ClientSecret 配置
11241频道 API 无权限前往 QQ 开放平台申请权限，或调用 
GET /guilds/{guild_id}/api_permission
查看可用权限
11242仅私域机器人可用需在 QQ 开放平台将机器人切换为私域模式
11243需要管理频道权限确保机器人拥有管理权限
11281日程频率限制单管理员/天限 10 次，单频道/天限 100 次
304023推荐子频道超限推荐子频道最多 3 条
Error CodeDescriptionSolution
401Token authentication failedCheck AppID and ClientSecret configuration
11241No guild API permissionGo to QQ Open Platform to apply for permissions, or call 
GET /guilds/{guild_id}/api_permission
to view available permissions
11242Only available for private domain botsYou need to switch the bot to private domain mode in QQ Open Platform
11243Guild management permission requiredEnsure the bot has management permissions
11281Schedule frequency limit10 times per administrator/day, 100 times per channel/day
304023Recommended sub-channels exceed limitMaximum 3 recommended sub-channels

⚠️ 注意事项

⚠️ Notes

  1. 路径中的占位符（如 
    {guild_id}
    、
    {channel_id}
    ）必须替换为实际值
  2. query 参数的值必须为字符串类型，如 
    { "limit": "100" }
    而非 
    { "limit": 100 }
  3. 成员列表翻页时可能返回重复成员，需按 
    user.id
    去重
  4. 公告的两种类型（消息公告和推荐子频道公告）会互相顶替
  5. 日程的时间戳为毫秒级字符串
  6. 删除操作不可逆，请谨慎使用
  7. 论坛操作仅私域机器人可用
  8. 子频道分组（type=4）的 
    position
    必须 >= 2
  9. 日程操作有频率限制：单个管理员每天 10 次，单个频道每天 100 次
  10. 头像/图标展示：成员 
    user.avatar
    和频道 
    icon
    等图片 URL 必须使用 Markdown 图片语法 
    ![描述](URL)
    展示，禁止作为纯文本或超链接展示
  1. Placeholders in the path (e.g. 
    {guild_id}
    , 
    {channel_id}
    ) must be replaced with actual values
  2. The values of query parameters must be string type, e.g. 
    { "limit": "100" }
    instead of 
    { "limit": 100 }
  3. Duplicate members may be returned when paging the member list, you need to deduplicate by 
    user.id
  4. The two types of announcements (message announcements and recommended sub-channel announcements) will replace each other
  5. The timestamp of schedule is a millisecond-level string
  6. Delete operations are irreversible, please use with caution
  7. Forum operations are only available for private domain bots
  8. The 
    position
    of sub-channel category (type=4) must be >= 2
  9. Schedule operations have frequency limits: 10 times per administrator per day, 100 times per channel per day
  10. 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