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

项目概述

CoolQ HTTP API 是一个基于 HTTP 协议的 QQ 机器人接口，允许开发者通过 HTTP 请求与 QQ 进行交互。本文将全面解析该项目的 API 接口，帮助开发者快速掌握其使用方法。

接口请求基础

请求方式

CoolQ HTTP API 支持两种请求方式：

1. GET 请求：参数通过 URL 查询字符串传递
2. POST 请求：参数通过表单或 JSON 格式传递

推荐使用 JSON 格式的 POST 请求，示例：

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

身份验证

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

Authorization: Token your_access_token

或者通过 URL 参数传递：

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

响应格式解析

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

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

状态说明

字段	可能值	含义
status	"ok"	操作成功
	"async"	请求已提交异步处理
	"failed"	操作失败
retcode	0	成功
	1	异步处理中
	>0	HTTP API 插件判断的失败
	<0	酷 Q 原生错误码

核心功能接口详解

消息发送类接口

1. 发送私聊消息

接口路径：/send_private_msg

参数：

• user_id：目标用户QQ号
• message：消息内容
• auto_escape：是否作为纯文本发送（不解析CQ码）

响应：

• message_id：消息ID

2. 发送群消息

接口路径：/send_group_msg

参数：

• group_id：目标群号
• message：消息内容
• auto_escape：同上

3. 通用消息发送

接口路径：/send_msg

参数：

• message_type：消息类型（private/group/discuss）
• 根据类型选择user_id/group_id/discuss_id
• message：消息内容
• auto_escape：同上

群管理类接口

1. 群成员限制发言

接口路径：/set_group_ban

参数：

• group_id：群号
• user_id：目标用户
• duration：限制时长（秒），0表示解除限制

2. 群成员踢出

接口路径：/set_group_kick

参数：

• group_id：群号
• user_id：目标用户
• reject_add_request：是否拒绝再次加群

3. 设置群管理员

接口路径：/set_group_admin

参数：

• group_id：群号
• user_id：目标用户
• enable：true设置，false取消

信息获取类接口

1. 获取登录信息

接口路径：/get_login_info

响应：

• user_id：机器人QQ号
• nickname：机器人昵称

2. 获取群列表

接口路径：/get_group_list

响应：群组信息数组，包含群号和群名

3. 获取群成员信息

接口路径：/get_group_member_info

参数：

• group_id：群号
• user_id：目标用户
• no_cache：是否不使用缓存

响应：包含详细的成员信息，如昵称、群名片、角色等

高级特性

异步调用

所有接口均可通过添加 _async 后缀进行异步调用，如 /send_private_msg_async。异步调用会立即返回，实际操作将在后台执行。

试验性接口

以_开头的接口为试验性功能，包括：

• /_get_friend_list：获取好友列表
• /_get_group_info：获取群详细信息

这些接口可能不稳定，建议谨慎使用。

实用技巧

1. 消息撤回：使用 /delete_msg 接口，传入消息ID即可撤回消息
2. 处理加群请求：通过 /set_group_add_request 接口自动处理加群申请
3. 语音消息处理：使用 /get_record 接口转换语音格式
4. 快速操作：通过 /.handle_quick_operation 对事件进行快速响应

注意事项

1. 部分操作需要机器人具备相应权限（如管理员权限）
2. 语音相关功能需要额外安装语音组件
3. 试验性接口可能在未来版本中变更
4. 频繁操作可能触发QQ风控机制

通过本文的详细介绍，开发者应该能够全面了解 CoolQ HTTP API 的功能和使用方法，快速开发出功能丰富的QQ机器人应用。