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 即可开启，见配置文件说明。

Files

API.md

Latest commit

History

API.md

File metadata and controls

API 说明

获取CoolQ对象

使用API

API 列表

sendPrivateMsg 发送私聊消息

参数

响应数据

sendGroupMsg 发送群消息

参数

响应数据

sendDiscussMsg 发送讨论组消息

参数

响应数据

sendMsg 发送消息

参数

响应数据

deleteMsg 撤回消息

参数

响应数据

sendLike 发送好友赞

参数

响应数据

setGroupKick 群组踢人

参数

响应数据

setGroupBan 群组单人禁言

参数

响应数据

setGroupAnonymousBan 群组匿名用户禁言

参数

响应数据

setGroupWholeBan 群组全员禁言

参数

响应数据

setGroupAdmin 群组设置管理员

参数

响应数据

setGroupAnonymous 群组匿名

参数

响应数据

setGroupCard 设置群名片（群备注）

参数

响应数据

setGroupLeave 退出群组

参数

响应数据

setGroupSpecialTitle 设置群组专属头衔

参数

响应数据

setDiscussLeave 退出讨论组

参数

响应数据

setFriendAddRequest 处理加好友请求

参数

响应数据

setGroupAddRequest 处理加群请求／邀请

参数

响应数据

getLoginInfo 获取登录号信息

参数

响应数据

getStrangerInfo 获取陌生人信息

参数

响应数据

getFriendList 获取好友列表

参数

响应数据

getGroupList 获取群列表

参数

响应数据

getGroupInfo 获取群信息

参数

响应数据

getGroupMemberInfo 获取群成员信息

`sendPrivateMsg` 发送私聊消息

`sendGroupMsg` 发送群消息

`sendDiscussMsg` 发送讨论组消息

`sendMsg` 发送消息

`deleteMsg` 撤回消息

`sendLike` 发送好友赞

`setGroupKick` 群组踢人

`setGroupBan` 群组单人禁言

`setGroupAnonymousBan` 群组匿名用户禁言

`setGroupWholeBan` 群组全员禁言

`setGroupAdmin` 群组设置管理员

`setGroupAnonymous` 群组匿名

`setGroupCard` 设置群名片（群备注）

`setGroupLeave` 退出群组

`setGroupSpecialTitle` 设置群组专属头衔

`setDiscussLeave` 退出讨论组

`setFriendAddRequest` 处理加好友请求

`setGroupAddRequest` 处理加群请求／邀请

`getLoginInfo` 获取登录号信息

`getStrangerInfo` 获取陌生人信息

`getFriendList` 获取好友列表

`getGroupList` 获取群列表

`getGroupInfo` 获取群信息

`getGroupMemberInfo` 获取群成员信息

`getGroupMemberList` 获取群成员列表

`getCookies` 获取 Cookies

`getCsrfToken` 获取 CSRF Token

`getCredentials` 获取 QQ 相关接口凭证

`getRecord` 获取语音

`getImage` 获取图片

`canSendImage` 检查是否可以发送图片

`canSendRecord` 检查是否可以发送语音

`getStatus` 获取插件运行状态

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

`setRestartPlugin` 重启 HTTP API 插件

`cleanDataDir` 清理数据目录

`cleanPluginLog` 清理插件日志