通知事件

好友通知的 post_type 为 friend_notice，群通知为 group_notice；通过 sub_type 区分具体操作。

常见类型

post_type	sub_type	含义
friend_notice	increase、decrease	好友关系建立或删除
friend_notice	recall	好友消息撤回
friend_notice	like	收到名片赞
group_notice	increase、decrease	成员加入或离开
group_notice	recall	群消息撤回
group_notice	mute	禁言变更
group_notice	file_uploaded	群文件上传

申请通知的 apply 类型见申请事件。具体通知取决于 QQ 实际推送与账号权限。

通用通知字段

除 self_id、protocol_id、post_type 和 sub_type 外，群通知包含 group_id，并可能包含 group_name、operator、target、body。好友通知可能包含 user_id、user_uid、operator、target、body。

operator 与 target 使用 user_id、nickname，并可能包含 remark、card；body 随通知类型变化。字段缺失时不要猜测操作者或目标。

好友通知

以下事件需要 friend_event 权限。

新增好友

friend_notice / increase。顶层 user_id 为 QQ 号，user_uid 为 UID，operator 提供可用的昵称、备注。仅收到 UID 且本地不能解析 QQ 号时，user_id 可能省略；不要把 UID 当 QQ 号转换为数字。

删除好友

friend_notice / decrease。user_id、user_uid 标识好友，target 包含本地可用的好友资料。身份字段可能不完整，不据此推断由哪一方删除关系。

好友消息撤回

friend_notice / recall。顶层 user_id、user_uid 标识会话好友，operator 描述撤回者。

body 字段	类型	说明
msg_seq、client_seq	integer	服务端及客户端消息序号
msg_uid	string	QQ 消息 UID，保留字符串
msg_time	integer	消息时间，Unix 秒
msg_random	integer	消息随机值
prompt_text	string	提示文字，可能省略
traceless	boolean	无痕撤回标记，可能省略
original	object	缓存原文资料；原文不可用时消息段可能为“消息已过期”占位

original 不代表重新从 QQ 拉取到了原消息。不要将 body.msg_uid 当作本地 message_id。

名片点赞

当前限制

此通知当前可能缺失，不要仅凭未收到通知就判断没有获得点赞。

friend_notice / like。operator 描述点赞者；body 包含 text（string，提示内容）和 count（integer，当前解析到的点赞数量）。不要将 count 当作账号累计获赞数。

群成员与管理

以下事件需要 group_event 权限。

成员加入

group_notice / increase。顶层 group_id、user_id、nickname、request_id、request_type 描述群和加入者。可能包含 group_name、card，以及 invitor_id、handler_id 和对应的 nickname、card 字段。缺失邀请者或处理者时不要推断操作者。

成员离开

group_notice / decrease。顶层 group_id、user_id、nickname、request_id、request_type 描述群和离开者。可能包含 group_name、card，以及 operator_id、operator_nickname、operator_card。该通知不等于插件发起的移除请求回执。

群消息撤回

group_notice / recall。operator 和 target 按推送内容提供，body 包含 msg_seq、msg_time（Unix 秒）、msg_random，可能包含 prompt_text、original、operator_level、operator_role、operator_title。original 为缓存资料，缺失时不保证提供原文。

禁言变更

group_notice / mute。body 包含 duration（integer，秒）和 status（boolean），可能包含 op_suffix、xml_tip。根据返回内容显示禁言状态，不将字段缺失解释成操作成功；xml_tip 仅作为文本处理，不直接插入页面 HTML。

文件

群文件上传

group_notice / file_uploaded，需要 group_event 权限。group_id 表示所属群，operator 在资料可用时描述上传者。

body 字段	类型	说明
file_id	string	文件标识
file_name	string	文件名
file_size	integer	文件大小，字节
busid	integer	文件业务标识
msg_seq	integer	原生消息推送的消息序号；回读事件不提供
upload_time	integer	文件上传时间，Unix 秒；回读事件提供
parent_folder_id	string	上级文件夹标识；回读事件提供

原生文件推送与文件列表回读的字段不同。回读事件还包含顶层 source: "server_readback" 和 confirmed_at（Unix 毫秒）；不要把所有来源的可选字段一起列为必需，也不要混用 confirmed_at 与 upload_time 的时间单位。

通知扩展

收到通知后按所属账号和协议处理。

参与人的 uid 是字符串；只有已知 QQ 号时才提供 user_id。operator 或 target 缺失时不要推断身份。群扩展继续使用 group_event 权限，好友扩展继续使用 friend_event 权限。

管理员变更

group_notice / admin。target 为目标成员，body.set_admin（boolean）为 true 表示设置管理员，为 false 表示取消管理员。不保证提供 operator。

群名片变更

group_notice / card。target 为目标成员，body.card（string）为新名片；空字符串表示清空。operator 按推送内容提供。

群名称变更

group_notice / name。顶层 group_name 与 body.group_name（string）为新群名，operator 按推送内容提供。

群头衔变更

group_notice / title。target 为目标成员，body.title（string）为新头衔，可为空字符串；operator 按推送内容提供。

精华消息变更

group_notice / essence。body 包含 msg_seq、msg_random（integer）、operation（string，add 或 remove）和 time（integer，上游事件时间）。operator 为操作者、target 为原消息发送者，无法确认时可能省略。

群系统提示

group_notice / system_tip。body.summary（string）为提示摘要，body.participants（array，可省略）为提示中的参与人。参与人排列不能用于推断操作者、目标或管理员角色；不要根据摘要中的词语将其转换成另一种专门通知。

互动

按通知类型订阅群或好友事件权限。

消息表态

group_notice / reaction，使用 group_event 权限。operator 为操作者；body 包含：

字段	类型	说明
msg_seq	integer	目标消息序号，不是本地 message_id
emoji_id	string	表态标识
count	integer	推送中的表态数量，0 有效
operation	string	add 或 remove

戳一戳

群聊为 group_notice / poke，使用 group_event 权限；好友为 friend_notice / poke，使用 friend_event 权限。operator 和 target 为发起者与目标；body.action、body.suffix（string）为展示文字。不根据重复文字合并事件，也不把事件当作插件调用的成功回执。

输入状态

friend_notice / typing，使用 friend_event 权限。operator 为发起者；body 包含 state（integer，0 有效）、from_uid、to_uid（string）以及可选 text（string）。state 保留上游值，不应将所有非零值统一解释为“正在输入”。

已有通知的字段补充

以下字段按实际推送内容提供：

• 成员加入、离开可携带 user_uid；未映射到 QQ 号时省略 user_id。加入可携带 invitor_uid、handler_uid，离开可携带 operator_uid 和 reason（仅已知的 left 或 kicked）。未知操作者、原因与申请信息会省略；不能凭成员变更通知发起申请审批。
• 名片点赞仅在数量可确认时提供 body.count，并提供 body.count_source: "native_text"；数量无法确认时省略这两个字段，不代表点赞数为 0。

群名片、头衔和管理员通知还可能来自修改后的服务端回读。只有确认读取账号及目标成员均在群内、并读到实际值变化时才会产生；顶层 source 为 server_readback，confirmed_at 为 Unix 毫秒。回读不提供 operator，不能把调用接口的账号当成已知操作者。

回读有 15 秒总预算，超时、状态未变或无法确认成员身份时不产生通知。不保证每个观察账号都能收到通知，也不能把修改接口返回成功当作通知已发出的证明。