概览

这里给出消息发送与获取相关接口。

事件对象已封装常用便捷方法（如 GroupMessageEvent.reply），本页列出底层异步 API，便于跨上下文调用。

依赖类型：MessageArray、Forward、Image、Record、PlainText 等，详见。

---

群聊发送

send_group_msg

• 功能: 发送群消息（底层直发，传 OneBot 片段字典列表）。
• 参数:
  • group_id: str | int
  • message: list[dict] OneBot 风格消息片段，例如 [{"type":"text","data":{"text":"hi"}}]
• 返回: str，message_id
• 示例：

await api.send_group_msg(123456, [{"type":"text","data":{"text":"hi"}}])

post_group_array_msg

• 功能: 使用 MessageArray 发送群消息。
• 参数:
  • group_id: str | int
  • msg: MessageArray
• 返回: str，message_id
• 示例：

msg = MessageArray().add_text("hello").add_image("/path/a.jpg")
await api.post_group_array_msg(123456, msg)

post_group_msg

• 功能: 快速组合群消息（文本/艾特/引用/图片/富文本）。
• 参数:
  • group_id: str | int
  • text: str | None
  • at: str | int | None 要 @ 的 QQ 号
  • reply: str | int | None 要引用的 message_id
  • image: str | None 图片本地路径或 URL
  • rtf: MessageArray | None 兼容旧富文本
• 返回: str，message_id
• 示例：

await api.post_group_msg(123456, text="hi", at=987654, reply=mid, image="https://.../a.png")
await api.post_group_msg(123456, text="hello")
await api.post_group_msg(123456, rtf=MessageArray().add_image("C:/a.jpg").add_text("hi"))

不需要的成分可以不填写。

send_group_text

• 功能: 群文本（支持 CQ 码）。
• 参数: group_id: str | int, text: str
• 返回: str，message_id
• 示例：

await api.send_group_text(123456, "[CQ:face,id=66] 大家好")

send_group_plain_text

• 功能: 群纯文本（不转义）。
• 参数: group_id: str | int, text: str
• 返回: str，message_id
• 示例：

await api.send_group_plain_text(123456, "<b>不会被解析</b>")

send_group_image

• 功能: 群图片。
• 参数: group_id: str | int, image: str 图片路径或 URL
• 返回: str，message_id
• 示例：

await api.send_group_image(123456, "C:/tmp/a.jpg")

参考

send_group_record

• 功能: 群语音。
• 参数: group_id: str | int, file: str 语音文件路径或 URL
• 返回: str，message_id
• 示例：

await api.send_group_record(123456, "/tmp/a.mp3")

参考

send_group_dice

• 功能: 群骰子（value 当前由端实现，传 1 占位）。
• 参数: group_id: str | int, value: int = 1
• 返回: str，message_id
• 示例：

await api.send_group_dice(123456)

send_group_rps

• 功能: 群猜拳（value 预留）。
• 参数: group_id: str | int, value: int = 1
• 返回: str，message_id
• 示例：

await api.send_group_rps(123456)

send_group_file

• 功能: 群文件。
• 参数: group_id: str | int, file: str 文件路径, name: str | None 文件名
• 返回: str，message_id
• 示例：

await api.send_group_file(123456, "./a.zip", name="包.zip")

参考

send_group_music

• 功能: 群音乐卡片（平台 qq/163）。
• 参数: group_id: str | int, type: Literal["qq","163"], id: int | str
• 返回: str，message_id
• 示例：

await api.send_group_music(123456, "qq", 123456789)

参考

send_group_custom_music

• 功能: 自定义音乐卡片。
• 参数: group_id: str | int, audio: str, url: str, title: str, content: str | None, image: str | None
• 返回: str，message_id
• 示例：

await api.send_group_custom_music(123456, audio="https://a.mp3", url="https://page", title="标题", content="副标题", image="https://img.jpg")

参考

send_group_forward_msg_by_id

