NcatBot 文档

外观

消息 API — 核心方法与便捷方法

约 1340 字大约 4 分钟

2026-03-19

QQMessaging 核心消息方法 + QQMessageSugarMixin 便捷方法的完整参数表、返回值和示例。

核心方法通过 api.qq.messaging.xxx() 调用，Sugar 方法通过 api.qq.xxx() 调用。

核心消息方法

命名空间：api.qq.messaging（QQMessaging）

send_group_msg()

async def send_group_msg(
    self, group_id: Union[str, int], message: list, **kwargs
) -> SendMessageResult:
参数类型必填说明
group_idstr | int是目标群号
messagelist是消息段列表（OneBot v11 格式）

返回值：SendMessageResult — 包含 message_id: str

send_private_msg()

async def send_private_msg(
    self, user_id: Union[str, int], message: list, **kwargs
) -> SendMessageResult:
参数类型必填说明
user_idstr | int是目标用户 QQ 号
messagelist是消息段列表

delete_msg()

async def delete_msg(self, message_id: Union[str, int]) -> None:

撤回消息。OneBot v11 Action：delete_msg

send_forward_msg()

async def send_forward_msg(
    self, message_type: str, target_id: Union[str, int],
    messages: list, **kwargs,
) -> SendMessageResult:
参数类型必填说明
message_typestr是"group" 或 "private"
target_idstr | int是目标群号或用户 QQ 号
messageslist是合并转发消息节点列表

send_poke()

async def send_poke(
    self, group_id: Union[str, int], user_id: Union[str, int],
) -> None:

戳一戳（NapCat 扩展）。

friend_poke()

async def friend_poke(self, user_id: Union[str, int]) -> None:

私聊戳一戳。

send_like()

async def send_like(self, user_id: Union[str, int], times: int = 1) -> None:

给用户点赞。times 为点赞次数，默认 1。

set_msg_emoji_like()

async def set_msg_emoji_like(
    self, message_id: Union[str, int], emoji_id: str, set: bool = True,
) -> None:

对消息设置/取消表情回应。emoji_id 为 QQ 表情 ID，set=False 取消。

mark_group_msg_as_read() / mark_private_msg_as_read() / mark_all_as_read()

async def mark_group_msg_as_read(self, group_id: Union[str, int]) -> None:
async def mark_private_msg_as_read(self, user_id: Union[str, int]) -> None:
async def mark_all_as_read(self) -> None:

标记群/私聊/全部消息为已读。

forward_friend_single_msg() / forward_group_single_msg()

async def forward_friend_single_msg(self, user_id: Union[str, int], message_id: Union[str, int]) -> None:
async def forward_group_single_msg(self, group_id: Union[str, int], message_id: Union[str, int]) -> None:

逐条转发单条消息到好友/群。

get_group_msg_history() / get_friend_msg_history()

async def get_group_msg_history(
    self, group_id: Union[str, int], message_seq: Union[str, int, None] = None, count: int = 20,
) -> MessageHistory:
async def get_friend_msg_history(
    self, user_id: Union[str, int], message_seq: Union[str, int, None] = None, count: int = 20,
) -> MessageHistory:

获取群/好友消息历史。message_seq 为起始消息序号，count 为拉取条数。

QQMessageSugarMixin 便捷方法

通过 api.qq.xxx() 直接调用（QQAPIClient 继承了 QQMessageSugarMixin）。

post_group_msg()

async def post_group_msg(
    self, group_id, text=None, at=None, reply=None, image=None, video=None, rtf=None,
    *, strict=False,
) -> SendMessageResult:

便捷群消息 — 组装顺序：reply → at → text → image → video → rtf。

参数类型说明
textstr | None文本内容
atstr | int | None要 @ 的用户 QQ 号
replystr | int | None要回复的消息 ID
imagestr | Image | None图片路径/URL
videostr | Video | None视频路径/URL
rtfMessageArray | None自定义富文本消息数组
strictbool为 True 时任何段冲突都抛 QQSegmentConflictError。默认 False（自动拆分）

段冲突防护：当 strict=False（默认）时，若组合中包含冲突段（如同时传 video 和 text），框架会自动拆为多条消息发送，而非静默丢弃。详见 段冲突规则。

