事件订阅详述

事件订阅是系统可以将软件中的消息或其他事件（加入、退出群事件和关注、取关机器人事件）推送到你的服务器中，你的服务器可以根据对应的消息或者事件做出相应的反应。
推送是通过HTTP协议以POST请求的方式推送JSON格式的数据

使用场景

你希望能对用户输入的内容做出相应反应时，比如当用户输入1+1=,你可以在服务器端收到这条消息，然后计算出结果，再通过消息发送接口告诉用户计算结果

事件列表

事件名称	介绍	取值	状态
普通消息事件	普通消息	message.receive.normal	可用
指令消息事件	指令消息	message.receive.instruction	可用
关注机器人事件	关注机器人事件	bot.followed	可用
取消关注机器人事件	取消关注机器人事件	bot.unfollowed	可用
加入群事件	用户加入群事件	group.join	可用
退出群事件	用户退出群事件	group.leave	可用
按钮事件	消息中按钮点击事件	button.report.inline	可用
快捷菜单事件	聊天框上方菜单按钮事件	bot.shortcut.menu	可用
机器人设置事件	机器人设置事件	bot.setting	可用
A2UI机器人按钮事件	A2UI机器消息中按钮点击事件	a2ui.button.report	可用

数据内容

字段	类型	说明
version	string	事件内容版本号，固定为 “1.0”
header	Header对象	包括事件的基础信息
event	Event对象	包括事件的内容。注意：Event对象的结构会在不同的eventType下发生变化

字段	类型	说明
eventId	string	事件ID，全局唯一
eventTime	int	事件产生的时间，毫秒13位时间戳
eventType	string	事件类型

一、普通消息事件 (message.receive.normal)

用户向机器人或机器人所在的群发送普通消息时触发。

触发场景

用户给机器人发送私聊消息
用户在机器人所在的群中发送消息

需要订阅

是（需在机器人后台开启”普通消息事件”订阅）

Event对象结构

字段	类型	说明
sender	Sender对象	发送者的信息
chat	Chat对象	聊天对象信息
message	Message对象	消息内容

Sender对象

字段	类型	说明
senderId	string	发送者ID，给用户回复消息需要该字段
senderType	string	发送者用户类型，取值：user
senderUserLevel	string	发送者级别，取值：owner（群主）、administrator（管理员）、member（普通成员）、unknown（未知）
senderNickname	string	发送者昵称
senderAvatarUrl	string	发送者头像URL

Chat对象

字段	类型	说明
chatId	string	聊天对象ID
chatType	string	聊天对象类型，取值: bot（机器人私聊）、group（群聊）

Message对象

字段	类型	说明
msgId	string	消息ID，全局唯一
parentId	string	引用消息时的父消息ID
sendTime	int	消息发送时间，毫秒13位时间戳
chatId	string	当前聊天的对象ID 单聊消息，chatId即机器人ID 群聊消息，chatId即群ID
chatType	string	当前聊天的对象类型 group 群聊 bot 机器人
contentType	string	当前消息类型 text 文本消息 image 图片消息 markdown Markdown消息 file 文件消息 video 视频消息 audio 语音消息 html HTML消息
content	Content对象	消息正文
instructionId	int	指令ID（普通消息为0）
instructionName	string	指令名称（普通消息为空）
commandId	int	指令ID，同instructionId
commandName	string	指令名称，同instructionName

Content对象（文本消息）

字段	类型	说明
text	string	消息正文
buttons	array	消息中包含的按钮列表（可选）
at	array	@用户ID列表（群聊消息可选）

Content对象（图片消息）

字段	类型	说明
imageUrl	string	图片URL
imageName	string	图片名称
imageKey	string	图片Key
imageWidth	int	图片宽度
imageHeight	int	图片高度

Content对象（文件消息）

字段	类型	说明
fileName	string	文件名
fileUrl	string	文件URL
fileKey	string	文件Key
fileSize	int	文件大小（字节）

Content对象（视频消息）

字段	类型	说明
videoUrl	string	视频URL
videoDuration	int	视频时长（秒）

Content对象（语音消息）

字段	类型	说明
audioUrl	string	语音URL
audioDuration	int	语音时长（秒）

JSON示例