• 功能: 通过消息 ID 列表构建并发送合并转发。
• 参数: group_id: str | int, messages: list[str | int]
• 返回: str，message_id
• 示例：

await api.send_group_forward_msg_by_id(123456, [1231, 1232, 1233])

send_group_forward_msg

• 功能: 发送合并转发（直接提供节点/新闻等原始结构）。
• 参数:
  • group_id: str | int: 群号
  • messages: list[dict]: OneBot 风格消息片段列表
  • news: list[str]: 前若干条消息内容预览。
  • prompt: str: 外显文本，（通常为 "[聊天记录]"）
  • summary: str: 底部介绍（通常为 "查看xxx条转发消息"）
  • source: str: 顶部介绍（通常为 "群聊的聊天记录"）
• 返回: str，message_id
• 示例：

await api.send_group_forward_msg(123456, messages=[...], news=[...], prompt="...", summary="...", source="...")

forward_group_single_msg

• 功能: 向群转发单条消息。
• 参数: group_id: str | int, message_id: str | int
• 返回: str，message_id
• 示例：

await api.forward_group_single_msg(123456, mid)

group_poke

• 功能: 群内戳一戳。
• 参数: group_id: str | int, user_id: str | int
• 返回: None
• 示例：

await api.group_poke(123456, 987654)

---

私聊发送

send_private_msg

• 功能: 发送私聊消息（底层直发）。
• 参数: user_id: str | int, message: list[dict]
• 返回: str，message_id
• 示例：

await api.send_private_msg(123, [{"type":"text","data":{"text":"hi"}}])

post_private_array_msg

• 功能: 以 MessageArray 发送私聊消息。
• 参数: user_id: str | int, msg: MessageArray
• 返回: str，message_id
• 示例：

msg = MessageArray().add_text("hi").add_image("/a.jpg")
await api.post_private_array_msg(123, msg)

post_private_msg

• 功能: 快速组合（文本/引用/图片/富文本）。
• 参数: user_id: str | int, text: str | None, reply: str | int | None, image: str | None, rtf: MessageArray | None
• 返回: str，message_id
• 示例：

await api.post_private_msg(123, text="hi", reply=mid, image="https://.../a.png")

参考post_group_msg。

send_private_text

• 功能: 私聊文本（支持 CQ 码）。
• 参数: user_id: str | int, text: str
• 返回: str，message_id
• 示例：

await api.send_private_text(123, "[CQ:face,id=66] hi")

send_private_plain_text

• 功能: 私聊纯文本（不转义）。
• 参数: user_id: str | int, text: str
• 返回: str，message_id
• 示例：

await api.send_private_plain_text(123, "<b>不会被解析</b>")

send_private_image

• 功能: 私聊图片。
• 参数: user_id: str | int, image: str
• 返回: str，message_id
• 示例：

await api.send_private_image(123, "C:/a.jpg")

参考

send_private_record

• 功能: 私聊语音。
• 参数: user_id: str | int, file: str
• 返回: str，message_id
• 示例：

await api.send_private_record(123, "/a.mp3")

参考

send_private_dice

• 功能: 私聊骰子。
• 参数: user_id: str | int, value: int = 1
• 返回: str，message_id
• 示例：

await api.send_private_dice(123)

send_private_rps

• 功能: 私聊猜拳。
• 参数: user_id: str | int, value: int = 1
• 返回: str，message_id
• 示例：

await api.send_private_rps(123)

send_private_file

• 功能: 私聊文件。
• 参数: user_id: str | int, file: str, name: str | None
• 返回: str，message_id
• 示例：

await api.send_private_file(123, "./a.zip", name="a.zip")

参考

send_private_music

• 功能: 私聊音乐卡片。
• 参数: user_id: str | int, type: Literal["qq","163"], id: int | str
• 返回: str，message_id
• 示例：

await api.send_private_music(123, "163", 987654)

参考

send_private_custom_music

