8.1 KiB
8.1 KiB
消息 API
发消息是机器人最基础的功能。这一页讲的是怎么发消息、撤回消息、转发消息，以及怎么用消息段（图片、@人、表情等等）。
快速开始
发一条简单的消息
from core.managers.command_manager import matcher
from models.events.message import MessageEvent
@matcher.command("hello")
async def handle_hello(event: MessageEvent):
# 方法 1: 直接回复（最常用）
await event.reply("你好呀！")
# 方法 2: 通过 bot 实例发消息
await event.bot.send_group_msg(event.group_id, "这是一条群消息")
# 如果是私聊，可以用 send_private_msg
# await event.bot.send_private_msg(event.user_id, "这是一条私聊消息")
event.reply() 是最简单的方式，它会自动判断是群聊还是私聊，然后调用正确的 API。
消息段 (MessageSegment)
除了纯文字，QQ 消息还能包含图片、@某人、表情、分享链接等等。在 OneBot 里，这些叫“消息段”。
NEO Bot 用 MessageSegment 类来表示消息段。
创建消息段
from models.message import MessageSegment
# 文本
text_seg = MessageSegment.text("这是一段文字")
# @某人
at_seg = MessageSegment.at(123456) # @QQ号 123456
at_all = MessageSegment.at("all") # @全体成员
# 图片
image_seg = MessageSegment.image("https://example.com/image.jpg")
# 本地图片
local_image = MessageSegment.image("file:///path/to/image.png")
# 表情 (QQ 表情，不是 emoji)
face_seg = MessageSegment(type="face", data={"id": "123"})
# 分享链接
share_seg = MessageSegment(type="share", data={
"url": "https://example.com",
"title": "示例网站",
"content": "这是一个示例网站",
"image": "https://example.com/thumb.jpg"
})
组合消息段
你可以把多个消息段组合成一条消息：
# 方法 1: 用列表
message = [
MessageSegment.text("你好，"),
MessageSegment.at(123456),
MessageSegment.text("！"),
MessageSegment.image("https://example.com/welcome.jpg")
]
# 方法 2: 用加法运算符（更直观）
message = (
MessageSegment.text("你好，") +
MessageSegment.at(123456) +
MessageSegment.text("！")
)
# 发送组合消息
await event.reply(message)
从 CQ 码转换
如果你熟悉 CQ 码，也可以用 MessageSegment 来解析：
# CQ 码字符串转消息段列表（需要手动解析，这里只是示例）
# 实际使用中，框架会自动处理 CQ 码
API 方法详解
send_group_msg - 发送群消息
async def send_group_msg(
self,
group_id: int,
message: Union[str, MessageSegment, List[MessageSegment]],
auto_escape: bool = False
) -> Dict[str, Any]
参数：
group_id: 群号message: 消息内容，可以是字符串、单个消息段，或消息段列表auto_escape: 是否对消息中的 CQ 码特殊字符进行转义（仅当message是字符串时有效）
示例：
# 发文字
await bot.send_group_msg(123456, "大家好！")
# 发图片
await bot.send_group_msg(123456, MessageSegment.image("https://example.com/cat.jpg"))
# 发组合消息
msg = MessageSegment.text("看这只猫：") + MessageSegment.image("https://example.com/cat.jpg")
await bot.send_group_msg(123456, msg)
send_private_msg - 发送私聊消息
async def send_private_msg(
self,
user_id: int,
message: Union[str, MessageSegment, List[MessageSegment]],
auto_escape: bool = False
) -> Dict[str, Any]
参数：
user_id: 对方的 QQ 号message: 消息内容auto_escape: 是否转义 CQ 码
示例：
await bot.send_private_msg(123456, "你好，这是一条私聊消息")
send - 智能发送
async def send(
self,
event: OneBotEvent,
message: Union[str, MessageSegment, List[MessageSegment]],
auto_escape: bool = False
) -> Dict[str, Any]
这个方法会根据事件的类型自动选择发群消息还是私聊消息。如果事件是消息事件，它其实会调用 event.reply()。
示例：
# 在事件处理函数中
await bot.send(event, "自动判断是群聊还是私聊")
delete_msg - 撤回消息
async def delete_msg(self, message_id: int) -> Dict[str, Any]
参数：
message_id: 要撤回的消息 ID（从消息事件中获取）
示例：
@matcher.command("recall")
async def handle_recall(event: MessageEvent):
# 撤回上一条消息（假设我们知道 message_id）
message_id = event.message_id
await event.bot.delete_msg(message_id)
get_msg - 获取消息详情
async def get_msg(self, message_id: int) -> Dict[str, Any]
获取一条消息的详细信息，包括发送者、发送时间、内容等。
get_forward_msg - 获取合并转发消息
async def get_forward_msg(self, id: str) -> List[Dict[str, Any]]
获取一条合并转发消息（聊天记录）的详细内容。
参数：
id: 合并转发消息的 ID（从消息中获取）
返回值：
- 消息节点列表，每个节点包含发送者、时间、内容等信息
合并转发
合并转发就是那种“点击展开查看聊天记录”的消息。在 QQ 里很常见。
构建转发节点
先用 bot.build_forward_node() 创建节点：
# 创建一个转发节点
node = bot.build_forward_node(
user_id=123456, # 发送者的 QQ 号
nickname ="张三", # 显示的名字
message="这是一条测试消息" # 消息内容
)
# 消息内容也可以用消息段
node2 = bot.build_forward_node(
user_id=789012,
nickname="李四",
message=MessageSegment.text("看这个图片：") + MessageSegment.image("https://example.com/img.jpg")
)
发送合并转发
# 方法 1: 直接发到群聊
nodes = [node1, node2, node3]
await bot.send_group_forward_msg(group_id=123456, messages=nodes)
# 方法 2: 发到私聊
await bot.send_private_forward_msg(user_id=123456, messages=nodes)
# 方法 3: 智能发送（根据事件判断）
await bot.send_forwarded_messages(target=event, nodes=nodes)
完整示例
@matcher.command("forward")
async def handleforward_(event: MessageEvent):
# 创建几个测试节点
nodes = [
event.bot.build_forward_node(
user_id=10001,
nickname="系统",
message="欢迎使用 NEO Bot"
),
event.bot.build_forward_node(
user_id=event.user_id,
nickname=event.sender.nickname,
message="这个合并转发功能真好用！"
),
event.bot.build_forward_node(
user_id=10002,
nickname="机器人",
message=MessageSegment.text("谢谢夸奖！") + MessageSegment.face(id="123")
)
]
# 发送
await event.bot.send_forwarded_messages(event, nodes)
消息事件中的快捷方法
在消息事件 (MessageEvent) 中，有一些快捷方法：
event.reply()
await event.reply("你好！")
await event.reply(message_segment_list)
自动回复到消息来源（群聊或私聊）。
event.message
获取事件中的消息内容（已经是 MessageSegment 列表格式）。
# 检查消息是否包含图片
for segment in event.message:
if segment.type == "image":
await event.reply("你发了一张图片！")
break
注意事项
- 消息长度限制: QQ 对单条消息有长度限制，太长的消息会被截断。
- 频率限制: 不要疯狂发消息，可能会被腾讯限制。
- 图片缓存: 默认情况下，图片会缓存到本地，下次发送同样的图片会更快。
- 网络错误: 发消息可能因为网络问题失败，建议做好错误处理。
下一步
现在你已经知道怎么发消息了。接下来可以看看：