文本消息示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def456",
        "eventTime": 1716000000000,
        "eventType": "message.receive.normal"
    },
    "event": {
        "sender": {
            "senderId": "user_001",
            "senderType": "user",
            "senderUserLevel": "member",
            "senderNickname": "张三",
            "senderAvatarUrl": "https://example.com/avatar.png"
        },
        "chat": {
            "chatId": "group_001",
            "chatType": "group"
        },
        "message": {
            "msgId": "msg_abc123",
            "parentId": "",
            "sendTime": 1716000000000,
            "chatId": "group_001",
            "chatType": "group",
            "contentType": "text",
            "content": {
                "text": "你好，这是一条测试消息"
            },
            "instructionId": 0,
            "instructionName": "",
            "commandId": 0,
            "commandName": ""
        }
    }
}

图片消息示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def457",
        "eventTime": 1716000001000,
        "eventType": "message.receive.normal"
    },
    "event": {
        "sender": {
            "senderId": "user_001",
            "senderType": "user",
            "senderUserLevel": "member",
            "senderNickname": "张三",
            "senderAvatarUrl": "https://example.com/avatar.png"
        },
        "chat": {
            "chatId": "bot_001",
            "chatType": "bot"
        },
        "message": {
            "msgId": "msg_abc124",
            "parentId": "",
            "sendTime": 1716000001000,
            "chatId": "bot_001",
            "chatType": "bot",
            "contentType": "image",
            "content": {
                "imageUrl": "https://example.com/image.webp",
                "imageName": "photo.jpg",
                "imageKey": "key_abc123",
                "imageWidth": 1920,
                "imageHeight": 1080
            },
            "instructionId": 0,
            "instructionName": "",
            "commandId": 0,
            "commandName": ""
        }
    }
}

二、指令消息事件 (message.receive.instruction)

用户发送带有指令的消息时触发。

触发场景

用户发送的消息匹配了机器人配置的指令规则

需要订阅

是（需在机器人后台开启”指令消息事件”订阅）

Event对象结构

与普通消息事件相同，但 instructionId 和 instructionName 字段有值。

JSON示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def458",
        "eventTime": 1716000002000,
        "eventType": "message.receive.instruction"
    },
    "event": {
        "sender": {
            "senderId": "user_001",
            "senderType": "user",
            "senderUserLevel": "member",
            "senderNickname": "张三",
            "senderAvatarUrl": "https://example.com/avatar.png"
        },
        "chat": {
            "chatId": "group_001",
            "chatType": "group"
        },
        "message": {
            "msgId": "msg_abc125",
            "parentId": "",
            "sendTime": 1716000002000,
            "chatId": "group_001",
            "chatType": "group",
            "contentType": "text",
            "content": {
                "text": "/help"
            },
            "instructionId": 1,
            "instructionName": "help",
            "commandId": 1,
            "commandName": "help"
        }
    }
}

三、关注机器人事件 (bot.followed)

用户关注（添加好友）机器人时触发。

触发场景

用户主动关注机器人
用户注册时自动关注机器人
用户同意机器人的好友申请

需要订阅

是（需在机器人后台开启”关注机器人事件”订阅）

Event对象结构

字段	类型	说明
time	int	事件发生时间，毫秒13位时间戳
chatId	string	用户ID
chatType	string	聊天类型，固定为 “private”
userId	string	关注用户的ID
nickname	string	关注用户的昵称
avatarUrl	string	关注用户的头像URL

JSON示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def459",
        "eventTime": 1716000003000,
        "eventType": "bot.followed"
    },
    "event": {
        "time": 1716000003000,
        "chatId": "user_001",
        "chatType": "private",
        "userId": "user_001",
        "nickname": "张三",
        "avatarUrl": "https://example.com/avatar.png"
    }
}

四、取消关注机器人事件 (bot.unfollowed)

用户取消关注（删除好友）机器人时触发。

触发场景

用户主动取消关注机器人
用户删除机器人好友

需要订阅

是（需在机器人后台开启”取消关注机器人事件”订阅）

Event对象结构

字段	类型	说明
time	int	事件发生时间，毫秒13位时间戳
chatId	string	用户ID
chatType	string	聊天类型，固定为 “private”
userId	string	取关用户的ID
nickname	string	取关用户的昵称
avatarUrl	string	取关用户的头像URL

