QQBot

Appearance

消息 API ​

所有 API 方法通过 self.api 调用。源码位置。

get_message ​

获取指定消息。API 路径：GET /channels/{channel_id}/messages/{message_id}

python
async def get_message(
    channel_id: str,
    message_id: str,
) -> message.MessagePayload
参数类型说明
channel_idstr消息所在子频道 ID
message_idstr消息 ID

返回: MessagePayload — 消息字典对象

源码位置：botpy/api.py 第 481-495 行。

post_message ​

发送消息到子频道。API 路径：POST /channels/{channel_id}/messages

python
async def post_message(
    channel_id: str,
    content: str = None,
    embed: message.Embed = None,
    ark: message.Ark = None,
    message_reference: message.Reference = None,
    image: str = None,
    file_image: Union[bytes, BinaryIO, str] = None,
    msg_id: str = None,
    event_id: str = None,
    markdown: message.MarkdownPayload = None,
    keyboard: message.KeyboardPayload = None,
) -> message.Message
参数类型默认值说明
channel_idstr必填目标子频道 ID
contentOptional[str]None文本消息内容
embedOptional[Embed]NoneEmbed 富文本消息
arkOptional[Ark]NoneARK 模板消息
message_referenceOptional[Reference]None引用消息
imageOptional[str]None图片 URL
file_imageUnion[bytes, BinaryIO, str, None]None本地图片（bytes/文件对象/路径）
msg_idOptional[str]None回复消息 ID（被动回复使用）
event_idOptional[str]None事件 ID
markdownOptional[MarkdownPayload]NoneMarkdown 消息
keyboardOptional[KeyboardPayload]None内联键盘

返回: Message — 消息字典对象

注意

  • 被动回复消息有效期为 5 分钟
  • 主动推送消息每日每个子频道限 2 条
  • 发送消息接口要求机器人需要连接到 WebSocket gateway 保持在线状态
  • 当传入 file_image 时，message_reference 不能同时传入

file_image 三种传参方式:

python
# 1. bytes 类型
with open("image.png", "rb") as img:
    await self.api.post_message(channel_id, file_image=img.read())

# 2. BinaryIO 对象
with open("image.png", "rb") as img:
    await self.api.post_message(channel_id, file_image=img)

# 3. 文件路径（自动读取）
await self.api.post_message(channel_id, file_image="image.png")

消息类型组合:

类型参数说明
纯文本content普通文字消息
Embedembed富文本 embed 消息
ARKark模板消息
MarkdownmarkdownMarkdown 格式消息
引用message_reference引用回复消息
图片URLimage传入网络图片地址
本地图片file_image传入 bytes/BinaryIO/路径
内联键盘keyboard按钮交互消息

源码位置：botpy/api.py 第 497-546 行。

recall_message ​

撤回消息。API 路径：DELETE /channels/{channel_id}/messages/{message_id}

python
async def recall_message(
    channel_id: str,
    message_id: str,
    hidetip: bool = False,
) -> str
参数类型默认值说明
channel_idstr必填消息所在子频道 ID
message_idstr必填要撤回的消息 ID
hidetipboolFalse是否隐藏撤回提示小灰条

返回: 成功返回空字符串

TIP

管理员可以撤回普通成员的消息；频道主可以撤回所有人的消息。

源码位置：botpy/api.py 第 548-572 行。

post_keyboard_message ​

发送内联键盘消息。API 路径：POST /channels/{channel_id}/messages

python
async def post_keyboard_message(
    channel_id: str,
    keyboard: message.KeyboardPayload = None,
    markdown: message.MarkdownPayload = None,
) -> message.Message
参数类型默认值说明
channel_idstr必填目标子频道 ID
keyboardOptional[KeyboardPayload]None键盘配置
markdownOptional[MarkdownPayload]NoneMarkdown 消息内容

返回: Message

源码位置：botpy/api.py 第 574-597 行。

patch_guild_message ​

修改频道 Markdown 消息（需要先申请权限）。API 路径：PATCH /channels/{channel_id}/messages/{patch_msg_id}

python
async def patch_guild_message(
    channel_id: str,
    patch_msg_id: str,
    msg_id: str = None,
    event_id: str = None,
    markdown: message.MarkdownPayload = None,
    keyboard: message.KeyboardPayload = message.KeyboardPayload(content={}),
) -> message.Message
参数类型默认值说明
channel_idstr必填消息所在子频道 ID
patch_msg_idstr必填需要修改的消息 ID
msg_idOptional[str]None回复消息 ID
event_idOptional[str]None事件 ID
markdownOptional[MarkdownPayload]None新 Markdown 内容
keyboardKeyboardPayload{}新键盘配置

返回: Message

源码位置：botpy/api.py 第 618-649 行。

on_interaction_result ​

消息按钮回调结果。API 路径：PUT /interactions/{id}

python
async def on_interaction_result(
    interaction_id: str,
    code: int,
) -> None
参数类型说明
interaction_idstr消息按钮回调事件的 ID
codeint回调结果码

code 参数:

值说明
0成功
1操作失败
2操作频繁
3重复操作
4没有权限
5仅管理员操作

源码位置：botpy/api.py 第 599-616 行。