Message API
约 2236 字大约 7 分钟
2025-09-26
概览
这里给出消息发送与获取相关接口。
事件对象已封装常用便捷方法(如 GroupMessageEvent.reply),本页列出底层异步 API,便于跨上下文调用。
依赖类型:MessageArray、Forward、Image、Record、PlainText 等,详见。
群聊发送
send_group_msg
- 功能: 发送群消息(底层直发,传 OneBot 片段字典列表)。
- 参数:
group_id: str | intmessage: 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 | intmsg: 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 | inttext: str | Noneat: str | int | None要 @ 的 QQ 号reply: str | int | None要引用的 message_idimage: str | None图片本地路径或 URLrtf: 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 | Noneat: str | int | None要 @ 的 QQ 号reply: str | int | None要引用的 message_idimage: str | None图片本地路径或 URLrtf: 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")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_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:消息 IDcount: 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:文件 IDout_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