JSON示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def460",
        "eventTime": 1716000004000,
        "eventType": "bot.unfollowed"
    },
    "event": {
        "time": 1716000004000,
        "chatId": "user_001",
        "chatType": "private",
        "userId": "user_001",
        "nickname": "张三",
        "avatarUrl": "https://example.com/avatar.png"
    }
}

五、加入群事件 (group.join)

用户加入群聊时触发。

触发场景

用户注册时自动加入群
用户被邀请加入群
用户通过好友申请自动加入群

需要订阅

是（需在机器人后台开启”加入群事件”订阅）

Event对象结构

字段	类型	说明
time	int	事件发生时间，毫秒13位时间戳
chatId	string	群ID
chatType	string	聊天类型，固定为 “group”
userId	string	加入用户的ID
nickname	string	加入用户的昵称
avatarUrl	string	加入用户的头像URL

JSON示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def461",
        "eventTime": 1716000005000,
        "eventType": "group.join"
    },
    "event": {
        "time": 1716000005000,
        "chatId": "group_001",
        "chatType": "group",
        "userId": "user_001",
        "nickname": "张三",
        "avatarUrl": "https://example.com/avatar.png"
    }
}

六、退出群事件 (group.leave)

用户退出群聊时触发。

触发场景

用户主动退出群
用户被踢出群
用户删除好友自动退群
机器人被移除出群

需要订阅

是（需在机器人后台开启”退出群事件”订阅）

Event对象结构

字段	类型	说明
time	int	事件发生时间，毫秒13位时间戳
chatId	string	群ID
chatType	string	聊天类型，固定为 “group”
userId	string	退出用户的ID
nickname	string	退出用户的昵称
avatarUrl	string	退出用户的头像URL

JSON示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def462",
        "eventTime": 1716000006000,
        "eventType": "group.leave"
    },
    "event": {
        "time": 1716000006000,
        "chatId": "group_001",
        "chatType": "group",
        "userId": "user_001",
        "nickname": "张三",
        "avatarUrl": "https://example.com/avatar.png"
    }
}

七、按钮事件 (button.report.inline)

用户点击消息中的内联按钮时触发。

触发场景

用户点击消息中 actionType=3（点击汇报）的按钮

需要订阅

否（始终发送，无需单独订阅）

Event对象结构

字段	类型	说明
time	int	事件发生时间，毫秒13位时间戳
msgId	string	按钮所在消息的ID
recvId	string	接收者ID（群ID或机器人ID）
recvType	string	接收者类型，取值：group（群）、bot（机器人）
userId	string	点击按钮的用户ID
value	string	按钮配置的value值

JSON示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def463",
        "eventTime": 1716000007000,
        "eventType": "button.report.inline"
    },
    "event": {
        "time": 1716000007000,
        "msgId": "msg_abc123",
        "recvId": "bot_001",
        "recvType": "bot",
        "userId": "user_001",
        "value": "confirm_action"
    }
}

八、快捷菜单事件 (bot.shortcut.menu)

用户点击机器人快捷菜单时触发。

触发场景

用户点击聊天框上方的机器人快捷菜单按钮

需要订阅

否（始终发送，无需单独订阅）

Event对象结构

字段	类型	说明
botId	string	机器人ID
menuId	string	菜单ID
menuType	int	菜单类型
menuAction	int	菜单动作类型
chatId	string	聊天对象ID（群ID或用户ID）
chatType	string	聊天对象类型，取值：group（群）、bot（机器人）
senderType	string	发送者类型，固定为 “user”
senderId	string	点击菜单的用户ID
sendTime	int	事件发生时间，毫秒13位时间戳

JSON示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def464",
        "eventTime": 1716000008000,
        "eventType": "bot.shortcut.menu"
    },
    "event": {
        "botId": "bot_001",
        "menuId": "menu_001",
        "menuType": 1,
        "menuAction": 1,
        "chatId": "group_001",
        "chatType": "group",
        "senderType": "user",
        "senderId": "user_001",
        "sendTime": 1716000008000
    }
}

