Action 列表
OneBot v11 Action 是 Bot 框架向 Waylay 发送的 API 请求。
请求格式
{
"action": "get_login_info",
"params": {},
"echo": "unique_id"
}响应格式
{
"status": "ok",
"retcode": 0,
"data": { ... },
"echo": "unique_id"
}| retcode | 含义 |
|---|---|
| 0 | 成功 |
| 1400 | 请求处理错误 |
| 1404 | 不支持的 API |
核心
get_login_info
获取当前登录账号信息。
参数：无
响应：
{
"user_id": 123456789,
"nickname": "Bot昵称"
}get_version_info
响应：
{
"app_name": "waylay",
"app_version": "0.4.0",
"protocol_version": "v11"
}get_status
响应：
{
"online": true,
"good": true
}消息
send_msg
发送消息，自动判断私聊或群聊。
参数：
| 字段 | 类型 | 说明 |
|---|---|---|
message_type | string | private 或 group（可选，可从 group_id 推断） |
user_id | number | 私聊对象 QQ 号 |
group_id | number | 群号 |
message | array | 消息段数组 |
send_group_msg
参数：
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
message | array | 消息段数组 |
响应：
{
"message_id": 12345
}send_private_msg
参数：
| 字段 | 类型 | 说明 |
|---|---|---|
user_id | number | 对方 QQ 号 |
message | array | 消息段数组 |
delete_msg
撤回消息。
| 字段 | 类型 | 说明 |
|---|---|---|
message_id | number | 消息 ID |
get_msg
获取消息详情。
| 字段 | 类型 | 说明 |
|---|---|---|
message_id | number | 消息 ID |
send_group_forward_msg / send_private_forward_msg
发送合并转发消息。使用 NTQQ 原生 multiForwardMsgWithComment API，在群聊/私聊中显示为一条可展开的合并转发卡片。
实现原理：先将每个 node 的内容暂存到 Bot 自身私聊以获取 NT 消息 ID，再调用 multiForwardMsgWithComment 合并转发到目标。若合并转发失败则自动回退为逐条发送。
为什么需要暂存到自身私聊？
NTQQ 的 multiForwardMsgWithComment 要求 msgId 对应的消息必须存在于发送记录中（19 位 ID）。通过 addLocalRecordMsg 创建的本地记录（16 位 ID）会被 NTQQ 内核拒绝（Data Not Existed）。这是 wrapper.node 的硬性限制，NapCat 等项目也采用相同方案。
| 字段 | 类型 | 说明 |
|---|---|---|
group_id / user_id | number | 目标 |
messages | array | node 类型的消息数组 |
兼容多种 node 格式：
标准 OneBot v11 格式：
{
"type": "node",
"data": {
"content": [{ "type": "text", "data": { "text": "hello" } }],
"name": "发送者",
"uin": "123456"
}
}Yunzai / TRSS 格式（自动识别）：
{
"message": { "type": "image", "file": "https://..." },
"nickname": "发送者",
"user_id": 123456
}扁平段格式（如 { "type": "image", "file": "..." }）会自动标准化为 { "type": "image", "data": { "file": "..." } }。
好友 / 用户
get_friend_list
获取好友列表。从内存缓存返回，亚毫秒级响应。
响应：
[
{ "user_id": 111, "nickname": "张三", "remark": "备注" }
]get_stranger_info
| 字段 | 类型 | 说明 |
|---|---|---|
user_id | number | QQ 号 |
优先从好友缓存查找，对陌生人使用 5 秒超时的原生 API 调用，避免阻塞。
send_like
给好友点赞。
| 字段 | 类型 | 说明 |
|---|---|---|
user_id | number | 目标 QQ 号 |
times | number | 点赞次数（1-20，默认 1） |
set_friend_add_request
| 字段 | 类型 | 说明 |
|---|---|---|
flag | string | 请求标识 |
approve | boolean | 是否同意 |
群组
get_group_list
从内存缓存返回。
响应：
[
{ "group_id": 123, "group_name": "群名", "member_count": 50, "max_member_count": 200 }
]get_group_info
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
get_group_member_list
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
启动时预加载全部群的成员列表到缓存。
get_group_member_info
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
user_id | number | 成员 QQ 号 |
set_group_ban
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
user_id | number | 成员 QQ 号 |
duration | number | 禁言时长（秒，0 = 解禁） |
set_group_whole_ban
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
enable | boolean | 是否全体禁言 |
set_group_kick
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
user_id | number | 成员 QQ 号 |
reject_add_request | boolean | 是否拒绝再次加群 |
set_group_admin
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
user_id | number | 成员 QQ 号 |
enable | boolean | 设置/取消管理员 |
set_group_card / set_group_name / set_group_leave
分别设置群名片、群名、退群。参数同上述模式。
set_group_add_request
| 字段 | 类型 | 说明 |
|---|---|---|
flag | string | 请求标识（seq|groupCode|type 格式） |
approve | boolean | 是否同意 |
reason | string | 拒绝理由 |
group_poke
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
user_id | number | 目标 QQ 号 |
媒体
get_image / get_record
| 字段 | 类型 | 说明 |
|---|---|---|
file | string | 文件名 |
upload_group_file / upload_private_file
| 字段 | 类型 | 说明 |
|---|---|---|
group_id / user_id | number | 目标 |
file | string | 文件路径、URL 或 base64:// |
name | string | 显示文件名 |
支持的 file 格式：本地路径、file:// 协议、http(s):// URL、base64:// 编码数据。
错误处理
上传前会预检文件是否可读取：本地路径不存在会返回 File not found or unreadable: /path，URL 下载失败会返回 Failed to download file from URL: ...。上传大文件时 NTQQ 通过 BDH 异步传输，若 30 秒内未完成会返回 message_id: 0（文件仍在后台上传中）。
can_send_image / can_send_record
检查是否可以发送图片/语音。始终返回 { "yes": true }。
群文件
get_group_file_system_info
获取群文件系统信息。
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
响应：
{
"file_count": 96,
"limit_count": 10000,
"used_space": 747338724,
"total_space": 10737418240
}get_group_root_files
获取群根目录文件列表。
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
响应：
{
"files": [
{
"group_id": 123456,
"file_id": "/xxx-xxx",
"file_name": "example.pdf",
"busid": 102,
"file_size": 1024,
"upload_time": 0,
"dead_time": 0,
"modify_time": 1700000000,
"download_times": 5,
"uploader": 111222333,
"uploader_name": "张三"
}
],
"folders": [
{
"group_id": 123456,
"folder_id": "/xxx-xxx",
"folder_name": "资料",
"create_time": 1700000000,
"creator": 111222333,
"creator_name": "张三",
"total_file_count": 10
}
]
}get_group_files_by_folder
获取群子目录文件列表。
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
folder_id | string | 文件夹 ID（空或不传 = 根目录） |
响应格式同 get_group_root_files。
get_group_file_url
获取群文件下载链接。
WARNING
当前版本 NTQQ wrapper.node 未暴露文件 URL API，始终返回空。
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
file_id | string | 文件 ID |
busid | number | Bus ID（默认 102） |
delete_group_file
删除群文件。
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
file_id | string | 文件 ID |
busid | number | Bus ID（默认 102） |
create_group_file_folder
创建群文件夹。
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
name | string | 文件夹名称 |
move_group_file
移动群文件到指定文件夹。
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
file_id | string | 文件 ID |
folder_id | string | 目标文件夹 ID（空 = 根目录） |
busid | number | Bus ID（默认 102） |
WARNING
当前 QQ 3.2.27 版本的 wrapper.node 未暴露 moveGroupFile 方法，此 action 会返回 retcode: 1400。若未来 QQ 版本支持该方法，Waylay 会自动启用。
delete_group_folder
删除群文件夹。
| 字段 | 类型 | 说明 |
|---|---|---|
group_id | number | 群号 |
folder_id | string | 文件夹 ID |