Message API

约 2236 字大约 7 分钟

2025-09-26

概览

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

事件对象已封装常用便捷方法（如 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_all_group_array_msg

功能: 向所有已加入的群发送 MessageArray 消息（慎用）。
参数:
- msg: MessageArray
返回: dict[str | int, str]，群号到 message_id 的映射
示例：

msg = MessageArray().add_text("hello").add_image("/path/a.jpg")
res = await api.post_all_group_array_msg(msg)
print(res)  # {"1234561": "12345671", "1234562": "12345672", ...}

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"))

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

post_all_group_msg

功能: 向所有已加入的群发送消息（慎用）。
参数:
- text: str | None
- at: str | int | None 要 @ 的 QQ 号
- reply: str | int | None 要引用的 message_id
- image: str | None 图片本地路径或 URL
- rtf: MessageArray | None 兼容旧富文本
返回: dict[str | int, str]，群号到 message_id 的映射
示例：

res = await api.post_all_group_msg(text="hello everyone", img="C:/a.jpg")
print(res)  # {"1234561": "12345671", "1234562": "12345672", ...}

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 则在指定群聊内戳一戳。
参数: user_id: str | int, group_id: str | int | None
返回: None
示例：

# 在群 123456 内戳用户 123
await api.send_poke(user_id=123, group_id=123456)

# 私聊戳用户 123
await api.send_poke(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, count: int = 20, reverseOrder: bool = False
返回: list[GroupMessageEvent]
示例：

msgs = await api.get_group_msg_history(123456, message_seq=1000, count=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
- count: 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: 目标消息的 ID。
- emoji_id: str | int: 要查询的表情 ID。
- emoji_type: str | int: 表情类型，通常为 1。

返回: dict，包含表情回应的详细信息。成功时 retcode 为 0，data 字段结构如下：

{
  "result": 0,
  "errMsg": "",
  "emojiLikesList": [
    {
      "tinyId": "", // 回应用户的qq号
      "nickName": "",     // 用户的昵称 (可能为空)
      "headUrl": ""       // 用户的头像 URL (可能为空)
    }
  ],
  "cookie": "",
  "isLastPage": true,
  "isFirstPage": true
}

示例：

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

版权所有

版权归属：huan-yp

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