九、A2UI表单事件 (a2ui.button.report)

用户在A2UI交互卡片中提交表单或点击操作时触发。

触发场景

用户在A2UI交互卡片中提交表单
用户在A2UI交互卡片中点击操作按钮

需要订阅

否（始终发送，无需单独订阅）

Event对象结构

字段	类型	说明
time	int	事件发生时间，毫秒13位时间戳
msgId	string	消息ID
recvId	string	接收者ID（群ID或机器人ID）
recvType	string	接收者类型，取值：group（群）、bot（机器人）
userId	string	操作用户的ID
actionName	string	操作名称
sourceComponentId	string	来源组件ID
formContext	object	表单上下文数据，键值对形式
interactionJson	string	交互数据的JSON字符串

JSON示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def465",
        "eventTime": 1716000009000,
        "eventType": "a2ui.button.report"
    },
    "event": {
        "time": 1716000009000,
        "msgId": "msg_abc126",
        "recvId": "bot_001",
        "recvType": "bot",
        "userId": "user_001",
        "actionName": "submit_form",
        "sourceComponentId": "form_001",
        "formContext": {
            "name": "张三",
            "phone": "13800138000",
            "email": "zhangsan@example.com"
        },
        "interactionJson": "{\"type\":\"form\",\"version\":\"1.0\"}"
    }
}

十、机器人设置事件 (bot.setting)

群内机器人设置被修改时触发。

触发场景

群管理员修改机器人在群内的设置

需要订阅

是（需在机器人后台开启”机器人设置事件”订阅）

Event对象结构

字段	类型	说明
time	int	事件发生时间，毫秒13位时间戳
chatId	string	群ID
chatType	string	聊天类型，固定为 “group”
groupId	string	群ID，同chatId
groupName	string	群名称
avatarUrl	string	群头像URL
settingJson	string	机器人设置的JSON字符串

JSON示例

{
    "version": "1.0",
    "header": {
        "eventId": "abc123def466",
        "eventTime": 1716000010000,
        "eventType": "bot.setting"
    },
    "event": {
        "time": 1716000010000,
        "chatId": "group_001",
        "chatType": "group",
        "groupId": "group_001",
        "groupName": "测试群",
        "avatarUrl": "https://example.com/group_avatar.png",
        "settingJson": "{\"notifyLevel\":1,\"autoReply\":true}"
    }
}

附录：消息类型对照表

contentType值	说明
text	文本消息
image	图片消息
markdown	Markdown消息
file	文件消息
video	视频消息
audio	语音消息
html	HTML消息
post	文章消息
expression	表情消息
form	表单消息
live_video	视频通话消息
live_audio	语音通话消息

附录：用户级别对照表

senderUserLevel值	说明
owner	群主
administrator	管理员
member	普通成员
unknown	未知

事件订阅详述

事件订阅详述

事件列表

数据内容

Header对象

一、普通消息事件 (message.receive.normal)

触发场景

需要订阅

Event对象结构

Sender对象

Chat对象

Message对象

Content对象（文本消息）

Content对象（图片消息）

Content对象（文件消息）

Content对象（视频消息）

Content对象（语音消息）

JSON示例

文本消息示例

图片消息示例

二、指令消息事件 (message.receive.instruction)

触发场景

需要订阅

Event对象结构

JSON示例

三、关注机器人事件 (bot.followed)

触发场景

需要订阅

Event对象结构

JSON示例

四、取消关注机器人事件 (bot.unfollowed)

触发场景

需要订阅

Event对象结构

JSON示例

五、加入群事件 (group.join)

触发场景

需要订阅

Event对象结构

JSON示例

六、退出群事件 (group.leave)

触发场景

需要订阅

Event对象结构

JSON示例

七、按钮事件 (button.report.inline)

触发场景

需要订阅

Event对象结构

JSON示例

八、快捷菜单事件 (bot.shortcut.menu)

触发场景

需要订阅

Event对象结构

JSON示例

九、A2UI表单事件 (a2ui.button.report)

触发场景

需要订阅

Event对象结构

JSON示例

十、机器人设置事件 (bot.setting)

触发场景

需要订阅

Event对象结构

JSON示例

附录：消息类型对照表

附录：用户级别对照表