API

基础传输

请求一个 API 时, 包含了: API 终结点, 以及 API 所需参数.

请求说明

使用 HTTP GET:

名称说明
请求 URL/终结点?参数名=参数值&参数名=参数值......
补充使用 GET 虽然简单, 但是你无法传入复杂的数据结构, 所以一些需要嵌套数据的 API 是无法通过 HTTP GET 来调用的, 例如 send_group_forward_msg 接口

使用 HTTP POST:

名称说明
请求 URL/终结点
请求体请求体可以使用 JSON 也可以使用 Form 表单, 需要注意的是, 请求的 Content-Type 是一定要设置准确的
补充同样, 在 POST 中, 如果要使用复杂的 API, 那么也需要使用 JSON 的格式, 表单格式是不支持数据嵌套的

HTTP POST JSON 格式:

{
    "参数名": "参数值",
    "参数名2": "参数值"
}
1
2
3
4

HTTP POST 表单格式:

param1=value&param2=value
1

使用 WebSocket:

名称说明
请求 URL这个其实说的是 websocket 建立连接时的 URL, 你可以连接 / 路径, 也可以连接 /api 路径, 他们的区别是 / 除了用来发送 api 和响应 api, 还提供上报功能
请求体一个 JSON 数据, 其中包含了请求 API 的终结点, 以及参数
补充在调用 api 时, 你还可以传入 "echo" 字段, 然后响应数据中也会有一个值相同的 "echo" 字段, 可以使用这个方式来甄别 "这个响应是哪个请求发出的", 你可以为每一个请求都使用一个唯一标识符来甄别

WebSocket JSON 格式

{
    "action": "终结点名称, 例如 'send_group_msg'",
    "params": {
        "参数名": "参数值",
        "参数名2": "参数值"
    },
    "echo": "'回声', 如果指定了 echo 字段, 那么响应包也会同时包含一个 echo 字段, 它们会有相同的值"
}
1
2
3
4
5
6
7
8

响应说明

使用 HTTP 调用 API 的时候, HTTP 的响应状态码:

