Skip to content

public.md

Latest commit

 

History

History
634 lines (430 loc) · 19.6 KB

public.md

File metadata and controls

634 lines (430 loc) · 19.6 KB

公开 API

send_private_msg 发送私聊消息

参数

字段名 数据类型 默认值 说明
user_id number - 对方 QQ 号
message message - 要发送的内容
auto_escape boolean false 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 message 字段是字符串时有效

响应数据

字段名 数据类型 说明
message_id number (int32) 消息 ID

send_group_msg 发送群消息

参数

字段名 数据类型 默认值 说明
group_id number - 群号
message message - 要发送的内容
auto_escape boolean false 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 message 字段是字符串时有效

响应数据

字段名 数据类型 说明
message_id number (int32) 消息 ID

send_msg 发送消息

参数

字段名 数据类型 默认值 说明
message_type string - 消息类型，支持 private、group，分别对应私聊、群组，如不传入，则根据传入的 *_id 参数判断
user_id number - 对方 QQ 号（消息类型为 private 时需要）
group_id number - 群号（消息类型为 group 时需要）
message message - 要发送的内容
auto_escape boolean false 消息内容是否作为纯文本发送（即不解析 CQ 码），只在 message 字段是字符串时有效

响应数据

字段名 数据类型 说明
message_id number (int32) 消息 ID

delete_msg 撤回消息

参数

字段名 数据类型 默认值 说明
message_id number (int32) - 消息 ID

响应数据

无

get_msg 获取消息

参数

字段名 数据类型 说明
message_id number (int32) 消息 ID

响应数据

字段名 数据类型 说明
time number (int32) 发送时间
message_type string 消息类型，同 消息事件
message_id number (int32) 消息 ID
real_id number (int32) 消息真实 ID
sender object 发送人信息，同 消息事件
message message 消息内容

get_forward_msg 获取合并转发消息

参数

字段名 数据类型 说明
id string 合并转发 ID

响应数据

字段名 类型 说明
message message 消息内容，使用 消息的数组格式 表示，数组中的消息段全部为 node 消息段

send_like 发送好友赞

参数

字段名 数据类型 默认值 说明
user_id number - 对方 QQ 号
times number 1 赞的次数，每个好友每天最多 10 次

响应数据

无

set_group_kick 群组踢人

参数

字段名 数据类型 默认值 说明
group_id number - 群号
user_id number - 要踢的 QQ 号
reject_add_request boolean false 拒绝此人的加群请求

响应数据

无

set_group_ban 群组单人禁言

参数

字段名 数据类型 默认值 说明
group_id number - 群号
user_id number - 要禁言的 QQ 号
duration number 30 * 60 禁言时长，单位秒，0 表示取消禁言

响应数据

无

set_group_anonymous_ban 群组匿名用户禁言

参数

字段名 数据类型 默认值 说明
group_id number - 群号
anonymous object - 可选，要禁言的匿名用户对象（群消息上报的 anonymous 字段）
anonymous_flag 或 flag string - 可选，要禁言的匿名用户的 flag（需从群消息上报的数据中获得）
duration number 30 * 60 禁言时长，单位秒，无法取消匿名用户禁言

上面的 anonymous 和 anonymous_flag 两者任选其一传入即可，若都传入，则使用 anonymous。

响应数据

无

set_group_whole_ban 群组全员禁言

参数

字段名 数据类型 默认值 说明
group_id number - 群号
enable boolean true 是否禁言

响应数据

无

set_group_admin 群组设置管理员

参数

字段名 数据类型 默认值 说明
group_id number - 群号
user_id number - 要设置管理员的 QQ 号
enable boolean true true 为设置，false 为取消

响应数据

无

set_group_anonymous 群组匿名

参数

字段名 数据类型 默认值 说明
group_id number - 群号
enable boolean true 是否允许匿名聊天

响应数据

无

set_group_card 设置群名片（群备注）

参数

字段名 数据类型 默认值 说明
group_id number - 群号
user_id number - 要设置的 QQ 号
card string 空 群名片内容，不填或空字符串表示删除群名片

响应数据

无

set_group_name 设置群名

参数

字段名 数据类型 说明
group_id number (int64) 群号
group_name string 新群名

