QQ官方频道机器人SDK

• 开发中~

直接使用SDK

• 参考 bot_main.py
• 在 bot_main.py 同级目录下创建名为 config.yaml 的配置文件，填入自己的 bot_app_id 、 bot_token 及 bot_secret，内容类似下面所示，也可直接使用仓库里的 config.example.yaml 文件，然后自己修改后缀名和内容

bot:
  id: 123  # 机器人id
  token: 456  # 机器人token
  secret: 789  # 机器人secret

import bot_api
from bot_api.models import Ark, Embed
from bot_api.utils import yaml_util

token = yaml_util.read('config.yaml')
bot = bot_api.BotApp(token['bot']['id'], token['bot']['token'], token['bot']['secret'],
                     is_sandbox=True, debug=True, api_return_pydantic=True,
                     ignore_at_self=False,  # 过滤消息正文中艾特Bot自身的内容, 默认为False
                     inters=[bot_api.Intents.GUILDS, bot_api.Intents.AT_MESSAGES,
                             bot_api.Intents.GUILD_MEMBERS])  # 事件订阅


@bot.receiver(bot_api.structs.Codes.SeverCode.BotGroupAtMessage)  # 填入对应的参数实现处理对应事件
def get_at_message(chain: bot_api.structs.Message):  # 注册一个艾特消息处理器
    bot.logger(f"收到来自频道:{chain.guild_id} 子频道: {chain.channel_id} "
               f"内用户: {chain.author.username}({chain.author.id}) 的消息: {chain.content} ({chain.id})")

    if "你好" in chain.content:
        bot.api_send_message(chain.channel_id, chain.id, "hello world!")
    elif "test" in chain.content:
        bot.api_send_message(chain.channel_id, chain.id, "chieri在哟~")
    elif "/echo" in chain.content:
        reply = chain.content[chain.content.find("/echo") + len("/echo"):].strip()
        bot.api_send_message(chain.channel_id, chain.id, reply)

    elif "/embed" in chain.content:  # 发送embed
        send_embed = Embed("标题", ["文本1", "文本2", "文本3"], image_url=None)
        bot.api_send_message(chain.channel_id, chain.id, embed=send_embed)

    elif "/ark" in chain.content:  # 发送ark消息, 需要Ark权限
        send_ark = Ark.LinkWithText("描述", "提示信息", [["纯文本1"], ["纯文本2"], ["链接文本1", "http://baidu.com"]])
        bot.api_send_message(chain.channel_id, chain.id, ark=send_ark)


bot.start()  # 启动bot

关于部分事件官方已改为被动消息说明

事件代号	事件描述
GUILD_MEMBER_ADD	成员加入
GUILD_MEMBER_UPDATE	成员资料变更
GUILD_MEMBER_REMOVE	成员被移除
MESSAGE_REACTION_ADD	消息添加表情表态
MESSAGE_REACTION_REMOVE	消息删除表情表态
FORUM_THREAD_CREATE	用户创建主题
FORUM_THREAD_UPDATE	用户更新主题
FORUM_THREAD_DELETE	用户删除主题
FORUM_POST_CREATE	用户创建帖子
FORUM_POST_DELETE	用户删除帖子
FORUM_REPLY_CREATE	用户回复评论
FORUM_REPLY_DELETE	用户回复评论

使用：即将要回复的消息ID（msg_id）替换为以上事件代号即可

这里以添加表情表态为例：

bot.api_send_message(channel_id, msg_id='MESSAGE_REACTION_ADD', content='ok')

自行组合消息

api_send_message方法提供了极高的自由度。您可以按照本文档提供的方法发送消息, 也可以使用others_parameter参数自行组合。

使用others_parameter, 您需要按照 QQ机器人文档 - 发送消息 提供的参数发送消息, 若有此SDK没有支持的消息类型, 您依旧可以自行组合参数进行发送。

下面是发送一条文本+图片消息的例子

---

• 一般情况下, 您可以:

bot.api_send_message(chain.channel_id, chain.id, "这是消息", "http://您的图片")

• 您也可以:

bot.api_send_message(chain.channel_id, chain.id, others_parameter={"content": "这是消息", "image": "https://您的图片"})

Ark消息说明

• 注意: 发送Ark消息需要向官方申请Ark权限, 否则无法发送

引用:

from bot_api.models import Ark, Embed

发送Embed消息

send_embed = Embed("标题", ["文本1", "文本2", "文本3"], image_url="http://你的图片")
"image_url"
参数可选, 若没有图片, 则不填

