API 说明

这部分是从 https://cqhttp.cc/docs/4.14/#/API 抄过来改一改的

获取CoolQ对象

获取CoolQ对象，可以用plugin中的cq对象，也可以在CQGlobal中通过robots获取

CoolQ cq=CQGlobal.robots.get(875543533L);

使用API

• 不好解释，直接举例说明：

  // 不需要返回值的情况
  // 给875543533L发送私聊消息，解析CQ码
  cq.sendPrivateMsg(875543533L, "123", false);
  
  // 需要返回值的情况
  // 先输入下面这行
  cq.getGroupMemberInfo(335783090L, 875543533L, true).getData(); // 光标放在最后 
  // 然后按 Alt+Enter 选择Introduce local variable, 会自动添加赋值代码
  GroupMemberInfoData data = cq.getGroupMemberInfo(335783090L, 875543533L, true).getData();
  // 读取到以后可以使用 data.getXXX()
  String role = data.getRole(); // 获取群成员角色 owner admin member
  

API 列表

sendPrivateMsg 发送私聊消息

参数

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

响应数据

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

sendGroupMsg 发送群消息

参数

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

响应数据

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

sendDiscussMsg 发送讨论组消息

参数

字段名	数据类型	默认值	说明
discuss_id	number	-	讨论组 ID（正常情况下看不到，需要从讨论组消息上报的数据中获得）
message	message	-	要发送的内容
auto_escape	boolean	false	消息内容是否作为纯文本发送（即不解析 CQ 码），只在 message 字段是字符串时有效

响应数据

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

sendMsg 发送消息

参数

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

响应数据

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

deleteMsg 撤回消息

参数

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

响应数据

无

sendLike 发送好友赞

参数

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

响应数据

无

setGroupKick 群组踢人

参数

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

响应数据

无

setGroupBan 群组单人禁言

参数

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

响应数据

无

setGroupAnonymousBan 群组匿名用户禁言

参数

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

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

响应数据

无

setGroupWholeBan 群组全员禁言

参数

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

响应数据

无

setGroupAdmin 群组设置管理员

参数

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

响应数据

无

setGroupAnonymous 群组匿名

参数

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

响应数据

无

setGroupCard 设置群名片（群备注）

参数

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

响应数据

无

setGroupLeave 退出群组

参数

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

响应数据

无

setGroupSpecialTitle 设置群组专属头衔

参数

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

响应数据

无

setDiscussLeave 退出讨论组

参数

字段名	数据类型	默认值	说明
discuss_id	number	-	讨论组 ID（正常情况下看不到，需要从讨论组消息上报的数据中获得）

响应数据

无

setFriendAddRequest 处理加好友请求

参数

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

响应数据

无

setGroupAddRequest 处理加群请求／邀请

参数

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

响应数据

无

getLoginInfo 获取登录号信息

参数

无

响应数据

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

getStrangerInfo 获取陌生人信息

参数

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

响应数据

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

getFriendList 获取好友列表

参数

无

响应数据

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

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

getGroupList 获取群列表

参数

无

响应数据

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

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

getGroupInfo 获取群信息

参数

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

响应数据

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

getGroupMemberInfo 获取群成员信息

参数

字段名	数据类型	默认值	说明
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	是否允许修改群名片

getGroupMemberList 获取群成员列表

参数

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

响应数据

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

getCookies 获取 Cookies

参数

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

响应数据

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

getCsrfToken 获取 CSRF Token

参数

无

响应数据

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

getCredentials 获取 QQ 相关接口凭证

即上面两个接口的合并。

参数

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

响应数据

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

getRecord 获取语音

其实并不是真的获取语音，而是转换语音到指定的格式，然后返回语音文件名（data\record 目录下）。注意，要使用此接口，需要安装 酷Q 的 语音组件。

参数

字段名	数据类型	默认值	说明
file	string	-	收到的语音文件名（CQ 码的 file 参数），如 0B38145AA44505000B38145AA4450500.silk
out_format	string	-	要转换到的格式，目前支持 mp3、amr、wma、m4a、spx、ogg、wav、flac
full_path	boolean	false	是否返回文件的绝对路径（Windows 环境下建议使用，Docker 中不建议）

响应数据

字段名	数据类型	说明
file	string	转换后的语音文件名或路径，如 0B38145AA44505000B38145AA4450500.mp3，如果开启了 full_path，则如 C:\Apps\CoolQ\data\record\0B38145AA44505000B38145AA4450500.mp3

getImage 获取图片

参数

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

响应数据

字段名	数据类型	说明
file	string	下载后的图片文件路径，如 C:\Apps\CoolQ\data\image\6B4DE3DFD1BD271E3297859D41C530F5.jpg

canSendImage 检查是否可以发送图片

参数

无

响应数据

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

canSendRecord 检查是否可以发送语音

参数

无

响应数据

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

getStatus 获取插件运行状态

参数

无

响应数据

字段名	数据类型	说明
app_initialized	boolean	HTTP API 插件已初始化
app_enabled	boolean	HTTP API 插件已启用
plugins_good	object	HTTP API 的各内部插件是否正常运行
app_good	boolean	HTTP API 插件正常运行（已初始化、已启用、各内部插件正常运行）
online	boolean	当前 QQ 在线，null 表示无法查询到在线状态
good	boolean	HTTP API 插件状态符合预期，意味着插件已初始化，内部插件都在正常运行，且 QQ 在线

通常情况下建议只使用 online 和 good 这两个字段来判断运行状态，因为随着插件的更新，其它字段有可能频繁变化。

其中，online 字段的在线状态检测有两种方式，可通过 online_status_detection_method 配置项切换，默认通过读取 酷Q 日志数据库实现，可切换为 get_stranger_info 以通过测试陌生人查询接口的可用性来检测。具体区别如下：

在线检测方式	优点	缺点
get_stranger_info（默认）	正常情况下比 log_db 准确，但请求频率过高时可能变得不准确（在线被认为不在线）；需要发送网络请求	（几乎不可能）会因为 酷Q 更新而失效
log_db	查询速度较快；无需网络请求（不会触发腾讯风控）；不会因为请求频率过高而不准确	可能因为 酷Q 修改数据库表名、文件名而失效；月尾掉线，月初无法检测到

getVersionInfo 获取 酷Q 及 HTTP API 插件的版本信息

参数

无

响应数据

字段名	数据类型	说明
coolq_directory	string	酷Q 根目录路径
coolq_edition	string	酷Q 版本，air 或 pro
plugin_version	string	HTTP API 插件版本，例如 2.1.3
plugin_build_number	number	HTTP API 插件 build 号
plugin_build_configuration	string	HTTP API 插件编译配置，debug 或 release

setRestartPlugin 重启 HTTP API 插件

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

参数

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

响应数据

无

cleanDataDir 清理数据目录

用于清理积攒了太多旧文件的数据目录，如 image。

参数

字段名	数据类型	默认值	说明
data_dir	string	-	收到清理的目录名，支持 image、record、show、bface

响应数据

无

cleanPluginLog 清理插件日志

用于清空插件的日志文件。

参数

无

响应数据

无

不开启，在配置文件中将 serve_data_files 设置为 yes 或 true 即可开启，见 配置文件说明。