This Skill only handles QQ Channel (Guild/Channel) operations. Channel IDs are pure numbers, and API paths are
/guilds/...and/channels/...。
qqbot_platform_api is the QQ Open Platform unified HTTP API gateway,automatically filling in the authentication token. You only need to specify the HTTP method, API path, request body, and query parameters to call channel-related interfaces.
🔀 Scope of application (required reading)
QQ Channel is a community product similar to Discord, with a hierarchy of Guild → Channel：
| Level | Chinese name | English | API path | ID format |
|---|---|---|---|---|
| Top level | Guild | Guild | /guilds/{guild_id} |
Pure number (e.g., 123456） |
| Secondary | Channel | Channel | /channels/{channel_id} |
Pure number (e.g., 789012） |
Core features：
- Multiple sub-channels (text, voice, forum, live streaming, etc.) can be created within a guild
- Supports posts, announcements, schedules, and other functions
- Guild members are managed via
/guilds/{guild_id}/membersmanagement - IDs are in pure numeric format, and API paths start with
/guilds/or/channels/starts with
Trigger keywords: channel, sub-channel, guild, channel, post, schedule, announcement, forum, channel member
📚 Detailed reference documentation
Complete parameter descriptions, return value structures, and enum value definitions for each interface:
references/api_references.md
🔧 Tool parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
method |
string | Yes | HTTP method:GET, POST, PUT, PATCH, DELETE |
path |
string | Yes | API path (excluding domain), 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 of string type |
Base URL:
https://api.sgroup.qq.com, authentication headerAuthorization: QQBot {token}is automatically filled in by the tool.
⭐ Interface quick reference
Guild
| 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
| Operation | Method | Path | Parameter description |
|---|---|---|---|
| Get channel list | GET |
/guilds/{guild_id}/channels |
— |
| Get channel details | GET |
/channels/{channel_id} |
— |
| Create channel | POST |
/guilds/{guild_id}/channels |
body: name*, type*, position*, sub_type, parent_id, private_type, private_user_ids, speak_permission, application_id |
| Modify channel | PATCH |
/channels/{channel_id} |
body: name, position, parent_id, private_type, speak_permission(at least one) |
| Delete channel | DELETE |
/channels/{channel_id} |
⚠️ Irreversible |
Channel type (type)：0=text, 2=voice, 4=group (position≥2), 10005=live, 10006=application, 10007=Forum
Members (Member)
| Operation | Method | Path | Parameter description |
|---|---|---|---|
| Get member list | GET |
/guilds/{guild_id}/members |
query: after(fill 0 for the first time), 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 the first time), limit(1-400) |
| Get online member count | GET |
/channels/{channel_id}/online_nums |
— |
Announcements (Announces)
| 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(maximum 3) |
| Delete announcement | DELETE |
/guilds/{guild_id}/announces/{message_id} |
message_id set to all delete all |
Forum — private-domain bots only
| 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 |
| Post comment | POST |
/channels/{channel_id}/threads/{thread_id}/comment |
body: thread_author*, content*, thread_create_time, image |
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 |
Reminder type (remind_type)："0"=no reminder, "1"=at start time, "2"=5 minutes before, "3"=15 minutes before, "4"=30 minutes before, "5"=60 minutes before
*indicates a required parameter
💡 Call examples
Get channel list
{
"method": "GET",
"path": "/users/@me/guilds",
"query": { "limit": "100" }
}
Get subchannel list
{
"method": "GET",
"path": "/guilds/123456/channels"
}
Create subchannel
{
"method": "POST",
"path": "/guilds/123456/channels",
"body": {
"name": "新频道",
"type": 0,
"position": 1,
"sub_type": 0
}
}
Get member list (paged)
{
"method": "GET",
"path": "/guilds/123456/members",
"query": { "after": "0", "limit": "100" }
}
Publish forum post
{
"method": "PUT",
"path": "/channels/789012/threads",
"body": {
"title": "公告标题",
"content": "# 标题\n\n公告内容",
"format": 3
}
}
Create schedule
{
"method": "POST",
"path": "/channels/456789/schedules",
"body": {
"schedule": {
"name": "周会",
"start_timestamp": "1770733800000",
"end_timestamp": "1770737400000",
"remind_type": "2"
}
}
}
Create recommended subchannel announcement
{
"method": "POST",
"path": "/guilds/123456/announces",
"body": {
"announces_type": 0,
"recommend_channels": [
{ "channel_id": "789012", "introduce": "欢迎来到攻略频道" }
]
}
}
Delete all announcements
{
"method": "DELETE",
"path": "/guilds/123456/announces/all"
}
🔄 Common operation flow
Get channel and subchannel information
1. GET /users/@me/guilds → 获取频道列表，拿到 guild_id
2. GET /guilds/{guild_id}/channels → 获取子频道列表，拿到 channel_id
3. GET /channels/{channel_id} → 获取子频道详情
Forum post + comment
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 → 发表评论
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} → 获取指定成员详情
Display member avatar
The user.avatar returned by member details is the avatar URL,must be displayed using Markdown image syntax, so users can directly see the avatar image rather than a plain text link:
成员信息：
· 昵称：{nick}
· 头像：
ProhibitedDisplaying the avatar URL as plain text or a hyperlink (such as
查看头像), must usesyntax for inline display. The channel'siconfield is the same.
🚨 Error code handling
| Error code | Description | Solution |
|---|---|---|
| 401 | Token authentication failed | Check the AppID and ClientSecret configuration |
| 11241 | No permission for the channel API | Go to the QQ Open Platform to apply for permission, or call GET /guilds/{guild_id}/api_permission to view available permissions |
| 11242 | Available only to private-domain bots | Need to switch the bot to private-domain mode on the QQ Open Platform |
| 11243 | Channel management permission required | Ensure the bot has administrative permissions |
| 11281 | Schedule frequency limits | Single administrator/day limit 10 times, single channel/day limit 100 times |
| 304023 | Recommended sub-channels exceed limit | Recommended sub-channels maximum 3 |
⚠️ Notes
- Scope of application: This Skill only handles QQ Channel (Guild/Channel) operations, and API paths start with
/guilds/or/channels/, and IDs are pure numbers - placeholders in the path(such as
{guild_id}、{channel_id}) must be replaced with actual pure numeric IDs - query parameter values must be of string type, such as
{ "limit": "100" }rather than{ "limit": 100 } - member list pagingmay return duplicate members, and deduplication must be done by
user.idDeduplicate - announcement's two types (message announcement and recommended sub-channel announcement) will replace each other
- schedule's timestamp is a millisecond-level string
- Delete operations are irreversible, please use with caution
- forum operationsare only available to private-domain bots
- sub-channel groups(type=4)'s
positionmust be >= 2 - schedule operationshave frequency limits: a single administrator 10 times per day, a single channel 100 times per day
- Avatar/icon display: member
user.avatarand channeliconand other image URLs must be displayed using Markdown image syntax, and are prohibited from being displayed as plain text or hyperlinks