bot.api_send_message(channel_id, message_id, embed=send_embed)

发送Ark消息

• Ark类中目前有LinkWithText, TextAndThumbnail, BigImage三个子类, 分别对应 23 链接+文本列表模板, 24 文本+缩略图模板, 37 大图模板, 下面以构造相对复杂的 23 链接+文本列表模板 为例

send_ark = Ark.LinkWithText("描述", "提示信息",
                            [["纯文本1"], ["纯文本2"], ["链接文本1", "http://baidu.com"], ["链接文本2", "http://google.com"]])

bot.api_send_message(channel_id, message_id, ark=send_ark)

目前支持的事件/API

事件

• 下表中所有事件触发时都会在新线程中执行

• 事件代号: 注册函数时, 输入对应事件代号, 在触发相应事件时, 所有被注册函数将被调用。

  • 位于: 类bot_api.structs.Codes.SeverCode, 继承自GatewayEventName

• 传入参数指被注册函数的参数

  • 位于: 类bot_api.structs

事件代号	传入参数	事件描述
FUNC_CALL_AFTER_BOT_LOAD	初始化后的BotAPP类(self)	当Bot初始化完成后, 会立刻执行这些函数
AT_MESSAGE_CREATE	Message	收到艾特消息
MESSAGE_CREATE	Message	收到消息(仅私域机器人可用)
DIRECT_MESSAGE_CREATE	Message	收到私聊消息
GUILD_CREATE	Guild	bot加入频道
GUILD_UPDATE	Guild	频道信息更新
GUILD_DELETE	Guild	频道解散/bot被移除
CHANNEL_CREATE	Channel	子频道被创建
CHANNEL_UPDATE	Channel	子频道信息变更
CHANNEL_DELETE	Channel	子频道被删除
GUILD_MEMBER_ADD	MemberWithGuildID	新用户加入频道
GUILD_MEMBER_UPDATE	-	TX: 暂无
GUILD_MEMBER_REMOVE	MemberWithGuildID	用户离开频道
AUDIO_START	AudioAction	音频开始播放
AUDIO_FINISH	AudioAction	音频结束
AUDIO_ON_MIC	AudioAction	上麦
AUDIO_OFF_MIC	AudioAction	下麦
MESSAGE_REACTION_ADD	MessageReaction	添加表情表态
MESSAGE_REACTION_REMOVE	MessageReaction	删除表情表态
THREAD_CREATE	暂不支持	用户创建主题
THREAD_UPDATE	暂不支持	用户更新主题
THREAD_DELETE	暂不支持	用户删除主题
POST_CREATE	暂不支持	用户创建帖子
POST_DELETE	暂不支持	用户删除帖子
REPLY_CREATE	暂不支持	用户回复评论
REPLY_DELETE	暂不支持	用户回复评论
MESSAGE_AUDIT_PASS	MessageAudited	消息审核通过
MESSAGE_AUDIT_REJECT	MessageAudited	消息审核不通过
PUBLIC_MESSAGE_DELETE	MessageDelete	消息撤回(公域)
MESSAGE_DELETE	MessageDelete	消息撤回(私域)
DIRECT_MESSAGE_DELETE	MessageDelete	消息撤回(私聊)

• 例: 注册一个添加表情表态处理函数

@bot.receiver(bot_api.structs.Codes.SeverCode.MESSAGE_REACTION_ADD)  # 填入事件代号
def get_at_message(event: bot_api.structs.MessageReaction):  # 函数参数类型为上表对应的传入参数
    pass

---

API

• 初始化Bot实例后, 输入bot.api_, 即可根据代码补全进行使用

