QQ频道机器人零基础开发详解(基于QQ官方机器人文档)[第五期]

QQ频道机器人零基础开发详解(基于QQ官方机器人文档)[第五期]

第五期介绍：频道模块之接口授权管理和发言管理

不懂得的也可以来私聊或评论区问哦～

原力到一千才可以推广，三连啊喂！！！

获取机器人在频道可用权限列表

接口

GET /guilds/{guild_id}/api_permission

功能描述
用于获取机器人在频道 guild_id 内可以使用的权限列表。

Content-Type
application/json

返回

错误码
详见错误码。

Python示例

import requests

guild_id = "你的频道ID"
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/api_permission"
Authorization = "QQBot 你的鉴权token"

headers = {
    "Authorization": Authorization
}

response = requests.get(url, headers=headers).json()

print(response)

响应数据包

# 取决于你给了机器人多少权限，我都给了，数据包返回了一大堆数据
{
  "apis": [
    {
      "path": "/guilds/{guild_id}/members/{user_id}",
      "method": "GET",
      "desc": "获取当前频道成员信息",
      "auth_status": 0
    },
    {
      "path": "/channels/{channel_id}/messages",
      "method": "POST",
      "desc": "创建消息",
      "auth_status": 1
    }
  ]
}

发送机器人在频道接口权限的授权链接

接口

POST /guilds/{guild_id}/api_permission/demand

功能描述
用于创建 API 接口权限授权链接，该链接指向 guild_id 对应的频道。

• 每天只能在一个频道内发 3 条（默认值）频道权限授权链接。

Content-Type
application/json

参数

返回
返回 APIPermissionDemand 对象。

错误码
详见错误码。

Python示例

import requests

guild_id = "你的频道ID"
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/api_permission/demand"
Authorization = f"QQBot 你的鉴权token"

data = {
  "channel_id": "你的子频道id",
  "api_identify": {
    "path": "/guilds/{guild_id}",
    "method": "GET"
  },
  "desc": "显示频道信息"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": Authorization
}

response = requests.post(url, headers=headers, json=data).json()

print(response)

请求数据包

{
  "channel_id": "123456",
  "api_identify": {
    "path": "/guilds/{guild_id}",
    "method": "GET"
  },
  "desc": "显示频道信息"
}

响应数据包

{
  "guild_id": "xxxxxx",
  "channel_id": "123456",
  "api_identify": {
    "path": "/guilds/{guild_id}",
    "method": "GET"
  },
  "title": "王者机器人申请授权频道信息接口权限",
  "desc": "申请权限后才能正常使用机器人显示频道信息功能"
}

示例图

获取频道消息频率的设置详情

接口

GET /guilds/{guild_id}/message/setting

功能描述
用于获取机器人在频道 guild_id 内的消息频率设置。

Content-Type
application/json

返回
返回 MessageSetting 对象。

错误码
详见错误码。

Python示例

import requests

guild_id = "你的频道ID"
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/message/setting"
Authorization = f"QQBot 你的鉴权token"

headers = {
    "Authorization": Authorization
}

response = requests.get(url, headers=headers).json()

print(response)

响应数据包

{
  "disable_create_dm": true, # 是否允许创建私信
  "disable_push_msg": false, # 是否允许发主动消息
  "channel_ids": [
    "1146313",
    "2651849",
    "2651149"
  ],# 子频道 id 数组
  "channel_push_max_num": 12 # 每个子频道允许主动推送消息最大消息条数
}

频道全员禁言

接口

PATCH /guilds/{guild_id}/mute

功能描述
用于将频道的全体成员（非管理员）禁言。

• 需要使用的 token 对应的用户具备管理员权限。如果是机器人，要求被添加为管理员。

该接口同样可用于解除禁言，具体使用见 解除全员禁言。

Content-Type
application/json

参数

解除禁言
该接口同样支持解除全员禁言，将mute_end_timestamp或mute_seconds传值为字符串’0’即可。

返回
成功返回 HTTP 状态码 204。

错误码
详见错误码。

Python示例

import requests

guild_id = "你的频道ID"
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/mute"
Authorization = f"QQBot 你的鉴权token"

# mute_end_timestamp和mute_seconds设置一个就好了，时间戳别用案例里面的，自己设置。
data = {
  "mute_end_timestamp": "1641916800",
  "mute_seconds": "120"
}

headers = {
    "Authorization": Authorization
}

response = requests.patch(url, headers=headers, json=data)

if response.status_code == 204:
    print("全员禁言成功")
else:
    print("禁言失败，状态码：", response.status_code)

请求数据包

{
  "mute_end_timestamp": "xxxx",
  "mute_seconds": "120"
}

示例图：

频道指定成员禁言

接口

PATCH /guilds/{guild_id}/members/{user_id}/mute

功能描述
用于禁言频道 guild_id 下的成员 user_id。

• 需要使用的 token 对应的用户具备管理员权限。如果是机器人，要求被添加为管理员。

该接口同样可用于解除禁言，具体使用见 解除指定成员禁言。

Content-Type
application/json

参数

返回
成功返回 HTTP 状态码 204。

错误码
详见错误码。

Python示例

import requests

guild_id = "你的频道ID"
user_id = "你的用户ID"
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/members/{user_id}/mute"
Authorization = f"QQBot 你的鉴权token"

data = {
  "mute_end_timestamp": "1641916800",
  "mute_seconds": "120"
}

headers = {
    "Authorization": Authorization
}

response = requests.patch(url, headers=headers, json=data)

if response.status_code == 204:
    print("指定成员禁言成功")
else:
    print("禁言失败，状态码：", response.status_code)

请求数据包

{
  "mute_end_timestamp": "1641916800",
  "mute_seconds": "120"
}

频道批量成员禁言

接口

PATCH /guilds/{guild_id}/mute

功能描述
用于将频道的指定批量成员（非管理员）禁言。

• 需要使用的 token 对应的用户具备管理员权限。如果是机器人，要求被添加为管理员。

该接口同样可用于批量解除禁言，具体使用见 批量解除禁言。

Content-Type
application/json

参数

批量解除禁言
该接口同样支持批量解除禁言，将mute_end_timestamp或mute_seconds传值为字符串’0’即可，及需要批量解除禁言的成员的user_id 列表user_ids。

返回
成功返回 HTTP 状态码 200，并返回设置成功的成员 user_ids。

错误码
详见错误码。

Python示例

import requests

guild_id = "你的频道ID"
url = f"https://api.sgroup.qq.com/guilds/{guild_id}/mute"
Authorization = f"QQBot 你的鉴权token"

data = {
  "mute_end_timestamp": "1641916800",
  "mute_seconds": "120",
  "user_ids": ["1201318637970874066","1201318637970874067"]
}

headers = {
    "Authorization": Authorization
}

response = requests.patch(url, headers=headers, json=data)

if response.status_code == 200:
    print("批量成员禁言成功")
    print(response.json())
else:
    print("禁言失败，状态码：", response.status_code)

请求数据包

{
  "mute_end_timestamp": "1641916800",
  "mute_seconds": "120",
  "user_ids": ["1201318637970874066","1201318637970874067"]
}

响应数据包

{
  "user_ids": ["1201318637970874066"]
}

致谢和更新

文章持续更新，如果三连支持，速更！！！
请在评论区提出疑惑和建议
上次更新: 9/12/2024, AM

⬅️第四期：频道模块之频道身份组与权限管理
➡️第六期：频道模块之内容管理