• 功能: 自定义音乐卡片。
• 参数: user_id: str | int, audio: str, url: str, title: str, content: str | None, image: str | None
• 返回: str，message_id
• 示例：

await api.send_private_custom_music(123, audio="https://a.mp3", url="https://page", title="标题")

参考

send_private_forward_msg

• 功能: 发送私聊合并转发（自带节点等）。
• 参数: user_id: str | int, messages: list[dict], news: list[str], prompt: str, summary: str, source: str
• 返回: str，message_id
• 示例：

await api.send_private_forward_msg(123, messages=[...], news=[...], prompt="...", summary="...", source="...")

参考 send_group_forward_msg。

send_private_forward_msg_by_id

• 功能: 通过消息 ID 列表构建并发送私聊合并转发。
• 参数: user_id: str | int, messages: list[str | int]
• 返回: str，message_id
• 示例：

await api.send_private_forward_msg_by_id(123, [m1, m2])

forward_private_single_msg

• 功能: 向私聊转发单条消息。
• 参数: user_id: str | int, message_id: str | int
• 返回: str，message_id
• 示例：

await api.forward_private_single_msg(123, mid)

friend_poke

• 功能: 私聊戳一戳。
• 参数: user_id: str | int
• 返回: None
• 示例：

await api.friend_poke(123)

---

通用操作

send_poke

• 功能: 戳一戳（互斥：二选一）。
• 参数: group_id: str | int | None, user_id: str | int | None
• 返回: None
• 示例：

await api.send_poke(group_id=123456)  # 或 user_id=123

delete_msg

• 功能: 撤回/删除消息。
• 参数: message_id: str | int
• 返回: None
• 示例：

await api.delete_msg(mid)

set_msg_emoji_like

• 功能: 贴表情反应。
• 参数: message_id: str | int, emoji_id: str | int, set: bool = True
• 返回: None
• 示例：

await api.set_msg_emoji_like(mid, 128512)

---

消息获取

get_group_msg_history

• 功能: 拉取群历史消息。
• 参数: group_id: str | int, message_seq: str | int, number: int = 20, reverseOrder: bool = False
• 返回: list[GroupMessageEvent]
• 示例：

msgs = await api.get_group_msg_history(123456, message_seq=1000, number=20)

get_msg

• 功能: 获取单条消息详情。
• 参数: message_id: str | int
• 返回: BaseMessageEvent
• 示例：

evt = await api.get_msg(mid)

get_forward_msg

• 功能: 获取合并转发详情。
• 参数: message_id: str | int
• 返回: Forward
• 示例：

forward = await api.get_forward_msg(mid)

get_friend_msg_history

• 功能: 拉取私聊历史消息。
• 参数:
  • user_id: str | int： 对方 QQ 号
  • message_seq: str | int：消息 ID
  • number: int = 20：拉取数量
  • reverseOrder: bool = False：是否按时间正序返回
• 返回: list[PrivateMessageEvent]
• 示例：

msgs = await api.get_friend_msg_history(123, 1000, 20)

get_record

• 功能: 获取语音文件（互斥：file 与 file_id）。
• 参数:
  • file: str | None：文件路径
  • file_id: str | None：文件 ID
  • out_format: Literal["mp3","amr","wma","m4a","ogg","wav","flac","spx"] = "mp3"：输出格式
• 返回: Record
• 示例：

rec = await api.get_record(file_id="abc")

参考

get_image

• 功能: 获取图片文件（互斥：file 与 file_id）。
• 参数: file: str | None, file_id: str | None
• 返回: Image
• 示例：

img = await api.get_image(file_id="abc")

参考

fetch_emoji_like

提示

详细情况待完善

• 功能: 获取贴表情详情。
• 参数: message_id: str | int, emoji_id: str | int, emoji_type: str | int
• 返回: dict
• 示例：

detail = await api.fetch_emoji_like(mid, 128512, 1)

---

版权所有

版权归属：huan-yp

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