api_send_message()  # 发送频道消息
api_create_dms()  # 创建私信会话
api_send_private_message()  # 发送私聊消息
api_reply_message()  # 回复消息(频道/私聊)
api_mute_guild()  # 全频道禁言
api_mute_member()  # 指定用户禁言
api_get_self_guilds()  # 获取Bot加入的频道列表
api_get_self_info()  # 获取Bot自身信息
api_get_message()  # 获取指定消息
api_get_guild_channel_list()  # 获取频道内子频道列表
api_get_channel_info()  # 获取子频道信息
api_get_guild_user_info()  # 获取频道用户信息
api_get_guild_info()  # 获取频道信息
api_get_schedule_list()  # 获取子频道日程列表
api_get_schedule()  # 获取单个日程信息
api_schedule_create()  # 创建日程
api_schedule_change()  # 修改日程
api_schedule_delete()  # 删除日程
api_message_recall()  # 撤回消息
api_guild_roles_list_get()  # 获取频道身份组列表
api_guild_role_create()  # 创建频道身份组
api_guild_role_change()  # 修改频道身份组
api_guild_role_remove()  # 删除频道身份组
api_guild_role_member_add()  # 增加频道身份组成员
api_guild_role_member_remove()  # 移除频道身份组成员
api_announces_create()  # 创建频道公告
api_announces_remove()  # 删除频道公告
api_permissions_get_channel()  # 获取指定子频道的权限
api_permissions_change_channel()  # 修改指定子频道的权限
api_permissions_get_channel_group()  # 获取指定子频道身份组的权限
api_permissions_change_channel_group()  # 修改指定子频道身份组的权限
api_audio_control()  # 音频控制
api_get_api_permission()  # 获取频道可用权限列表
api_demand_api_permission()  # 创建频道 API 接口权限授权链接
api_add_pins()  # 添加精华消息
api_remove_pins()  # 删除精华消息
api_get_pins()  # 获取精华消息
api_send_message_reactions()  # 发送表情表态
api_send_message_guide()  # 发送消息设置引导
api_get_guild_message_freq()  # 获取频道消息频率设置

api_pv_get_member_list()  # 仅私域机器人可用 - 取频道成员列表
api_pv_kick_member()  # 仅私域机器人可用 - 踢出指定成员
api_pv_create_channel()  # 仅私域机器人可用 - 创建子频道
api_pv_change_channel()  # 仅私域机器人可用 - 修改子频道信息
api_pv_delete_channel()  # 仅私域机器人可用 - 删除子频道

---

作为HTTP API使用

• 一个人同时更新两套SDK显然是非常困难的。因此HTTP API部分的更新进度会慢于SDK本体(已停更)。欢迎有能之士前来Pr~

• 参考main.py

import bot_api
import server

bot = bot_api.BotApp(123456, "你的bot token", "你的bot secret",
                     is_sandbox=True, debug=True, api_return_pydantic=True,
                     inters=[bot_api.Intents.GUILDS, bot_api.Intents.AT_MESSAGES, bot_api.Intents.GUILD_MEMBERS])  # 事件订阅


app = server.BotServer(bot, ip_call="127.0.0.1", port_call=11415, ip_listen="127.0.0.1", port_listen=1988,
                       allow_push=False)

# 开始注册事件, 可以选择需要的进行注册
app.reg_bot_at_message()  # 艾特消息事件
app.reg_guild_member_add()  # 成员增加事件
app.reg_guild_member_remove()  # 成员减少事件

# 以下事件与onebot差别较大
app.reg_guild_create()  # Bot加入频道事件
app.reg_guild_update()  # 频道信息更新事件
app.reg_guild_delete()  # Bot离开频道/频道被解散事件
app.reg_channel_create()  # 子频道创建事件
app.reg_channel_update()  # 子频道信息更新事件
app.reg_channel_delete()  # 子频道删除事件

@app.bot.receiver(bot_api.structs.Codes.SeverCode.image_to_url)  # 注册一个图片转url方法
def img_to_url(img_path: str):
    # 用处: 发送图片时, 使用图片cq码[CQ:image,file=]或[CQ:image,url=]
    # 装饰器作用为: 解析cq码中图片的路径(网络图片则下载到本地), 将绝对路径传给本函数, 自行操作后, 返回图片url, sdk将使用此url发送图片
    # 若不注册此方法, 则无法发送图片。
    print(img_path)
    return "https://你的图片url"

# 注册事件结束

app.listening_server_start()  # HTTP API 服务器启动
app.bot.start()  # Bot启动

---

目前实现的CQ码

CQ码	功能	备注
[CQ:reply,id=abc123]	回复消息	被动回复请务必带上此CQ码, 否则会被视为主动推送消息
[CQ:at,qq=123456]	艾特用户	与官方<@!123456>对应
[CQ:image,file=...] [CQ:image,url=...]	发送图片	发送图片可以使用这两个CQ码 由于API限制, 发送图片仅支持一张, 并且需要自行配置图床(见上方代码示例) 接收到图片时, 目前仅会返回[CQ:image,url=...]

---

目前实现的API(基本同onebot):

• 特别注意: 所有用户ID, 频道号, 子频道号, 消息ID字段均为string

接口	描述	备注
/send_group_msg	发送群消息	group_id请填写channel_id auto_escape为true时, 依然会解析[CQ:reply]
/get_group_member_info	获取成员信息	group_id请填写guild_id 仅user_id,nickname,role有效 额外增加头像URL: avatar

---

