API

2024-01-15 16:59| 来源: 网络整理| 查看: 265

# 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": "参数值" } 1234

HTTP POST 表单格式:

param1=value¶m2=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 字段, 它们会有相同的值" } 12345678# 响应说明

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

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

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

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

其中, status 字段:

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

retcode 字段:

值说明0调用成功1已提交 async 处理其他操作失败, 具体原因可以看响应的 msg 和 wording 字段# 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客户端IDdevice_namestring设备名称device_kindstring设备类型# 好友信息# 获取陌生人信息

终结点：/get_stranger_info

参数

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

响应数据

字段名数据类型说明user_idint64QQ 号nicknamestring昵称sexstring性别, male 或 female 或 unknownageint32年龄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-消息类型, 支持 private、group , 分别对应私聊、群组, 如不传入, 则根据传入的 *_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消息idreal_idint32消息真实idmessage_typestring群消息时为group, 私聊消息为privatesenderobject发送者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" } 123456789101112131415161718192021222324# 发送合并转发 ( 群聊 )

终结点: /send_group_forward_msg

参数

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

响应数据

字段名数据类型说明message_idint64消息 IDforward_idstring转发消息 ID# 发送合并转发 ( 好友 )

终结点: /send_private_forward_msg

参数

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

响应数据

字段名数据类型说明message_idint64消息 IDforward_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.silkout_formatstring-要转换到的格式, 目前支持 mp3、amr、wma、m4a、spx、ogg、wav、flac

响应数据

字段名数据类型说明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_type 或 typestring-add 或 invite, 请求类型（需要和上报消息中的 sub_type 字段相符）approvebooleantrue是否同意请求／邀请reasonstring空拒绝理由（仅在拒绝时有效）

提示

该 API 无响应数据

响应数据

字段类型说明master_idint64父账号IDext_namestring用户昵称create_timeint64账号创建时间# 群信息

群信息相关 API

# 获取群信息

终结点：/get_group_info

参数

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

响应数据

提示

如果机器人尚未加入群, group_create_time, group_level, max_member_count 和 member_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性别, male 或 female 或 unknownageint32年龄areastring地区join_timeint32加群时间戳last_sent_timeint32最后发言时间戳levelstring成员等级rolestring角色, owner 或 admin 或 memberunfriendlyboolean是否不良记录成员titlestring专属头衔title_expire_timeint64专属头衔过期时间戳card_changeableboolean是否允许修改群名片shut_up_timestampint64禁言到期时间# 获取群成员列表

终结点：/get_group_member_list

参数

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

响应数据

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

# 获取群荣誉信息

终结点：/get_group_honor_info

参数

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

响应数据

字段名数据类型说明group_idint64群号current_talkativeobject当前龙王, 仅 type 为 talkative 或 all 时有数据talkative_listarray历史龙王, 仅 type 为 talkative 或 all 时有数据performer_listarray群聊之火, 仅 type 为 performer 或 all 时有数据legend_listarray群聊炽焰, 仅 type 为 legend 或 all 时有数据strong_newbie_listarray冒尖小春笋, 仅 type 为 strong_newbie 或 all 时有数据emotion_listarray快乐之源, 仅 type 为 emotion 或 all 时有数据

其中 current_talkative 字段的内容如下：

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

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

字段名数据类型说明user_idint64QQ 号nicknamestring昵称avatarstring头像 URLdescriptionstring荣誉描述# 获取群系统消息

终结点: /get_group_system_msg

响应数据

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

注意

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

InvitedRequest

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

JoinRequest

字段类型说明request_idint64请求IDrequester_uinint64请求者IDrequester_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.jpgBase64 编码, 例如 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_flag 或 flagstring-可选, 要禁言的匿名用户的 flag（需从群消息上报的数据中获得）durationuint3230 * 60禁言时长, 单位秒, 无法取消匿名用户禁言

提示

上面的 anonymous 和 anonymous_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空间上限# 获取群根目录文件列表

提示

File 和 Folder 对象信息请参考最下方

终结点: /get_group_root_files

参数

字段类型说明group_idint64群号

响应数据

字段类型说明filesFile[]文件列表foldersFolder[]文件夹列表# 获取群子目录文件列表

提示

File 和 Folder 对象信息请参考最下方

终结点: /get_group_files_by_folder

参数

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

响应数据

字段类型说明filesFile[]文件列表foldersFolder[]文件夹列表# 获取群文件资源链接

提示

File 和 Folder 对象信息请参考最下方

终结点: /get_group_file_url

参数

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

响应数据

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

File

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

Folder

字段类型说明group_idint32群号folder_idstring文件夹IDfolder_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 的域名

响应数据

字段名数据类型说明cookiesstringCookiescsrf_tokenint32CSRF Token# 获取版本信息

终结点：/get_version_info

提示

该 API 无需参数

响应数据

字段名数据类型默认值说明app_namestringgo-cqhttp应用标识, 如 go-cqhttp 固定值app_versionstring应用版本, 如 v0.9.40-fix4app_full_namestring应用完整名称protocol_nameint6protocol_versionstringv11OneBot 标准版本固定值coolq_editionstringpro原Coolq版本固定值coolq_directorystringgo-cqhttpbooltrue是否为go-cqhttp 固定值plugin_versionstring4.15.0固定值plugin_build_numberint99固定值plugin_build_configurationstringrelease固定值runtime_versionstringruntime_osstringversionstring应用版本, 如 v0.9.40-fix4# 获取状态

终结点: /get_status

响应数据

字段类型说明app_initializedbool原 CQHTTP 字段, 恒定为 trueapp_enabledbool原 CQHTTP 字段, 恒定为 trueplugins_goodbool原 CQHTTP 字段, 恒定为 trueapp_goodbool原 CQHTTP 字段, 恒定为 trueonlinebool表示BOT是否在线goodbool同 onlinestatStatistics运行统计

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 请求会被中断, 因此需要异步地重启, 接口返回的 status 是 async。

参数

字段名数据类型默认值说明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" ] 1234

响应数据

字段类型说明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 没有响应数据

【本文地址】

API

API

今日新闻

推荐新闻