响应数据

无

set_group_leave 退出群组

参数

字段名 数据类型 默认值 说明
group_id number - 群号
is_dismiss boolean false 是否解散，如果登录号是群主，则仅在此项为 true 时能够解散

响应数据

无

set_group_special_title 设置群组专属头衔

参数

字段名 数据类型 默认值 说明
group_id number - 群号
user_id number - 要设置的 QQ 号
special_title string 空 专属头衔，不填或空字符串表示删除专属头衔
duration number -1 专属头衔有效期，单位秒，-1 表示永久，不过此项似乎没有效果，可能是只有某些特殊的时间长度有效，有待测试

响应数据

无

set_friend_add_request 处理加好友请求

参数

字段名 数据类型 默认值 说明
flag string - 加好友请求的 flag（需从上报的数据中获得）
approve boolean true 是否同意请求
remark string 空 添加后的好友备注（仅在同意时有效）

响应数据

无

set_group_add_request 处理加群请求／邀请

参数

字段名 数据类型 默认值 说明
flag string - 加群请求的 flag（需从上报的数据中获得）
sub_type 或 type string - add 或 invite，请求类型（需要和上报消息中的 sub_type 字段相符）
approve boolean true 是否同意请求／邀请
reason string 空 拒绝理由（仅在拒绝时有效）

响应数据

无

get_login_info 获取登录号信息

参数

无

响应数据

字段名 数据类型 说明
user_id number (int64) QQ 号
nickname string QQ 昵称

get_stranger_info 获取陌生人信息

参数

字段名 数据类型 默认值 说明
user_id number - QQ 号
no_cache boolean false 是否不使用缓存（使用缓存可能更新不及时，但响应更快）

响应数据

字段名 数据类型 说明
user_id number (int64) QQ 号
nickname string 昵称
sex string 性别，male 或 female 或 unknown
age number (int32) 年龄

get_friend_list 获取好友列表

参数

无

响应数据

响应内容为 JSON 数组，每个元素如下：

字段名 数据类型 说明
user_id number (int64) QQ 号
nickname string 昵称
remark string 备注名

get_group_info 获取群信息

参数

字段名 数据类型 默认值 说明
group_id number - 群号
no_cache boolean false 是否不使用缓存（使用缓存可能更新不及时，但响应更快）

响应数据

字段名 数据类型 说明
group_id number (int64) 群号
group_name string 群名称
member_count number (int32) 成员数
max_member_count number (int32) 最大成员数（群容量）

get_group_list 获取群列表

参数

无

响应数据

响应内容为 JSON 数组，每个元素和上面的 get_group_info 接口相同。

get_group_member_info 获取群成员信息

参数

字段名 数据类型 默认值 说明
group_id number - 群号
user_id number - QQ 号
no_cache boolean false 是否不使用缓存（使用缓存可能更新不及时，但响应更快）

响应数据

字段名 数据类型 说明
group_id number (int64) 群号
user_id number (int64) QQ 号
nickname string 昵称
card string 群名片／备注
sex string 性别，male 或 female 或 unknown
age number (int32) 年龄
area string 地区
join_time number (int32) 加群时间戳
last_sent_time number (int32) 最后发言时间戳
level string 成员等级
role string 角色，owner 或 admin 或 member
unfriendly boolean 是否不良记录成员
title string 专属头衔
title_expire_time number (int32) 专属头衔过期时间戳
card_changeable boolean 是否允许修改群名片

get_group_member_list 获取群成员列表

参数

字段名 数据类型 默认值 说明
group_id number (int64) - 群号

响应数据

响应内容为 JSON 数组，每个元素的内容和上面的 get_group_member_info 接口相同，但对于同一个群组的同一个成员，获取列表时和获取单独的成员信息时，某些字段可能有所不同，例如 area、title 等字段在获取列表时无法获得，具体应以单独的成员信息为准。

get_group_honor_info 获取群荣誉信息

参数

字段名 数据类型 默认值 说明
group_id number (int64) - 群号
type string - 要获取的群荣誉类型，可传入 talkative performer legend strong_newbie emotion 以分别获取单个类型的群荣誉数据，或传入 all 获取所有数据

