准备工作

安装

pip install qq-botpy

更新包的话需要添加 --upgrade 兼容版本：python3.8+

使用

需要使用的地方import botpy

import botpy

兼容提示

原机器人的老版本qq-bot仍然可以使用，但新接口的支持上会逐渐暂停，此次升级不会影响线上使用的机器人

版本更新说明

v1.1.5

1. 更新鉴权方式。 新版本通过AppID + AppSecret进行鉴权，需要使用者进行适配。AppSecret见QQ机器人开发设置页中的AppSecret字段。具体适配方式见示例 鉴权配置示例 鉴权传参接口变更示例
2. 增加群和好友内发消息能力。可参考群内发消息示例 好友内发消息示例
3. 增加群和好友内发送富媒体消息能力，目前支持图片、视频、语音类型。可参考 群内发富媒体消息示例 好友内发富媒体消息示例

使用方式

快速入门

步骤1

通过继承实现bot.Client, 实现自己的机器人Client

步骤2

实现机器人相关事件的处理方法,如 on_at_message_create， 详细的事件监听列表，请参考 事件监听.md

如下，是定义机器人被@的后自动回复:

import botpy
from botpy.message import Message

class MyClient(botpy.Client):
    async def on_at_message_create(self, message: Message):
        await message.reply(content=f"机器人{self.robot.name}收到你的@消息了: {message.content}")

注意:每个事件会下发具体的数据对象，如`message`相关事件是`message.Message`的对象 (部分事件透传了后台数据，暂未实现对象缓存)

步骤3

设置机器人需要监听的事件通道，并启动client

import botpy
from botpy.message import Message

class MyClient(botpy.Client):
    async def on_at_message_create(self, message: Message):
        await self.api.post_message(channel_id=message.channel_id, content="content")

intents = botpy.Intents(public_guild_messages=True) 
client = MyClient(intents=intents)
client.run(appid="12345", secret="xxxx")

备注

也可以通过预设置的类型，设置需要监听的事件通道

import botpy

intents = botpy.Intents.none()
intents.public_guild_messages=True

使用API

如果要使用api方法，可以参考如下方式:

import botpy
from botpy.message import Message

class MyClient(botpy.Client):
    async def on_at_message_create(self, message: Message):
        await self.api.post_message(channel_id=message.channel_id, content="content")

示例机器人

examples 目录下存放示例机器人，具体使用可参考Readme.md

examples/
.
├── README.md
├── config.example.yaml          # 示例配置文件（需要修改为config.yaml）
├── demo_announce.py             # 机器人公告API使用示例
├── demo_api_permission.py       # 机器人授权查询API使用示例
├── demo_at_reply.py             # 机器人at被动回复async示例
├── demo_at_reply_ark.py         # 机器人at被动回复ark消息示例
├── demo_at_reply_embed.py       # 机器人at被动回复embed消息示例
├── demo_at_reply_command.py     # 机器人at被动使用Command指令装饰器回复消息示例
├── demo_at_reply_file_data.py   # 机器人at被动回复本地图片消息示例
├── demo_at_reply_keyboard.py    # 机器人at被动回复md带内嵌键盘的示例
├── demo_at_reply_markdown.py    # 机器人at被动回复md消息示例
├── demo_at_reply_reference.py   # 机器人at被动回复消息引用示例
├── demo_dms_reply.py            # 机器人私信被动回复示例
├── demo_get_reaction_users.py   # 机器人获取表情表态成员列表示例
├── demo_guild_member_event.py   # 机器人频道成员变化事件示例
├── demo_interaction.py          # 机器人互动事件示例（未启用）
├── demo_pins_message.py         # 机器人消息置顶示例
├── demo_recall.py               # 机器人消息撤回示例
├── demo_schedule.py             # 机器人日程相关示例

参与开发

环境配置

pip install -r requirements.txt   # 安装依赖的pip包

pre-commit install                 # 安装格式化代码的钩子

单元测试

代码库提供API接口测试和 websocket 的单测用例，位于 tests 目录中。如果需要自己运行，可以在 tests 目录重命名 .test.yaml 文件后添加自己的测试参数启动测试：

单测执行方法

先确保已安装 pytest ：

pip install pytest

然后在项目根目录下执行单测：

pytest

致谢

感谢感谢以下开发者对 botpy 作出的贡献：

加入官方社区

欢迎扫码加入QQ 频道开发者社区。