post_private_msg()

用法与 post_group_msg 类似，但无 at 参数。同样支持 strict 参数。

post_group_array_msg() / post_private_array_msg()

async def post_group_array_msg(self, group_id, msg: MessageArray, *, strict=False) -> SendMessageResult:
async def post_private_array_msg(self, user_id, msg: MessageArray, *, strict=False) -> SendMessageResult:

支持 strict 参数，行为同 post_group_msg。

群消息 Sugar

方法签名说明
send_group_text(group_id, text)群纯文本
send_group_plain_text(group_id, text)PlainText 段群文本
send_group_image(group_id, image)群图片
send_group_record(group_id, file)群语音
send_group_file(group_id, file, name=None)群文件
send_group_video(group_id, video)群视频
send_group_sticker(group_id, image)群动画表情

私聊消息 Sugar

方法签名说明
send_private_text(user_id, text)私聊纯文本
send_private_plain_text(user_id, text)PlainText 段私聊文本
send_private_image(user_id, image)私聊图片
send_private_record(user_id, file)私聊语音
send_private_file(user_id, file, name=None)私聊文件
send_private_video(user_id, video)私聊视频
send_private_sticker(user_id, image)私聊动画表情
send_private_dice(user_id, value=1)骰子魔法表情
send_private_rps(user_id, value=1)猜拳魔法表情

合并转发 Sugar

方法签名说明
post_group_forward_msg(group_id, forward: Forward)群合并转发
post_private_forward_msg(user_id, forward: Forward)私聊合并转发
send_group_forward_msg_by_id(group_id, message_ids: List)通过消息 ID 逐条转发
send_private_forward_msg_by_id(user_id, message_ids: List)通过消息 ID 转发到私聊

所有方法返回 SendMessageResult（含 message_id）。

消息段冲突规则

QQ 平台对同一消息中包含多种"独占段"时会静默吞掉部分段，甚至导致客户端崩溃。NcatBot 在 Sugar 层对此进行了防护。

段类型分类

类别段类型说明
独占段Video, File发送时会吞掉同消息内的其他非独占段
崩溃段Forward混入 MessageArray 会导致客户端崩溃
视觉段Image, QQImage(动画表情)可与轻量段共存，但被独占段吞掉
轻量段Text, At, Reply, Face互相兼容

兼容矩阵

Text/AtReplyImageVideoFileForward
Text/At✅✅✅⚠️ 文本被吞⚠️ 文本被吞🔥 崩溃
Reply✅—✅❌ 视频被吞⚠️ 回复被吞🔥 崩溃
Image✅✅✅⚠️ 图片被吞⚠️ 图片被吞🔥 崩溃
Video⚠️❌⚠️—⚠️ 视频被吞🔥 崩溃
File⚠️⚠️⚠️⚠️✅ 拆多条⚠️ Forward被吞
Forward🔥🔥🔥🔥⚠️—

框架防护行为

模式崩溃级冲突 (Forward)吞段级冲突 (Video/File)
strict=False（默认）抛 QQSegmentConflictError自动拆为多条消息 + warning 日志
strict=True抛 QQSegmentConflictError抛 QQSegmentConflictError

自动拆分规则：

  1. 轻量段 + 视觉段 → 合为一条（Group A）
  2. Video → 单独一条（Group B）
  3. File → 单独一条（Group C）
  4. Reply 若无可搭配内容段 → 丢弃 + warning

示例

# ⚠️ 以下组合会自动拆为两条消息（一条文本，一条视频）
await api.qq.post_group_msg(group_id, text="附带说明", video="video.mp4")

# ❌ 以下组合会抛异常（Forward 不能混入普通消息）
msg = MessageArray()
msg.add_segment(forward)
msg.add_text("hello")
await api.qq.post_group_array_msg(group_id, msg)  # → QQSegmentConflictError

# ✅ 正确：Forward 通过专用 API 发送
await api.qq.post_group_forward_msg(group_id, forward)

异常类

from ncatbot.api.qq.segment_validator import QQSegmentConflictError

try:
    await api.qq.post_group_array_msg(group_id, msg, strict=True)
except QQSegmentConflictError as e:
    print(f"段冲突: {e}")

版权归属：MI

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025-2026 NcatBot