# API

# 基础传输

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

# 请求说明

使用 HTTP GET:

使用 HTTP POST:

HTTP POST JSON 格式:

{
    "参数名": "参数值",
    "参数名2": "参数值"

HTTP POST 表单格式:

param1=value&param2=value

使用 WebSocket:

WebSocket JSON 格式

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

# 响应说明

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

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

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

其中, status 字段:

retcode 字段:

# Bot 账号

有关 Bot 账号的相关 API

# 获取登录号信息

终结点： /get_login_info

响应数据

# 设置登录号资料

终结点： /set_qq_profile

# 获取企点账号信息

终结点: /qidian_get_account_info

# 获取在线机型

终结点： /_get_model_show

参数

响应数据

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

# 设置在线机型

终结点： /_set_model_show

参数

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

终结点： /get_online_clients

参数

响应数据

Device

# 好友信息

# 获取陌生人信息

终结点： /get_stranger_info

参数

响应数据

# 获取好友列表

终结点： /get_friend_list

响应数据

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

# 获取单向好友列表

终结点： /get_unidirectional_friend_list

响应数据

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

# 好友操作

好友操作 API

# 删除好友

终结点： /delete_friend

参数

# 删除单向好友

终结点： /delete_unidirectional_friend

参数

# 消息

有关消息操作的 API

# 发送私聊消息

终结点： /send_private_msg

参数

响应数据

# 发送群聊消息

终结点： /send_group_msg

参数

响应数据

# 发送消息

终结点： /send_msg

参数

响应数据

# 获取消息

终结点: /get_msg

参数

响应数据

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

# 撤回消息

终结点： /delete_msg

参数

# 标记消息已读

终结点: /mark_msg_as_read

参数

# 获取合并转发内容

终结点: /get_forward_msg

参数

响应数据

响应示例

{
    "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"

# 发送合并转发 ( 群聊 )

终结点: /send_group_forward_msg

参数

响应数据

# 发送合并转发 ( 好友 )

终结点: /send_private_forward_msg

参数

响应数据

# 获取群消息历史记录

终结点： /get_group_msg_history

参数

响应数据

# 图片

图片相关 API

# 获取图片信息

终结点: /get_image

参数

响应数据

# 检查是否可以发送图片

终结点： /can_send_image

响应数据

# 图片 OCR

终结点: /ocr_image 或 /.ocr_image

参数

响应数据

TextDetection

# 语音

语音相关 API

# 获取语音

终结点： /get_record

参数

响应数据

# 检查是否可以发送语音

终结点： /can_send_record

响应数据

# 处理

上报处理相关 API

# 处理加好友请求

终结点： /set_friend_add_request

参数

# 处理加群请求／邀请

终结点： /set_group_add_request

参数

响应数据

# 群信息

群信息相关 API

# 获取群信息

终结点： /get_group_info

参数

响应数据

# 获取群列表

终结点： /get_group_list

参数

响应数据

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

# 获取群成员信息

终结点： /get_group_member_info

参数

响应数据

# 获取群成员列表

终结点： /get_group_member_list

参数

响应数据

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

# 获取群荣誉信息

终结点： /get_group_honor_info

参数

响应数据

其中 current_talkative 字段的内容如下：

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

# 获取群系统消息

终结点: /get_group_system_msg

响应数据

InvitedRequest

JoinRequest

# 获取精华消息列表

终结点: /get_essence_msg_list

参数

响应数据

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

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

终结点: /get_group_at_all_remain

参数

响应数据

# 群设置

群设置相关 API

# 设置群名

终结点： /set_group_name

参数

# 设置群头像

终结点: /set_group_portrait

参数

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

• 绝对路径, 例如 file:///C:\\Users\Richard\Pictures\1.png , 格式使用 file URI open 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

参数

# 设置群名片 ( 群备注 )

终结点： /set_group_card

参数

# 设置群组专属头衔

终结点： /set_group_special_title

参数

# 群操作

群操作相关 API

# 群单人禁言

终结点： /set_group_ban

参数

# 群全员禁言

终结点： /set_group_whole_ban

参数

# 群匿名用户禁言

终结点： /set_group_anonymous_ban

参数

# 设置精华消息

终结点: /set_essence_msg

参数

# 移出精华消息

终结点: /delete_essence_msg

参数

# 群打卡

终结点： /send_group_sign

# 群设置匿名

终结点： /set_group_anonymous

参数

# 发送群公告

终结点： /_send_group_notice

参数

# 获取群公告

终结点： /_get_group_notice

参数

响应数据

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

其中 message 字段的内容如下：

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

# 群组踢人

终结点： /set_group_kick

参数

# 退出群组

终结点： /set_group_leave

参数

# 文件

# 上传群文件

终结点: /upload_group_file

参数

# 删除群文件

终结点: /delete_group_file

参数

# 创建群文件文件夹

终结点: /create_group_file_folder

参数

# 删除群文件文件夹

终结点: /delete_group_folder

# 获取群文件系统信息

终结点: /get_group_file_system_info

参数

响应数据

# 获取群根目录文件列表

终结点: /get_group_root_files

参数

响应数据

# 获取群子目录文件列表

终结点: /get_group_files_by_folder

参数

响应数据

# 获取群文件资源链接

终结点: /get_group_file_url

参数

响应数据

File

Folder

# 上传私聊文件

终结点: /upload_private_file

参数

# Go-CqHttp 相关

# 获取 Cookies

终结点： /get_cookies

参数

响应数据

# 获取 CSRF Token

终结点： /get_csrf_token

响应数据

# 获取 QQ 相关接口凭证

终结点： /get_credentials

参数

响应数据

# 获取版本信息

终结点： /get_version_info

响应数据

# 获取状态

终结点: /get_status

响应数据

Statistics

# 重启 Go-CqHttp

终结点： /set_restart

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

参数

# 清理缓存

终结点： /clean_cache

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

# 重载事件过滤器

终结点： /reload_event_filter

参数

# 下载文件到缓存目录

终结点: /download_file

参数

headers 格式:

字符串:

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

JSON数组:

[
    "User-Agent=YOUR_UA",