事件参考

WebSocket 和 IPC 连接通过事件帧接收推送。HTTP 调用不提供事件订阅。

分类目录

分类	内容
消息	群消息、好友消息与群临时消息
好友通知	好友关系、撤回与名片点赞
群成员与管理	成员加入、离开、撤回与禁言
互动	表态、戳一戳、输入状态
文件	群文件上传
申请	好友申请、入群申请与邀请
账号与连接	QQ 上下线、连接状态

具体字段、适用条件与订阅权限见各分类页面。

{
  "type": "event",
  "data": {
    "post_type": "bot_online",
    "self_id": 123456789,
    "protocol_id": 0
  }
}

公共字段

字段	类型	说明
type	string	外层固定为 event
data.post_type	string	事件类别
data.self_id	integer	事件所属 QQ
data.protocol_id	integer	事件所属协议配置 ID，0 有效
data.sub_type	string	好友与群通知的具体类型；其他事件不一定包含

订阅权限

事件	权限	文档
group_message	group_message	消息事件
friend_message、group_temp_message	friend_message	消息事件
friend_notice	friend_event	通知事件、申请事件
group_notice	group_event	通知事件、申请事件
bot_online	bot_online	账号状态
bot_offline	bot_offline	账号状态
message_sent	按消息类型使用 group_message 或 friend_message	发送确认
system_event	system_event（需显式开启）	连接状态

只推送当前框架内已授权的事件。正向 WebSocket 在认证帧中声明权限；反向 WebSocket 初始开启表中的六项权限，可通过 plugin_info.permissions 替换；IPC 使用插件清单的 events 声明。连接格式见通信协议。

接收示例

socket.addEventListener('message', ({ data }) => {
  const frame = JSON.parse(data)
  if (frame.type !== 'event') return
  const event = frame.data
  if (event.post_type === 'group_message') {
    console.log(event.self_id, event.protocol_id, event.group_id, event.message)
  }
})

断线期间不保证补发事件。重新连接后应查询账号及业务状态；不要依赖未声明的 event_id、event_type 或 client_type 字段。