onebot_v11/api/
payload.rs

1use crate::{event::message::Anonymous, traits::EndPoint, MessageSegment};
2use onebot_v11_macro::{endpoint, ApiDataDerive};
3use serde::{Deserialize, Serialize};
4
5#[derive(Debug, Clone, PartialEq, Eq, ApiDataDerive)]
6pub enum ApiPayload {
7    /// 发送私聊消息
8    SendPrivateMsg(SendPrivateMsg),
9    /// 发送群消息
10    SendGroupMsg(SendGroupMsg),
11    /// 发送消息
12    SendMsg(SendMsg),
13    /// 撤回消息
14    DeleteMsg(DeleteMsg),
15    /// 获取消息
16    GetMsg(GetMsg),
17    /// 获取合并转发消息
18    GetForwardMsg(GetForwardMsg),
19    /// 发送好友赞
20    SendLike(SendLike),
21    /// 群组踢人
22    SetGroupKick(SetGroupKick),
23    /// 群组禁言
24    SetGroupBan(SetGroupBan),
25    /// 群组匿名用户禁言
26    SetGroupAnonymousBan(SetGroupAnonymousBan),
27    /// 群组全员禁言
28    SetGroupWholeBan(SetGroupWholeBan),
29    /// 群组设置管理员
30    SetGroupAdmin(SetGroupAdmin),
31    /// 群组匿名
32    SetGroupAnonymous(SetGroupAnonymous),
33    /// 设置群名片（群备注）
34    SetGroupCard(SetGroupCard),
35    /// 设置群名
36    SetGroupName(SetGroupName),
37    /// 退出群组
38    SetGroupLeave(SetGroupLeave),
39    /// 设置群组专属头衔
40    SetGroupSpecialTitle(SetGroupSpecialTitle),
41    /// 处理加好友请求
42    SetFriendAddRequest(SetFriendAddRequest),
43    /// 处理加群请求／邀请
44    SetGroupAddRequest(SetGroupAddRequest),
45    /// 获取登录号信息
46    GetLoginInfo(GetLoginInfo),
47    /// 获取陌生人信息
48    GetStrangerInfo(GetStrangerInfo),
49    /// 获取好友列表
50    GetFriendList(GetFriendList),
51    /// 获取群信息
52    GetGroupInfo(GetGroupInfo),
53    /// 获取群列表
54    GetGroupList(GetGroupList),
55    /// 获取群成员信息
56    GetGroupMemberInfo(GetGroupMemberInfo),
57    /// 获取群成员列表
58    GetGroupMemberList(GetGroupMemberList),
59    /// 获取群荣誉信息
60    GetGroupHonorInfo(GetGroupHonorInfo),
61    /// 获取 Cookies
62    GetCookies(GetCookies),
63    /// 获取 CSRF Token
64    GetCsrfToken(GetCsrfToken),
65    /// 获取 QQ 相关接口凭证
66    GetCredentials(GetCredentials),
67    /// 获取语音
68    GetRecord(GetRecord),
69    /// 获取图片
70    GetImage(GetImage),
71    /// 检查是否可以发送图片
72    CanSendImage(CanSendImage),
73    /// 检查是否可以发送语音
74    CanSendRecord(CanSendRecord),
75    /// 获取运行状态
76    GetStatus(GetStatus),
77    /// 获取版本信息
78    GetVersionInfo(GetVersionInfo),
79    /// 重启 OneBot 实现
80    SetRestart(SetRestart),
81    /// 清理 OneBot 实现缓存
82    CleanCache(CleanCache),
83
84    // NapCat / llOneBot扩展
85    /// 设置头像
86    SetQQAvatar(SetQQAvatar),
87    /// 获取群系统通知
88    GetGroupSystemMsg(GetGroupSystemMsg),
89    /// 下载群文件或私聊文件
90    GetFile(GetFile),
91    /// 转发单条消息给好友
92    ForwardFriendSingleMsg(ForwardFriendSingleMsg),
93    /// 转发单条消息给群
94    ForwardGroupSingleMsg(ForwardGroupSingleMsg),
95    /// 设置表情回应
96    SetMsgEmojiLike(SetMsgEmojiLike),
97    /// 标记私聊消息为已读
98    MarkPrivateMsgAsRead(MarkPrivateMsgAsRead),
99    /// 标记群消息为已读
100    MarkGroupMsgAsRead(MarkGroupMsgAsRead),
101    /// 获取官方bot qq号范围
102    GetRobotUinRange(GetRobotUinRange),
103    /// 设置自身在线状态
104    SetOnlineStatus(SetOnlineStatus),
105    /// 获取好友分类列表
106    GetFriendsWithCategory(GetFriendsWithCategory),
107    /// 获取群文件数量
108    GetGroupFileCount(GetGroupFileCount),
109    /// 获取群文件列表
110    GetGroupFileList(GetGroupFileList),
111    /// 创建群文件夹
112    SetGroupFileFolder(SetGroupFileFolder),
113    /// 删除群文件
114    DelGroupFile(DelGroupFile),
115    /// 删除群文件夹
116    DelGroupFileFolder(DelGroupFileFolder),
117
118    /// NapCat / GoCq 拓展
119    /// 合并转发消息给群聊
120    SendGroupForwardMsg(SendGroupForwardMsg),
121    /// 合并转发消息给好友
122    SendPrivateForwardMsg(SendPrivateForwardMsg),
123}
124
125/// 发送私聊消息结构体
126#[endpoint("send_private_msg")]
127#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
128pub struct SendPrivateMsg {
129    /// 对方 QQ 号
130    pub user_id: i64,
131    /// 要发送的内容
132    pub message: Vec<MessageSegment>,
133    /// 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 message 字段是字符串时有效
134    pub auto_escape: bool,
135}
136
137/// 发送群消息结构体
138#[endpoint("send_group_msg")]
139#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
140pub struct SendGroupMsg {
141    /// 群号
142    pub group_id: i64,
143    /// 要发送的消息内容
144    pub message: Vec<MessageSegment>,
145    /// 消息内容是否作为纯文本发送（不解析 CQ 码）
146    pub auto_escape: bool,
147}
148
149#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
150pub enum MessageType {
151    #[serde(rename = "private")]
152    Private,
153    #[serde(rename = "group")]
154    Group,
155}
156
157/// 发送消息结构体
158#[endpoint("send_msg")]
159#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
160pub struct SendMsg {
161    /// 消息类型（private 或 group）
162    pub message_type: MessageType,
163    /// 对方 QQ 号（私聊时需要）
164    pub user_id: Option<i64>,
165    /// 群号（群聊时需要）
166    pub group_id: Option<i64>,
167    /// 要发送的消息内容
168    pub message: Vec<MessageSegment>,
169    /// 消息内容是否作为纯文本发送（不解析 CQ 码）
170    pub auto_escape: bool,
171}
172
173/// 撤回消息结构体
174#[endpoint("delete_msg")]
175#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
176pub struct DeleteMsg {
177    /// 消息 ID
178    pub message_id: i64,
179}
180
181/// 获取消息结构体
182#[endpoint("get_msg")]
183#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
184pub struct GetMsg {
185    /// 消息 ID
186    pub message_id: i64,
187}
188
189/// 获取合并转发消息结构体
190#[endpoint("get_forward_msg")]
191#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
192pub struct GetForwardMsg {
193    /// 合并转发 ID
194    pub id: String,
195}
196
197/// 发送好友赞结构体
198#[endpoint("send_like")]
199#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
200pub struct SendLike {
201    /// 对方 QQ 号
202    pub user_id: i64,
203    /// 赞的次数，每个好友每天最多 10 次
204    pub times: i64,
205}
206
207/// 群组踢人结构体
208#[endpoint("set_group_kick")]
209#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
210pub struct SetGroupKick {
211    /// 群号
212    pub group_id: i64,
213    /// 要踢的 QQ 号
214    pub user_id: i64,
215    /// 拒绝此人的加群请求
216    pub reject_add_request: bool,
217}
218
219/// 群组单人禁言结构体
220#[endpoint("set_group_ban")]
221#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
222pub struct SetGroupBan {
223    /// 群号
224    pub group_id: i64,
225    /// 要禁言的 QQ 号
226    pub user_id: i64,
227    /// 禁言时长，单位秒，0 表示取消禁言
228    pub duration: i64,
229}
230
231/// 群组匿名用户禁言结构体
232#[endpoint("set_group_anonymous_ban")]
233#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
234pub struct SetGroupAnonymousBan {
235    /// 群号
236    pub group_id: i64,
237    /// 可选，要禁言的匿名用户对象
238    pub anonymous: Option<Anonymous>,
239    /// 可选，要禁言的匿名用户的 flag
240    pub anonymous_flag: Option<String>,
241    /// 禁言时长，单位秒，无法取消匿名用户禁言
242    pub duration: i64,
243}
244
245/// 群组全员禁言结构体
246#[endpoint("set_group_whole_ban")]
247#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
248pub struct SetGroupWholeBan {
249    /// 群号
250    pub group_id: i64,
251    /// 是否禁言
252    pub enable: bool,
253}
254
255/// 群组设置管理员结构体
256#[endpoint("set_group_admin")]
257#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
258pub struct SetGroupAdmin {
259    /// 群号
260    pub group_id: i64,
261    /// 要设置管理员的 QQ 号
262    pub user_id: i64,
263    /// true 为设置，false 为取消
264    pub enable: bool,
265}
266
267/// 群组匿名结构体
268#[endpoint("set_group_anonymous")]
269#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
270pub struct SetGroupAnonymous {
271    /// 群号
272    pub group_id: i64,
273    /// 是否允许匿名聊天
274    pub enable: bool,
275}
276
277/// 设置群名片（群备注）结构体
278#[endpoint("set_group_card")]
279#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
280pub struct SetGroupCard {
281    /// 群号
282    pub group_id: i64,
283    /// 要设置的 QQ 号
284    pub user_id: i64,
285    /// 群名片内容，不填或空字符串表示删除群名片
286    pub card: String,
287}
288
289/// 设置群名结构体
290#[endpoint("set_group_name")]
291#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
292pub struct SetGroupName {
293    /// 群号
294    pub group_id: i64,
295    /// 新群名
296    pub group_name: String,
297}
298
299/// 退出群组结构体
300#[endpoint("set_group_leave")]
301#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
302pub struct SetGroupLeave {
303    /// 群号
304    pub group_id: i64,
305    /// 是否解散，如果登录号是群主，则仅在此项为 true 时能够解散
306    pub is_dismiss: bool,
307}
308
309/// 设置群组专属头衔结构体
310#[endpoint("set_group_special_title")]
311#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
312pub struct SetGroupSpecialTitle {
313    /// 群号
314    pub group_id: i64,
315    /// 要设置的 QQ 号
316    pub user_id: i64,
317    /// 专属头衔，不填或空字符串表示删除专属头衔
318    pub special_title: String,
319    /// 专属头衔有效期，单位秒，-1 表示永久，此项似乎没有效果，有待测试
320    pub duration: i64,
321}
322
323/// 处理加好友请求结构体
324#[endpoint("set_friend_add_request")]
325#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
326pub struct SetFriendAddRequest {
327    /// 加好友请求的 flag
328    pub flag: String,
329    /// 是否同意请求
330    pub approve: bool,
331    /// 添加后的好友备注（仅在同意时有效）
332    #[serde(skip_serializing_if = "Option::is_none")]
333    pub remark: Option<String>,
334}
335
336/// 处理加群请求／邀请结构体
337#[endpoint("    set_group_add_request")]
338#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
339pub struct SetGroupAddRequest {
340    /// 加群请求的 flag
341    pub flag: String,
342    /// 请求类型（add 或 invite）
343    pub sub_type: String,
344    /// 是否同意请求／邀请
345    pub approve: bool,
346    /// 拒绝理由（仅在拒绝时有效）
347    #[serde(skip_serializing_if = "Option::is_none")]
348    pub reason: Option<String>,
349}
350
351/// 获取登录号信息结构体
352#[endpoint("get_login_info")]
353#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
354pub struct GetLoginInfo {}
355
356/// 获取陌生人信息结构体
357#[endpoint("get_stranger_info")]
358#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
359pub struct GetStrangerInfo {
360    /// QQ 号
361    pub user_id: i64,
362    /// 是否不使用缓存
363    pub no_cache: bool,
364}
365
366/// 获取好友列表结构体
367#[endpoint("get_friend_list")]
368#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
369pub struct GetFriendList {}
370
371/// 获取群信息结构体
372#[endpoint("get_group_info")]
373#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
374pub struct GetGroupInfo {
375    /// 群号
376    pub group_id: i64,
377    /// 是否不使用缓存
378    pub no_cache: bool,
379}
380
381/// 获取群列表结构体
382#[endpoint("get_group_list")]
383#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
384pub struct GetGroupList {}
385
386/// 获取群成员信息结构体
387#[endpoint("get_group_member_info")]
388#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
389pub struct GetGroupMemberInfo {
390    /// 群号
391    pub group_id: i64,
392    /// QQ 号
393    pub user_id: i64,
394    /// 是否不使用缓存
395    pub no_cache: bool,
396}
397
398/// 获取群成员列表结构体
399#[endpoint("get_group_member_list")]
400#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
401pub struct GetGroupMemberList {
402    /// 群号
403    pub group_id: i64,
404}
405
406/// 获取群荣誉信息结构体
407#[endpoint("get_group_honor_info")]
408#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
409pub struct GetGroupHonorInfo {
410    /// 群号
411    pub group_id: i64,
412    /// 要获取的群荣誉类型
413    #[serde(rename = "type")]
414    pub honor_type: String,
415}
416
417/// 获取 Cookies 结构体
418#[endpoint("get_cookies")]
419#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
420pub struct GetCookies {
421    /// 需要获取 cookies 的域名
422    pub domain: String,
423}
424
425/// 获取 CSRF Token 结构体
426#[endpoint("get_csrf_token")]
427#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
428pub struct GetCsrfToken {}
429
430/// 获取 QQ 相关接口凭证结构体
431#[endpoint("get_credentials")]
432#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
433pub struct GetCredentials {
434    /// 需要获取 cookies 的域名
435    pub domain: String,
436}
437
438/// 获取语音结构体
439#[endpoint("get_record")]
440#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
441pub struct GetRecord {
442    /// 收到的语音文件名
443    pub file: String,
444    /// 要转换到的格式
445    pub out_format: String,
446}
447
448/// 获取图片结构体
449#[endpoint("get_image")]
450#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
451pub struct GetImage {
452    /// 收到的图片文件名
453    pub file: String,
454}
455
456/// 检查是否可以发送图片结构体
457#[endpoint("can_send_image")]
458#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
459pub struct CanSendImage {}
460
461/// 检查是否可以发送语音结构体
462#[endpoint("can_send_record")]
463#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
464pub struct CanSendRecord {}
465
466/// 获取运行状态结构体
467#[endpoint("get_status")]
468#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
469pub struct GetStatus {}
470
471/// 获取版本信息结构体
472#[endpoint("get_version_info")]
473#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
474pub struct GetVersionInfo {}
475
476/// 重启 OneBot 实现结构体
477#[endpoint("set_restart")]
478#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
479pub struct SetRestart {
480    /// 要延迟的毫秒数
481    pub delay: i64,
482}
483
484/// 清理缓存结构体
485#[endpoint("clean_cache")]
486#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
487pub struct CleanCache {}
488
489// NapCat / llOneBot扩展
490
491/// 设置头像✔
492#[endpoint("set_qq_avatar")]
493#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
494pub struct SetQQAvatar {
495    /// 图片路径/链接/base64
496    pub file: String,
497}
498
499/// 获取群系统通知✔
500#[endpoint("get_group_system_msg")]
501#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
502pub struct GetGroupSystemMsg {
503    /// 群号
504    pub group_id: i64,
505}
506
507/// 下载群文件或私聊文件
508#[endpoint("get_file")]
509#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
510pub struct GetFile {
511    /// 文件 ID
512    pub file_id: String,
513}
514
515/// 转发单条消息给好友✔
516#[endpoint("forward_friend_single_msg")]
517#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
518pub struct ForwardFriendSingleMsg {
519    /// 对方 QQ 号
520    pub user_id: i64,
521    /// 消息 ID
522    pub message_id: i64,
523}
524
525/// 转发单条消息给群✔
526#[endpoint("forward_group_single_msg")]
527#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
528pub struct ForwardGroupSingleMsg {
529    /// 群号
530    pub group_id: i64,
531    /// 消息 ID
532    pub message_id: i64,
533}
534
535/// 设置表情回应✔
536#[endpoint("set_msg_emoji_like")]
537#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
538pub struct SetMsgEmojiLike {
539    /// 消息 ID
540    pub message_id: String,
541    /// 表情 ID
542    /// 参考 https://bot.q.qq.com/wiki/develop/api-v2/openapi/emoji/model.html#EmojiType
543    pub emoji_id: String,
544}
545
546/// 设置私聊消息已读✔
547#[endpoint("mark_private_msg_as_read")]
548#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
549pub struct MarkPrivateMsgAsRead {
550    /// 对方 QQ 号
551    pub user_id: i64,
552}
553
554/// 设置群消息已读✔
555#[endpoint("mark_group_msg_as_read")]
556#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
557pub struct MarkGroupMsgAsRead {
558    /// 群号
559    pub group_id: i64,
560}
561
562/// 获取官方bot qq号范围✔
563#[endpoint("get_robot_uin_range")]
564#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
565pub struct GetRobotUinRange {}
566
567/// 设置自身在线状态✔
568/// 参考: https://napneko.github.io/zh-CN/develop/status_list
569#[endpoint("set_online_status")]
570#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
571pub struct SetOnlineStatus {
572    /// 在线状态
573    pub status: u32,
574    // 扩展在线状态
575    #[serde(rename = "extStatus")]
576    pub ext_status: u32,
577    /// 电量状态
578    #[serde(rename = "batteryStatus")]
579    pub battery_status: u32,
580}
581
582/// 获取好友分类列表(untested)
583#[endpoint("get_friends_with_category")]
584#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
585pub struct GetFriendsWithCategory {}
586
587/// 获取群文件数量✔
588#[endpoint("get_group_file_count")]
589#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
590pub struct GetGroupFileCount {
591    // 群号
592    pub group_id: i64,
593}
594
595/// 获取群文件列表✔
596#[endpoint("get_group_file_list")]
597#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
598pub struct GetGroupFileList {
599    /// 群号
600    pub group_id: i64,
601    /// 起始文件序号
602    pub start_index: i64,
603    /// 获取的文件数量
604    pub file_count: i64,
605}
606
607/// 创建群文件夹✔
608#[endpoint("set_group_file_folder")]
609#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
610pub struct SetGroupFileFolder {
611    /// 群号
612    pub group_id: i64,
613    /// 文件夹名称
614    pub folder_name: String,
615}
616
617/// 删除群文件✔
618#[endpoint("del_group_file")]
619#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
620pub struct DelGroupFile {
621    /// 群号
622    pub group_id: i64,
623    /// 文件 ID
624    pub file_id: String,
625}
626
627/// 删除群文件夹✔
628#[endpoint("del_group_file_folder")]
629#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
630pub struct DelGroupFileFolder {
631    /// 群号
632    pub group_id: i64,
633    /// 文件夹 ID
634    pub folder_id: String,
635}
636
637// NapCat GoCq 拓展
638
639/// 合并转发消息给群聊
640#[endpoint("send_group_forward_msg")]
641#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
642pub struct SendGroupForwardMsg {
643    /// 群号
644    pub group_id: i64,
645    /// 要发送的消息内容
646    pub messages: Vec<MessageSegment>,
647}
648
649/// 合并转发消息给好友
650#[endpoint("send_private_forward_msg")]
651#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
652pub struct SendPrivateForwardMsg {
653    /// 对方 QQ 号
654    pub user_id: i64,
655    /// 要发送的消息内容
656    pub messages: Vec<MessageSegment>,
657}
onebot_v11/api/payload.rs

onebot_v11/api/
payload.rs