响应数据

字段名 数据类型 说明
group_id number (int64) 群号
current_talkative object 当前龙王，仅 type 为 talkative 或 all 时有数据
talkative_list array 历史龙王，仅 type 为 talkative 或 all 时有数据
performer_list array 群聊之火，仅 type 为 performer 或 all 时有数据
legend_list array 群聊炽焰，仅 type 为 legend 或 all 时有数据
strong_newbie_list array 冒尖小春笋，仅 type 为 strong_newbie 或 all 时有数据
emotion_list array 快乐之源，仅 type 为 emotion 或 all 时有数据

其中 current_talkative 字段的内容如下：

字段名 数据类型 说明
user_id number (int64) QQ 号
nickname string 昵称
avatar string 头像 URL
day_count number (int32) 持续天数

其它各 *_list 的每个元素是一个 JSON 对象，内容如下：

字段名 数据类型 说明
user_id number (int64) QQ 号
nickname string 昵称
avatar string 头像 URL
description string 荣誉描述

get_cookies 获取 Cookies

参数

字段名 数据类型 默认值 说明
domain string 空 需要获取 cookies 的域名

响应数据

字段名 数据类型 说明
cookies string Cookies

get_csrf_token 获取 CSRF Token

参数

无

响应数据

字段名 数据类型 说明
token number (int32) CSRF Token

get_credentials 获取 QQ 相关接口凭证

即上面两个接口的合并。

参数

字段名 数据类型 默认值 说明
domain string 空 需要获取 cookies 的域名

响应数据

字段名 数据类型 说明
cookies string Cookies
csrf_token number (int32) CSRF Token

get_record 获取语音

提示：要使用此接口，通常需要安装 ffmpeg，请参考 OneBot 实现的相关说明。

参数

字段名 数据类型 默认值 说明
file string - 收到的语音文件名（消息段的 file 参数），如 0B38145AA44505000B38145AA4450500.silk
out_format string - 要转换到的格式，目前支持 mp3、amr、wma、m4a、spx、ogg、wav、flac

响应数据

字段名 数据类型 说明
file string 转换后的语音文件路径，如 /home/somebody/cqhttp/data/record/0B38145AA44505000B38145AA4450500.mp3

get_image 获取图片

参数

字段名 数据类型 默认值 说明
file string - 收到的图片文件名（消息段的 file 参数），如 6B4DE3DFD1BD271E3297859D41C530F5.jpg

响应数据

字段名 数据类型 说明
file string 下载后的图片文件路径，如 /home/somebody/cqhttp/data/image/6B4DE3DFD1BD271E3297859D41C530F5.jpg

can_send_image 检查是否可以发送图片

参数

无

响应数据

字段名 数据类型 说明
yes boolean 是或否

can_send_record 检查是否可以发送语音

参数

无

响应数据

字段名 数据类型 说明
yes boolean 是或否

get_status 获取运行状态

参数

无

响应数据

字段名 数据类型 说明
online boolean 当前 QQ 在线，null 表示无法查询到在线状态
good boolean 状态符合预期，意味着各模块正常运行、功能正常，且 QQ 在线
…… - OneBot 实现自行添加的其它内容

通常情况下建议只使用 online 和 good 这两个字段来判断运行状态，因为根据 OneBot 实现的不同，其它字段可能完全不同。

get_version_info 获取版本信息

参数

无

响应数据

字段名 数据类型 说明
app_name string 应用标识，如 mirai-native
app_version string 应用版本，如 1.2.3
protocol_version string OneBot 标准版本，如 v11
…… - OneBot 实现自行添加的其它内容

set_restart 重启 OneBot 实现

由于重启 OneBot 实现同时需要重启 API 服务，这意味着当前的 API 请求会被中断，因此需要异步地重启，接口返回的 status 是 async。

参数

字段名 数据类型 默认值 说明
delay number 0 要延迟的毫秒数，如果默认情况下无法重启，可以尝试设置延迟为 2000 左右

响应数据

无

clean_cache 清理缓存

用于清理积攒了太多的缓存文件。

参数

无

响应数据

无

上一节 下一节
API 概述 隐藏 API
⚡