CoolQ HTTP API 插件接口详解与使用指南

一、概述

CoolQ HTTP API 插件是一个基于 HTTP/HTTPS 协议的 CoolQ 机器人接口服务，它允许开发者通过 HTTP 请求与 CoolQ 进行交互，实现发送消息、管理群组、获取信息等功能。本文将详细介绍该插件的 API 使用方法、参数说明和响应处理。

二、请求方式与认证

2.1 请求方式支持

所有 API 都支持 GET 和 POST 两种请求方式（获取 data 目录文件的接口除外）。参数可以通过以下三种方式传递：

1. URL 参数：直接在 URL 中附加参数
2. 表单形式：使用 application/x-www-form-urlencoded Content-Type
3. JSON 形式：使用 application/json Content-Type，参数放在 JSON 对象顶层

推荐使用 JSON 方式，示例：

{
    "user_id": 123456,
    "message": "你好"
}

2.2 访问认证

如果配置了 access_token，需要在请求头中加入认证信息：

Authorization: Bearer your_access_token

或者通过 URL 参数传递：

/send_private_msg?access_token=your_access_token&user_id=123456&message=你好

三、响应处理

3.1 响应结构

所有响应均为 JSON 格式，基本结构如下：

{
    "status": "ok",
    "retcode": 0,
    "data": {...}
}

3.2 状态码说明

HTTP 状态码	说明
200	请求已处理（不代表操作成功）
401	未提供 access token
403	access token 不匹配
406	不支持的 Content-Type
400	请求正文格式错误
404	API 不存在

3.3 返回码说明

retcode	status	说明
0	ok	操作成功
1	async	已进入异步处理
>100	failed	HTTP API 插件判断的失败
<0	failed	CoolQ 函数返回的错误

常见错误码：

• 100：参数缺失或无效
• 102：返回数据无效（如无权限）
• 103：操作失败（权限不足等）
• 104：凭证失效
• 201：线程池未初始化

四、核心功能 API

4.1 消息发送

发送私聊消息

POST /send_private_msg
{
    "user_id": 123456,
    "message": "你好",
    "auto_escape": false
}

发送群消息

POST /send_group_msg
{
    "group_id": 123456,
    "message": "大家好",
    "auto_escape": false
}

通用发送接口

POST /send_msg
{
    "message_type": "private",
    "user_id": 123456,
    "message": "你好"
}

4.2 消息管理

撤回消息

POST /delete_msg
{
    "message_id": 123456789
}

4.3 群组管理

群组踢人

POST /set_group_kick
{
    "group_id": 123456,
    "user_id": 654321,
    "reject_add_request": true
}

禁言成员

POST /set_group_ban
{
    "group_id": 123456,
    "user_id": 654321,
    "duration": 1800
}

设置管理员

POST /set_group_admin
{
    "group_id": 123456,
    "user_id": 654321,
    "enable": true
}

五、信息获取 API

5.1 账号信息

获取登录号信息

GET /get_login_info

响应示例：

{
    "user_id": 123456,
    "nickname": "机器人"
}

5.2 群组信息

获取群列表

GET /get_group_list

获取群成员信息

POST /get_group_member_info
{
    "group_id": 123456,
    "user_id": 654321
}

六、高级功能

6.1 异步调用

在任何 API 后添加 _async 后缀可进行异步调用，如：

/send_private_msg_async

6.2 限速调用

添加 _rate_limited 后缀可进行限速调用，需在配置中开启：

enable_rate_limited_actions = true
rate_limit_interval = 500  # 毫秒

七、实用技巧

1. 消息格式处理：message 参数支持字符串、消息段数组或单个消息段对象
2. 缓存控制：信息获取接口可通过 no_cache 参数控制是否使用缓存
3. 语音处理：使用 /get_record 接口前需安装 CoolQ 语音组件
4. 状态监控：定期检查 /get_status 确保插件正常运行

八、注意事项

1. 部分操作虽然返回成功（retcode=0），但实际上可能未执行成功
2. 试验性 API（以_开头）稳定性较差，不建议生产环境使用
3. 隐藏 API（以.开头）仅供插件内部使用
4. 频繁操作可能导致腾讯封号，建议合理使用限速功能

通过本文的详细介绍，开发者可以全面了解 CoolQ HTTP API 插件的各项功能和使用方法，从而更高效地开发机器人应用。建议在实际开发中结合官方文档和社区资源，以获得最佳开发体验。