说明
401access token 未提供
403access token 不符合
406Content-Type 不支持 (非 application/json 或 application/x-www-form-urlencoded
404API 不存在
200除上述情况外所有情况 (具体 API 调用是否成功, 需要看 API 的 响应数据

API 的响应是一个 JSON 数据, 如下:

{
    "status": "状态, 表示 API 是否调用成功, 如果成功, 则是 OK, 其他的在下面会说明",
    "retcode": 0,
    "msg": "错误消息, 仅在 API 调用失败时有该字段",
    "wording": "对错误的详细解释(中文), 仅在 API 调用失败时有该字段",
    "data": {
        "响应数据名": "数据值",
        "响应数据名2": "数据值",
    },
    "echo": "'回声', 如果请求时指定了 echo, 那么响应也会包含 echo"
}
1
2
3
4
5
6
7
8
9
10
11

其中, status 字段:

说明
okapi 调用成功
asyncapi 调用已经提交异步处理, 此时 retcode 为 1, 具体 api 调用是否成功无法得知
failedapi 调用失败

retcode 字段:

说明
0调用成功
1已提交 async 处理
其他操作失败, 具体原因可以看响应的 msgwording 字段

Bot 账号

有关 Bot 账号的相关 API

获取登录号信息

终结点:/get_login_info

提示

该 API 无需参数

响应数据

字段名数据类型说明
user_idint64QQ 号
nicknamestringQQ 昵称

设置登录号资料

终结点:/set_qq_profile

字段名数据类型默认值说明
nicknamestring-名称
companystring-公司
emailstring-邮箱
collegestring-学校
personal_notestring-个人说明

提示

该 API 没有响应数据

获取企点账号信息

注意

该API只有企点协议可用

终结点: /qidian_get_account_info

提示

该 API 无需参数

获取在线机型

提示

有关例子可从这个链接open in new window找到

终结点:/_get_model_show

参数

字段类型说明
modelstring机型名称

响应数据

字段类型说明
variantsarray-

响应内容为 JSON 数组,每个元素如下:

字段名数据类型说明
model_showstring-
need_payboolean-

设置在线机型

提示

有关例子可从这个链接open in new window找到

终结点:/_set_model_show

参数

字段类型说明
modelstring机型名称
model_showstring-

提示

该 API 没有响应数据

获取当前账号在线客户端列表

终结点:/get_online_clients

参数

字段类型说明
no_cachebool是否无视缓存

响应数据

字段类型说明
clientsDevice[]在线客户端列表

Device

字段类型说明
app_idint64客户端ID
device_namestring设备名称
device_kindstring设备类型

好友信息

获取陌生人信息

终结点:/get_stranger_info

参数

字段名数据类型默认值说明
user_idint64-QQ 号
no_cachebooleanfalse是否不使用缓存(使用缓存可能更新不及时, 但响应更快)

响应数据

字段名数据类型说明
user_idint64QQ 号
nicknamestring昵称
sexstring性别, malefemaleunknown
ageint32年龄
qidstringqid ID身份卡
levelint32等级
login_daysint32等级

获取好友列表

终结点:/get_friend_list

提示

该 API 无需参数

响应数据

响应内容为 json 数组, 每个元素如下:

字段名数据类型说明
user_idint64QQ 号
nicknamestring昵称
remarkstring备注名

获取单向好友列表

终结点:/get_unidirectional_friend_list

提示

该 API 无需参数

响应数据

响应内容为 json 数组, 每个元素如下:

字段名数据类型说明
user_idint64QQ 号
nicknamestring昵称
sourcestring来源

好友操作

好友操作 API

删除好友

终结点:/delete_friend

参数

字段名数据类型默认值说明
user_idint64-好友 QQ 号

提示

该 API 无响应数据

删除单向好友

终结点:/delete_unidirectional_friend

参数

字段类型说明
user_idint64单向好友QQ号

提示

该 API 没有响应数据

消息

有关消息操作的 API

发送私聊消息

终结点:/send_private_msg

参数

字段名数据类型默认值说明
user_idint64-对方 QQ 号
group_idint64-主动发起临时会话时的来源群号(可选, 机器人本身必须是管理员/群主)
messagemessage-要发送的内容
auto_escapebooleanfalse消息内容是否作为纯文本发送 ( 即不解析 CQ 码 ) , 只在 message 字段是字符串时有效

响应数据

字段名数据类型说明
message_idint32消息 ID

发送群聊消息

终结点:/send_group_msg

参数

字段名数据类型默认值说明
group_idint64-群号
messagemessage-要发送的内容
auto_escapebooleanfalse消息内容是否作为纯文本发送 ( 即不解析 CQ 码 ) , 只在 message 字段是字符串时有效

响应数据

字段名数据类型说明
message_idint32消息 ID

发送消息

终结点:/send_msg

参数

字段名数据类型默认值说明
message_typestring-消息类型, 支持 privategroup , 分别对应私聊、群组, 如不传入, 则根据传入的 *_id 参数判断
user_idint64-对方 QQ 号 ( 消息类型为 private 时需要 )
group_idint64-群号 ( 消息类型为 group 时需要 )
messagemessage-要发送的内容
auto_escapebooleanfalse消息内容是否作为纯文本发送 ( 即不解析 CQ 码 ) , 只在 message 字段是字符串时有效

响应数据

字段名数据类型说明
message_idint32消息 ID

获取消息

终结点: /get_msg

参数

字段类型说明
message_idint32消息id

响应数据

字段类型说明
groupbool是否是群消息
group_idint64是群消息时的群号(否则不存在此字段)
message_idint32消息id
real_idint32消息真实id
message_typestring群消息时为group, 私聊消息为private
senderobject发送者
timeint32发送时间
messagemessage消息内容
raw_messagemessage原始消息内容

其中sender字段包含两个字段:

字段类型说明
nicknamestring发送者昵称
user_idint64发送者 QQ 号

注意

在 go-cqhttp-v0.9.35~v0.9.36-fix3 版本中 raw_message 字段为 message_raw

在 go-cqhttp-v0.9.35以前的版本中不存在 message_raw 字段

在 go-cqhttp-v0.9.29-fix1 以前的版本可能不符合该文档

撤回消息

终结点:/delete_msg

参数

字段名数据类型默认值说明
message_idint32-消息 ID

提示

该 API 无响应数据

标记消息已读

终结点: /mark_msg_as_read

参数

字段类型说明
message_idint32消息id

提示

该 API 无响应数据

获取合并转发内容

终结点: /get_forward_msg

参数

字段类型说明
message_idstring消息id

提示

字段 message_id 对应合并转发open in new window中的 id 字段

响应数据

字段类型说明
messagesforward message[]消息列表

响应示例

{
    "data": {
        "messages": [
            {
                "content": "合并转发1",
                "sender": {
                    "nickname": "发送者A",
                    "user_id": 10086
                },
                "time": 1595694374
            },
            {
                "content": "合并转发2[CQ:image,file=xxxx,url=xxxx]",
                "sender": {
                    "nickname": "发送者B",
                    "user_id": 10087
                },
                "time": 1595694393
            }
        ]
    },
    "retcode": 0,
    "status": "ok"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

发送合并转发 ( 群聊 )

终结点: /send_group_forward_msg

参数

字段类型说明
group_idint64群号
messagesforward node[]自定义转发消息, 具体看 CQcodeopen in new window

响应数据

字段名数据类型说明
message_idint64消息 ID
forward_idstring转发消息 ID

发送合并转发 ( 好友 )

终结点: /send_private_forward_msg

参数

字段类型说明
user_idint64好友QQ号
messagesforward node[]自定义转发消息, 具体看 CQcodeopen in new window

响应数据

字段名数据类型说明
message_idint64消息 ID
forward_idstring转发消息 ID

获取群消息历史记录

终结点:/get_group_msg_history

参数

字段类型说明
message_seqint64起始消息序号, 可通过 get_msg 获得
group_idint64群号

响应数据

字段类型说明
messagesMessage[]从起始序号开始的前19条消息

提示

不提供起始序号将默认获取最新的消息

图片

图片相关 API

获取图片信息

终结点: /get_image

注意

该接口为 CQHTTP 接口修改

参数

字段类型说明
filestring图片缓存文件名

响应数据

字段类型说明
sizeint32图片源文件大小
filenamestring图片文件原名
urlstring图片下载地址

检查是否可以发送图片

终结点:/can_send_image

提示

该 API 无需参数

响应数据

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

图片 OCR

注意

目前图片OCR接口仅支持接受的图片

ocr_image API移除了实验模式, 目前版本 .ocr_image 和 ocr_image 均能访问, 后期将只保留后者.

go-cqhttp-v0.9.34更新日志open in new window

终结点: /ocr_image/.ocr_image

参数

字段类型说明
imagestring图片ID

响应数据

字段类型说明
textsTextDetection[]OCR结果
languagestring语言

TextDetection

字段类型说明
textstring文本
confidenceint32置信度
coordinatesvector2[]坐标

语音

语音相关 API

获取语音

注意

该 API 暂未被 go-cqhttp 支持, 您可以提交 pr 以使该 API 被支持 提交 propen in new window

终结点:/get_record

提示

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

参数

字段名数据类型默认值说明
filestring-收到的语音文件名(消息段的 file 参数), 如 0B38145AA44505000B38145AA4450500.silk
out_formatstring-要转换到的格式, 目前支持 mp3amrwmam4aspxoggwavflac

响应数据

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

检查是否可以发送语音

终结点:/can_send_record

提示

该 API 无需参数

响应数据

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

处理

上报处理相关 API

处理加好友请求

终结点:/set_friend_add_request

参数

字段名数据类型默认值说明
flagstring-加好友请求的 flag(需从上报的数据中获得)
approvebooleantrue是否同意请求
remarkstring添加后的好友备注(仅在同意时有效)

提示

该 API 无响应数据

处理加群请求/邀请

终结点:/set_group_add_request

参数

字段名数据类型默认值说明
flagstring-加群请求的 flag(需从上报的数据中获得)
sub_typetypestring-addinvite, 请求类型(需要和上报消息中的 sub_type 字段相符)
approvebooleantrue是否同意请求/邀请
reasonstring拒绝理由(仅在拒绝时有效)

提示

该 API 无响应数据

响应数据

字段类型说明
master_idint64父账号ID
ext_namestring用户昵称
create_timeint64账号创建时间

群信息

群信息相关 API

获取群信息

终结点:/get_group_info

参数

字段名数据类型默认值说明
group_idint64-群号
no_cachebooleanfalse是否不使用缓存(使用缓存可能更新不及时, 但响应更快)

响应数据

提示

如果机器人尚未加入群, group_create_time, group_level, max_member_countmember_count 将会为0

字段名数据类型说明
group_idint64群号
group_namestring群名称
group_memostring群备注
group_create_timeuint32群创建时间
group_leveluint32群等级
member_countint32成员数
max_member_countint32最大成员数(群容量)

提示

这里提供了一个API用于获取群图片, group_id 为群号 https://p.qlogo.cn/gh/{group_id}/{group_id}/100

注意

go-cqhttp-v0.9.40之前的版本中,该API不能获取陌生群消息

获取群列表

终结点:/get_group_list

参数

字段名数据类型默认值说明
no_cachebooleanfalse是否不使用缓存(使用缓存可能更新不及时, 但响应更快)

响应数据

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

获取群成员信息

终结点:/get_group_member_info

参数

字段名数据类型默认值说明
group_idint64-群号
user_idint64-QQ 号
no_cachebooleanfalse是否不使用缓存(使用缓存可能更新不及时, 但响应更快)

响应数据

字段名数据类型说明
group_idint64群号
user_idint64QQ 号
nicknamestring昵称
cardstring群名片/备注
sexstring性别, malefemaleunknown
ageint32年龄
areastring地区
join_timeint32加群时间戳
last_sent_timeint32最后发言时间戳
levelstring成员等级
rolestring角色, owneradminmember
unfriendlyboolean是否不良记录成员
titlestring专属头衔
title_expire_timeint64专属头衔过期时间戳
card_changeableboolean是否允许修改群名片
shut_up_timestampint64禁言到期时间

获取群成员列表

终结点:/get_group_member_list

参数

字段名数据类型默认值说明
group_idint64-群号
no_cachebooleanfalse是否不使用缓存(使用缓存可能更新不及时, 但响应更快)

响应数据

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

获取群荣誉信息

终结点:/get_group_honor_info

参数

字段名数据类型默认值说明
group_idint64-群号
typestring-要获取的群荣誉类型, 可传入 talkative performer legend strong_newbie emotion 以分别获取单个类型的群荣誉数据, 或传入 all 获取所有数据

响应数据

字段名数据类型说明
group_idint64群号
current_talkativeobject当前龙王, 仅 typetalkativeall 时有数据
talkative_listarray历史龙王, 仅 typetalkativeall 时有数据
performer_listarray群聊之火, 仅 typeperformerall 时有数据
legend_listarray群聊炽焰, 仅 typelegendall 时有数据
strong_newbie_listarray冒尖小春笋, 仅 typestrong_newbieall 时有数据
emotion_listarray快乐之源, 仅 typeemotionall 时有数据

其中 current_talkative 字段的内容如下:

字段名数据类型说明
user_idint64QQ 号
nicknamestring昵称
avatarstring头像 URL
day_countint32持续天数

其它各 *_list 的每个元素是一个 json 对象, 内容如下:

字段名数据类型说明
user_idint64QQ 号
nicknamestring昵称
avatarstring头像 URL
descriptionstring荣誉描述

获取群系统消息

终结点: /get_group_system_msg

响应数据

字段类型说明
invited_requestsInvitedRequest[]邀请消息列表
join_requestsJoinRequest[]进群消息列表

注意

如果列表不存在任何消息, 将返回 null

InvitedRequest

字段类型说明
request_idint64请求ID
invitor_uinint64邀请者
invitor_nickstring邀请者昵称
group_idint64群号
group_namestring群名
checkedbool是否已被处理
actorint64处理者, 未处理为0

JoinRequest

字段类型说明
request_idint64请求ID
requester_uinint64请求者ID
requester_nickstring请求者昵称
messagestring验证消息
group_idint64群号
group_namestring群名
checkedbool是否已被处理
actorint64处理者, 未处理为0

注意

go-cqhttp-v0.9.40 之前的版本中,无法获取被过滤的群系统消息

获取精华消息列表

终结点: /get_essence_msg_list

参数

字段类型说明
group_idint64群号

响应数据

响应内容为 JSON 数组,每个元素如下:

字段名数据类型说明
sender_idint64发送者QQ 号
sender_nickstring发送者昵称
sender_timeint64消息发送时间
operator_idint64操作者QQ 号
operator_nickstring操作者昵称
operator_timeint64精华设置时间
message_idint32消息ID

获取群 @全体成员 剩余次数

终结点: /get_group_at_all_remain

参数

字段类型说明
group_idint64群号

响应数据

字段类型说明
can_at_allbool是否可以 @全体成员
remain_at_all_count_for_groupint16群内所有管理当天剩余 @全体成员 次数
remain_at_all_count_for_uinint16Bot 当天剩余 @全体成员 次数

群设置

群设置相关 API

设置群名

终结点:/set_group_name

参数

字段名数据类型说明
group_idint64群号
group_namestring新群名

提示

该 API 无响应数据

设置群头像

终结点: /set_group_portrait

参数

字段类型说明
group_idint64群号
filestring图片文件名
cacheint表示是否使用已缓存的文件

[1] file 参数支持以下几种格式:

  • 绝对路径, 例如 file:///C:\\Users\Richard\Pictures\1.png, 格式使用 file URIopen in new window
  • 网络 URL, 例如 http://i1.piimg.com/567571/fdd6e7b6d93f1ef0.jpg
  • Base64 编码, 例如 base64://iVBORw0KGgoAAAANSUhEUgAAABQAAAAVCAIAAADJt1n/AAAAKElEQVQ4EWPk5+RmIBcwkasRpG9UM4mhNxpgowFGMARGEwnBIEJVAAAdBgBNAZf+QAAAAABJRU5ErkJggg==

[2] cache参数: 通过网络 URL 发送时有效, 1表示使用缓存, 0关闭关闭缓存, 默认 为1

[3] 目前这个API在登录一段时间后因cookie失效而失效, 请考虑后使用

设置群管理员

终结点:/set_group_admin

参数

字段名数据类型默认值说明
group_idint64-群号
user_idint64-要设置管理员的 QQ 号
enablebooleantruetrue 为设置, false 为取消

提示

该 API 无响应数据

设置群名片 ( 群备注 )

终结点:/set_group_card

参数

字段名数据类型默认值说明
group_idint64-群号
user_idint64-要设置的 QQ 号
cardstring群名片内容, 不填或空字符串表示删除群名片

提示

该 API 无响应数据

设置群组专属头衔

终结点:/set_group_special_title

参数

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

提示

该 API 无响应数据

群操作

群操作相关 API

群单人禁言

终结点:/set_group_ban

参数

字段名数据类型默认值说明
group_idint64-群号
user_idint64-要禁言的 QQ 号
durationuint3230 * 60禁言时长, 单位秒, 0 表示取消禁言

提示

该 API 无响应数据

群全员禁言

终结点:/set_group_whole_ban

参数

字段名数据类型默认值说明
group_idint64-群号
enablebooleantrue是否禁言

提示

该 API 无响应数据

群匿名用户禁言

注意

该 API 从 go-cqhttp-v0.9.36 开始支持

终结点:/set_group_anonymous_ban

参数

字段名数据类型默认值说明
group_idint64-群号
anonymousobject-可选, 要禁言的匿名用户对象(群消息上报的 anonymous 字段)
anonymous_flagflagstring-可选, 要禁言的匿名用户的 flag(需从群消息上报的数据中获得)
durationuint3230 * 60禁言时长, 单位秒, 无法取消匿名用户禁言

提示

上面的 anonymousanonymous_flag 两者任选其一传入即可, 若都传入, 则使用 anonymous

提示

该 API 无响应数据

设置精华消息

终结点: /set_essence_msg

参数

字段类型说明
message_idint32消息ID

提示

该 API 没有响应数据

移出精华消息

终结点: /delete_essence_msg

参数

字段类型说明
message_idint32消息ID

提示

该 API 没有响应数据

群打卡

终结点:/send_group_sign

字段名数据类型说明
group_idint64群号

提示

该 API 无响应数据

群设置匿名

终结点:/set_group_anonymous

参数

字段名数据类型默认值说明
group_idint64-群号
enablebooleantrue是否允许匿名聊天

提示

该 API 无响应数据

发送群公告

终结点: /_send_group_notice

参数

字段名数据类型默认值说明
group_idint64群号
contentstring公告内容
imagestring图片路径(可选)

提示

该 API 没有响应数据

获取群公告

终结点: /_get_group_notice

参数

字段名数据类型默认值说明
group_idint64群号

响应数据

响应内容为 json 数组,每个元素内容如下:

字段类型说明
sender_idint64公告发表者
publish_timeint64公告发表时间
messageobject公告内容

其中 message 字段的内容如下:

字段类型说明
textstring公告内容
imagesarray公告图片

其中 images 字段每个元素内容如下:

字段类型说明
heightstring图片高度
widthstring图片宽度
idstring图片ID

群组踢人

终结点:/set_group_kick

参数

字段名数据类型默认值说明
group_idint64-群号
user_idint64-要踢的 QQ 号
reject_add_requestbooleanfalse拒绝此人的加群请求

提示

该 API 无响应数据

退出群组

终结点:/set_group_leave

参数

字段名数据类型默认值说明
group_idint64-群号
is_dismissbooleanfalse是否解散, 如果登录号是群主, 则仅在此项为 true 时能够解散

提示

该 API 无响应数据

文件

上传群文件

终结点: /upload_group_file

参数

字段类型说明
group_idint64群号
filestring本地文件路径
namestring储存名称
folderstring父目录ID

注意

在不提供 folder 参数的情况下默认上传到根目录

只能上传本地文件, 需要上传 http 文件的话请先调用 download_file API下载

删除群文件

提示

File 对象信息请参考最下方

终结点: /delete_group_file

参数

字段类型说明
group_idint64群号
file_idstring文件ID 参考 File 对象
busidint32文件类型 参考 File 对象

提示

该 API 无响应数据

创建群文件文件夹

注意

仅能在根目录创建文件夹

终结点: /create_group_file_folder

参数

字段类型说明
group_idint64群号
namestring文件夹名称
parent_idstring仅能为 /

提示

该 API 无响应数据

删除群文件文件夹

提示

Folder 对象信息请参考最下方

终结点: /delete_group_folder

字段类型说明
group_idint64群号
folder_idstring文件夹ID 参考 Folder 对象

提示

该 API 无响应数据

获取群文件系统信息

终结点: /get_group_file_system_info

参数

字段类型说明
group_idint64群号

响应数据

字段类型说明
file_countint32文件总数
limit_countint32文件上限
used_spaceint64已使用空间
total_spaceint64空间上限

获取群根目录文件列表

提示

FileFolder 对象信息请参考最下方

终结点: /get_group_root_files

参数

字段类型说明
group_idint64群号

响应数据

字段类型说明
filesFile[]文件列表
foldersFolder[]文件夹列表

获取群子目录文件列表

提示

FileFolder 对象信息请参考最下方

终结点: /get_group_files_by_folder

参数

字段类型说明
group_idint64群号
folder_idstring文件夹ID 参考 Folder 对象

响应数据

字段类型说明
filesFile[]文件列表
foldersFolder[]文件夹列表

获取群文件资源链接

提示

FileFolder 对象信息请参考最下方

终结点: /get_group_file_url

参数

字段类型说明
group_idint64群号
file_idstring文件ID 参考 File 对象
busidint32文件类型 参考 File 对象

响应数据

字段类型说明
urlstring文件下载链接

File

字段类型说明
group_idint32群号
file_idstring文件ID
file_namestring文件名
busidint32文件类型
file_sizeint64文件大小
upload_timeint64上传时间
dead_timeint64过期时间,永久文件恒为0
modify_timeint64最后修改时间
download_timesint32下载次数
uploaderint64上传者ID
uploader_namestring上传者名字

Folder

字段类型说明
group_idint32群号
folder_idstring文件夹ID
folder_namestring文件名
create_timeint64创建时间
creatorint64创建者
creator_namestring创建者名字
total_file_countint32子文件数量

上传私聊文件

终结点: /upload_private_file

参数

字段类型说明
user_idint64对方 QQ 号
filestring本地文件路径
namestring文件名称

注意

只能上传本地文件, 需要上传 http 文件的话请先调用 download_file API下载

Go-CqHttp 相关

获取 Cookies

注意

该 API 暂未被 go-cqhttp 支持, 您可以提交 pr 以使该 API 被支持 提交 propen in new window

终结点:/get_cookies

参数

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

响应数据

字段名数据类型说明
cookiesstringCookies

获取 CSRF Token

注意

该 API 暂未被 go-cqhttp 支持, 您可以提交 pr 以使该 API 被支持 提交 propen in new window

终结点:/get_csrf_token

提示

该 API 无需参数

响应数据

字段名数据类型说明
tokenint32CSRF Token

获取 QQ 相关接口凭证

注意

该 API 暂未被 go-cqhttp 支持, 您可以提交 pr 以使该 API 被支持 提交 propen in new window

提示

即上面两个接口的合并

终结点:/get_credentials

参数

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

响应数据

字段名数据类型说明
cookiesstringCookies
csrf_tokenint32CSRF Token

获取版本信息

终结点:/get_version_info

提示

该 API 无需参数

响应数据

字段名数据类型默认值说明
app_namestringgo-cqhttp应用标识, 如 go-cqhttp 固定值
app_versionstring应用版本, 如 v0.9.40-fix4
app_full_namestring应用完整名称
protocol_nameint6
protocol_versionstringv11OneBot 标准版本 固定值
coolq_editionstringpro原Coolq版本 固定值
coolq_directorystring
go-cqhttpbooltrue是否为go-cqhttp 固定值
plugin_versionstring4.15.0固定值
plugin_build_numberint99固定值
plugin_build_configurationstringrelease固定值
runtime_versionstring
runtime_osstring
versionstring应用版本, 如 v0.9.40-fix4

获取状态

终结点: /get_status

响应数据

字段类型说明
app_initializedboolCQHTTP 字段, 恒定为 true
app_enabledboolCQHTTP 字段, 恒定为 true
plugins_goodboolCQHTTP 字段, 恒定为 true
app_goodboolCQHTTP 字段, 恒定为 true
onlinebool表示BOT是否在线
goodboolonline
statStatistics运行统计

Statistics

字段类型说明
packet_receiveduint64收到的数据包总数
packet_sentuint64发送的数据包总数
packet_lostuint32数据包丢失总数
message_receiveduint64接受信息总数
message_sentuint64发送信息总数
disconnect_timesuint32TCP 链接断开次数
lost_timesuint32账号掉线次数
last_message_timeint64最后一条消息时间

注意

所有统计信息都将在重启后重置

重启 Go-CqHttp

注意

该 API 由于技术原因,自 1.0.0 版本已被移除,目前暂时没有再加入的计划 #1230open in new window

终结点:/set_restart

由于重启 go-cqhttp 实现同时需要重启 API 服务, 这意味着当前的 API 请求会被中断, 因此需要异步地重启, 接口返回的 statusasync

参数

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

提示

该 API 无响应数据

清理缓存

注意

该 API 暂未被 go-cqhttp 支持, 您可以提交 pr 以使该 API 被支持 提交 propen in new window

终结点:/clean_cache

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

提示

该 API 无需参数也没有响应数据

重载事件过滤器

终结点:/reload_event_filter

参数

字段名数据类型默认值说明
filestring-事件过滤器文件

提示

该 API 没有响应数据

下载文件到缓存目录

终结点: /download_file

参数

字段类型说明
urlstring链接地址
thread_countint32下载线程数
headersstring or array自定义请求头

headers格式:

字符串:

User-Agent=YOUR_UA[\r\n]Referer=https://www.baidu.com
1

提示

[\r\n] 为换行符, 使用http请求时请注意编码

JSON数组:

[
    "User-Agent=YOUR_UA",
    "Referer=https://www.baidu.com"
]
1
2
3
4

响应数据

字段类型说明
filestring下载文件的绝对路径

提示

通过这个API下载的文件能直接放入CQ码作为图片或语音发送

调用后会阻塞直到下载完成后才会返回数据,请注意下载大文件时的超时

检查链接安全性

终结点:/check_url_safely

参数

字段类型说明
urlstring需要检查的链接

响应数据

字段类型说明
levelint安全等级, 1: 安全 2: 未知 3: 危险

获取中文分词 ( 隐藏 API )

警告

隐藏 API 是不建议一般用户使用的, 它们只应该在 OneBot 实现内部或由 SDK 和框架使用, 因为不正确的使用可能造成程序运行不正常。

终结点: /.get_word_slices

参数

字段类型说明
contentstring内容

响应数据

字段类型说明
slicesstring[]词组

对事件执行快速操作 ( 隐藏 API )

注意

隐藏 API 是不建议一般用户使用的, 它们只应该在 OneBot 实现内部或由 SDK 和框架使用, 因为不正确的使用可能造成程序运行不正常。

终结点:/.handle_quick_operation

关于事件的快速操作, 见 快速操作

参数

字段名数据类型默认值说明
contextobject-事件数据对象, 可做精简, 如去掉 message 等无用字段
operationobject-快速操作对象, 例如 {"ban": true, "reply": "请不要说脏话"}

提示

该 API 没有响应数据