QQ Channel API Request Guide

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

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

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

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

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 — For 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
Publish 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

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" }
}

Get sub-channel list

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
  }
}

Get member list (pagination)

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
  }
}

Create schedule

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": "欢迎来到攻略频道" }
    ]
  }
}

Delete all announcements

json

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

🔄 Common Operation Processes

Get guild and sub-channel information

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 → 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 → 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

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

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

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

qqbot-channel

NPX Install

Tags

SKILL.md Content (Chinese)

QQ Channel API Request Guide

📚 Detailed Reference Documentation

🔧 Tool Parameters

⭐ Quick API Reference

Guild

Channel

Member

Announces

Forum — For private domain bots only

Schedule

💡 Call Examples

Get guild list

Get sub-channel list

Create sub-channel

Get member list (pagination)

Publish forum post

Create schedule

Create recommended sub-channel announcement

Delete all announcements

🔄 Common Operation Processes

Get guild and sub-channel information

Forum posting + commenting

Member management

Display member avatar

🚨 Error Code Handling

⚠️ Notes