目前实现的API(与onebot不同)

获取自身信息

• 接口: /get_self_info

参数	类型	默认值	说明
cache	bool	false	是否使用缓存(可选)

• 返回参数

参数	类型	说明
avatar	string	头像url
id	string	BotID
username	string	Bot名

获取自身加入频道列表

• 接口: /get_self_guild_list

参数	类型	默认值	说明
cache	bool	false	是否使用缓存(可选)
before	string	-	读此id之前的数据(可选, before/after只能二选一)
after	string	-	读此id之后的数据(可选, before/after只能二选一)
limit	int	100	每次拉取多少条数据(可选)

• 返回参数

见: https://bot.q.qq.com/wiki/develop/api/openapi/channel/get_channel.html

获取频道信息

• 接口: /get_guild_info

参数	类型	默认值	说明
guild_id	string	-	频道id

• 返回参数

见: https://bot.q.qq.com/wiki/develop/api/openapi/guild/get_guild.html

获取子频道信息

• 接口: /get_channel_info

参数	类型	默认值	说明
channel_id	string	-	子频道id

• 返回参数

见: https://bot.q.qq.com/wiki/develop/api/openapi/channel/get_channel.html

获取子频道列表

• 接口: /get_channel_list

参数	类型	默认值	说明
guild_id	string	-	频道id

• 返回参数

见: https://bot.q.qq.com/wiki/develop/api/openapi/channel/get_channels.html

获取指定消息

• 接口: /get_message

参数	类型	默认值	说明
message_id	string	-	消息id
channel_id	string	-	频道id

• 返回参数

见: https://bot.q.qq.com/wiki/develop/api/openapi/message/get_message_of_id.html

---

目前实现的Event(基本同onebot)

• 特别注意: 所有用户ID, 频道号, 子频道号, 消息ID字段均为string

收到艾特消息

• 见: https://github.com/botuniverse/onebot-11/blob/master/event/message.md#%E7%BE%A4%E6%B6%88%E6%81%AF

• 注意:

  • 注意上面的特别注意
  • anonymous字段恒为null
  • sender字段中仅user_id, nickname, role有效

成员增加事件

• 见: https://github.com/botuniverse/onebot-11/blob/master/event/notice.md#%E7%BE%A4%E6%88%90%E5%91%98%E5%A2%9E%E5%8A%A0
• 注意:

  • 注意上面的特别注意

  • sub_type恒为approve

成员减少事件

• 见: https://github.com/botuniverse/onebot-11/blob/master/event/notice.md#%E7%BE%A4%E6%88%90%E5%91%98%E5%87%8F%E5%B0%91
• 注意:
  • 注意上面的特别注意
  • sub_type恒为leave

---

目前实现的Event(与onebot差别较大)

• 通用字段

参数	类型	默认值	说明
time	int	-	消息接收时间戳
self_id	string	-	自身id
post_type	string	notice	上报类型
notice_type	string	-	通知类型
sub_type	string	-	通知子类型
user_id	string	空字符串	触发者ID, 仅在对应事件有值
guild_id	string	空字符串	触发频道ID, 仅在对应事件有值
channel_id	string	空字符串	触发子频道ID, 仅在对应事件有值
data	-	-	每个事件均不同, 见下方文档

Bot加入频道事件

参数	类型	值
post_type	string	notice
notice_type	string	guild_create
sub_type	string	guild_create
guild_id	string	频道ID
data	Guild	见: 腾讯机器人文档

频道信息更新事件

参数	类型	值
post_type	string	notice
sub_type	string	guild_update
guild_id	string	频道ID
data	Guild	见: 腾讯机器人文档

机器人离开频道/频道被解散事件

参数	类型	值
post_type	string	notice
notice_type	string	guild_update
sub_type	string	guild_update
guild_id	string	频道ID
data	Guild	见: 腾讯机器人文档

子频道创建事件

参数	类型	值
post_type	string	notice
notice_type	string	channel_create
sub_type	string	channel_create
guild_id	string	频道ID
channel_id	string	子频道ID
data	Channel	见: 腾讯机器人文档

子频道信息更新事件

参数	类型	值
post_type	string	notice
notice_type	string	channel_update
sub_type	string	channel_update
guild_id	string	频道ID
channel_id	string	子频道ID
data	Channel	见: 腾讯机器人文档

子频道被删除事件

参数	类型	值
post_type	string	notice
notice_type	string	channel_delete
sub_type	string	channel_delete
guild_id	string	频道ID
channel_id	string	子频道ID
data	Channel	见: 腾讯机器人文档