QQ频道机器人零基础开发详解(基于QQ官方机器人文档)[第三期]
第三期介绍:频道模块之频道成员
不懂得的也可以来私聊或评论区问哦~
原力到一千才可以推广,三连啊喂!!!
获取子频道在线成员数
接口
GET /channels/{channel_id}/online_nums
功能描述
此接口用于查询音视频/直播子频道channel_id
的在线成员数。
Content-Type
application/json
返回
成功时返回空对象,包含在线成员数:
{
"online_nums": 1
}
错误码
具体错误码信息请参考错误码。
Python示例
import requests
url = f"https://api.sgroup.qq.com/channels/{channel_id}/online_nums"
Authorization = f"QQBot {你的鉴权,不懂得看前面文章}"
herders = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.get(url, headers=herders).json()
print(response)
运行成功如下,因为我没有音频子频道,所以是如下输出:
{'code': 505007, 'message': 'requested channel is not audio or live channel'}
获取频道成员列表
接口
GET /guilds/{guild_id}/members
功能描述
用于获取指定guild_id
的频道中所有成员的详情列表,支持分页。
注意事项
- 公域机器人暂不支持申请,仅私域机器人可用。
- 开通后需要先将机器人从频道移除,然后重新添加,方可生效。
Content-Type
application/json
参数
字段名 | 类型 | 描述 |
---|---|---|
after | string | 上一次回包中最后一个 member 的 user id ,如果是第一次请求填 0,默认为 0 |
limit | uint32 | 分页大小,1-400,默认是 1。成员较多的频道尽量使用较大的 limit 值,以减少请求数 |
返回
返回Member
对象数组。
返回结果说明
- 在每次翻页的过程中,可能会返回上一次请求已经返回过的
member
信息,需要调用方自己根据user id
来进行去重。 - 每次返回的
member
数量与limit
不一定完全相等。翻页请使用最后一个member
的user id
作为下一次请求的after
参数,直到回包为空,拉取结束。
错误码
具体错误码信息请参考错误码。
Python示例
import requests
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/members?limit=2"
Authorization = f"QQBot {你的鉴权}"
herders = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.get(url, headers=herders).json()
print(response)
运行结果如下:
# 运行出来的是一行的,不好展示,使用官方回复样式,实际获取数据和这个大差不差
[
{
"user": {
"id": "xxxxxx",
"username": "xxxx",
"avatar": "xxxxxx",
"bot": false,
"public_flags": 0,
"system": false,
"union_openid": "xxxxxx",
"union_user_account": ""
},
"nick": "",
"roles": ["1"],
"joined_at": "2021-12-09T15:53:41+08:00",
"deaf": false,
"mute": false,
"pending": false
},
{
"user": {
"id": "xxxxxx",
"username": "秦时明月",
"avatar": "xxxxxx",
"bot": false,
"public_flags": 0,
"system": false,
"union_openid": "xxxxxx",
"union_user_account": ""
},
"nick": "",
"roles": ["4"],
"joined_at": "2021-12-02T15:19:00+08:00",
"deaf": false,
"mute": false,
"pending": false
}
]
获取频道身份组成员列表
接口
GET /guilds/{guild_id}/roles/{role_id}/members
功能描述
用于获取 guild_id
频道中指定 role_id
身份组下所有成员的详情列表,支持分页。
注意
- 公域机器人暂不支持申请,仅私域机器人可用,选择私域机器人后默认开通。
- 开通后需要先将机器人从频道移除,然后重新添加,方可生效。
参数
字段名 | 类型 | 描述 |
---|---|---|
start_index | string | 将上一次回包中 next 填入,如果是第一次请求填 0,默认为 0 |
limit | uint32 | 分页大小,1-400,默认是 1。成员较多的频道尽量使用较大的 limit 值,以减少请求数 |
返回
字段名 | 类型 | 描述 |
---|---|---|
data | Member 对象数组 | 一组用户信息对象 |
next | string | 下一次请求的分页标识 |
有关返回结果的说明
每次返回的 member
数量与 limit
不一定完全相等。特定管理身份组下的成员可能存在一次性返回全部的情况。
错误码
详见错误码。
Python示例
import requests
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/roles/{role_id}/members?limit=2"
Authorization = f"QQBot {你的鉴权}"
herders = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.get(url, headers=herders).json()
print(response)
运行结果如下:
{
"data": [
{
"user": {
"id": "xxx",
"username": "xxx",
"avatar": "xxx",
"bot": false
},
"nick": "xxx",
"joined_at": "2021-11-03T20:41:36+08:00"
}
],
"next": "0"
}
获取频道成员详情
接口
GET /guilds/{guild_id}/members/{user_id}
功能描述
用于获取 guild_id
指定的频道中 user_id
对应成员的详细信息。
Content-Type
application/json
返回
返回 Member 成员对象。
错误码
详见错误码。
Python示例
import requests
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/members/{user_id}"
Authorization = f"QQBot {你的鉴权}"
herders = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.get(url, headers=herders).json()
print(response)
运行结果如下:
{
"user": {
"id": "2823701233424295228",
"username": "xxx",
"avatar": "https://qqchannel-profile-1251316161.file.myqcloud.com/xxxxxxx",
"bot": false,
"union_openid": "",
"union_user_account": ""
},
"nick": "",
"roles": [
"1"
],
"joined_at": "2021-12-05T14:08:29+08:00"
}
删除频道成员
接口
DELETE /guilds/{guild_id}/members/{user_id}
功能描述
用于删除 guild_id
指定的频道下的成员 user_id
。
- 需要使用的
token
对应的用户具备踢人权限。如果是机器人,要求被添加为管理员。(读者需要知道的是,在我们提交的鉴权里,除了机器人的,也可以提交管理员的鉴权,当你提交的是机器人的鉴权,那么将是机器人执行,如果你提交的是操作者的鉴权,那么将是操作者执行,这在第一期提过一点) - 操作成功后,会触发 频道成员删除事件。
- 无法移除身份为管理员的成员
注意
- 公域机器人暂不支持申请,仅私域机器人可用,选择私域机器人后默认开通。
- 注意: 开通后需要先将机器人从频道移除,然后重新添加,方可生效。
Content-Type
application/json
参数
字段名 | 类型 | 描述 |
---|---|---|
add_blacklist | bool | 删除成员的同时,将该用户添加到频道黑名单中 |
delete_history_msg_days | int | 删除成员的同时,撤回该成员的消息,可以指定撤回消息的时间范围 |
注:消息撤回时间范围仅支持固定的天数: 3
, 7
, 15
, 30
。 特殊的时间范围: -1: 撤回全部消息
。默认值为 0
不撤回任何消息。
返回
成功返回 HTTP 状态码 204
。
错误码
详见错误码。
Python示例
import requests
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/members/{user_id}"
Authorization = f"QQBot {你的鉴权}"
data = {
{
"add_blacklist": True,# 删除成员的同时,将该用户添加到频道黑名单中
"delete_history_msg_days": -1# -1: 撤回全部消息
}
}
herders = {
"Content-Type": "application/json",
"Authorization": Authorization
}
response = requests.delete(url, headers=herders).json()
print(response)
我懒得删除自己的用户,这里返回就不展示了,官方也没有给示例,成功了就是返回状态码。
致谢和更新
文章持续更新,如果三连支持,速更!!!
请在评论区提出疑惑和建议
上次更新: 9/10/2024, PM
👻关于频道成员事件和音视频/直播子频道成员进出事件 ,它们基于websocket方法。因为目前在讲openapi方法调用QQ频道机器人,所以暂时跳过这部分,当然放心啦,三连我速更,肯定会讲啦。
⬅️QQ频道机器人零基础开发详解(基于QQ官方机器人文档)[第二期]
➡️第四期:频道模块之频道身份组与权限管理(更新中…)