深入解析CoolQ HTTP API接口使用指南

深入解析CoolQ HTTP API接口使用指南

一、CoolQ HTTP API简介

CoolQ HTTP API是一个为QQ机器人开发者提供的高效接口系统，它通过HTTP协议将CoolQ的功能暴露出来，允许开发者使用各种编程语言与QQ进行交互。本指南将全面解析该API的使用方法，帮助开发者快速构建功能丰富的QQ机器人。

二、API请求规范

2.1 请求方式

CoolQ HTTP API同时支持GET和POST两种请求方式（获取data目录文件除外），参数可以通过以下三种方式传递：

1. URL查询参数（GET方式）
2. 表单数据（Content-Type: application/x-www-form-urlencoded）
3. JSON数据（Content-Type: application/json）

最佳实践建议：出于稳定性和类型安全的考虑，强烈推荐使用JSON格式传递参数，示例如下：

{
    "user_id": 123456,
    "message": "你好，这是一条测试消息"
}

2.2 身份验证

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

Authorization: Bearer your_access_token_here

或者通过URL参数传递：

/send_private_msg?access_token=your_token&user_id=123456&message=hello

三、响应处理机制

3.1 响应结构

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

{
    "status": "ok",
    "retcode": 0,
    "data": {
        // 具体返回数据
    }
}

3.2 状态码说明

| 状态码 | 含义 | 处理建议 | |--------|------|----------| | 200 | 请求已处理 | 检查retcode确定实际结果 | | 401 | 未提供access token | 检查请求头或URL参数 | | 403 | access token无效 | 核对配置文件中的token | | 406 | 不支持的Content-Type | 确保使用正确的内容类型 | | 400 | 请求体格式错误 | 检查JSON或表单数据格式 | | 404 | API不存在 | 检查API路径是否正确 |

3.3 返回码(retcode)详解

| retcode | 含义 | 常见场景 | |---------|------|----------| | 0 | 操作成功 | API调用正常完成 | | 1 | 异步执行 | 请求已提交但结果未知 | | 100 | 参数错误 | 缺少必填参数或参数无效 | | 102 | 数据无效 | 无权限获取目标数据 | | 103 | 操作失败 | 权限不足或文件系统异常 | | 104 | 凭证失效 | 需清除CoolQ缓存 | | 201 | 线程池异常 | 异步任务无法执行 |

四、核心API功能详解

4.1 消息发送功能

私聊消息发送

{
    "user_id": 123456,
    "message": "私聊测试",
    "auto_escape": false
}

参数说明：

• auto_escape：设为true时，消息内容将作为纯文本发送，不解析CQ码

群消息发送

{
    "group_id": 123456789,
    "message": "[CQ:at,qq=123456] 请查看群公告",
    "auto_escape": false
}

4.2 群组管理功能

群成员禁言

{
    "group_id": 123456789,
    "user_id": 987654,
    "duration": 600
}

注意事项：

• duration为0表示解除禁言
• 默认禁言时长为30分钟

群成员踢除

{
    "group_id": 123456789,
    "user_id": 987654,
    "reject_add_request": true
}

参数说明：

• reject_add_request：是否同时拒绝该用户的加群请求

4.3 请求处理功能

处理加群请求

{
    "flag": "请求标识符",
    "sub_type": "add",
    "approve": false,
    "reason": "不符合群规"
}

请求类型：

• add：加群请求
• invite：群邀请

五、高级功能特性

5.1 异步调用机制

所有API均可通过添加_async后缀实现异步调用，例如：

/send_private_msg_async

适用场景：

• 不需要立即获取结果的非关键操作
• 高并发场景下减轻服务器压力

5.2 限速调用机制

通过添加_rate_limited后缀启用限速调用：

/send_msg_rate_limited

配置参数：

• rate_limit_interval：控制调用间隔，默认500毫秒

最佳实践：

• 消息发送类API建议使用限速调用
• 避免因消息频率过高导致账号被封禁

六、实用工具API

6.1 多媒体处理

语音格式转换

{
    "file": "0B38145AA44505000B38145AA4450500.silk",
    "out_format": "mp3",
    "full_path": true
}

支持格式：mp3、amr、wma、m4a、spx、ogg、wav、flac

图片获取

{
    "file": "6B4DE3DFD1BD271E3297859D41C530F5.jpg"
}

6.2 系统状态监控

获取运行状态

响应示例：

{
    "app_initialized": true,
    "app_enabled": true,
    "online": true,
    "good": true
}

关键字段：

• online：QQ在线状态
• good：整体运行状态

七、实验性API说明

实验性API以_开头，稳定性较差，建议谨慎使用。

7.1 增强版群信息获取

{
    "group_id": 123456789
}

响应包含群分类、创建时间、管理员列表等扩展信息。

7.2 群公告管理

发布群公告

{
    "group_id": 123456789,
    "title": "重要通知",
    "content": "请全体成员注意..."
}

八、最佳实践建议

1. 错误处理：始终检查retcode并做好错误处理
2. 频率控制：消息类API使用限速调用
3. 缓存利用：适当使用no_cache参数平衡性能与实时性
4. 安全措施：务必配置access_token防止未授权访问
5. 异步优化：非关键操作使用异步API提升响应速度

通过本指南的详细解析，开发者可以全面掌握CoolQ HTTP API的各项功能，构建出稳定高效的QQ机器人应用。建议在实际开发中结合具体需求，合理选择API调用方式，并注意遵守QQ平台的相关规则。