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

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

项目概述

CoolQ HTTP API 是一个为 QQ 机器人框架 CoolQ 设计的 HTTP 接口插件，它通过 HTTP 协议提供了一系列操作 QQ 的 API，使开发者能够使用各种编程语言来开发 QQ 机器人应用。

接口请求规范

请求方式

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

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

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

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

身份验证

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

Authorization: Bearer your_access_token

或者通过 URL 参数传递：

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

响应格式解析

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

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

状态说明

| 字段 | 可能值 | 说明 | |------|--------|------| | status | "ok", "async", "failed" | 操作状态 | | retcode | 数值 | 具体返回码 | | data | 对象/null | 返回数据 |

常见返回码

| retcode | 含义 | |---------|------| | 0 | 操作成功 | | 1 | 异步执行 | | 100 | 参数错误 | | 102 | 数据无效 | | 103 | 操作失败 | | 104 | 凭证失效 |

核心功能接口详解

消息发送类接口

发送私聊消息

• 接口：/send_private_msg
• 参数：
  • user_id: 接收者QQ号
  • message: 消息内容
  • auto_escape: 是否作为纯文本发送

发送群消息

• 接口：/send_group_msg
• 参数：
  • group_id: 群号
  • message: 消息内容
  • auto_escape: 同上

通用消息发送

• 接口：/send_msg
• 参数：
  • message_type: "private"/"group"/"discuss"
  • 对应类型的ID参数
  • message: 消息内容

群组管理接口

群成员禁言

• 接口：/set_group_ban
• 参数：
  • group_id: 群号
  • user_id: QQ号
  • duration: 禁言时长(秒)

设置群管理员

• 接口：/set_group_admin
• 参数：
  • group_id: 群号
  • user_id: QQ号
  • enable: true/false

修改群名片

• 接口：/set_group_card
• 参数：
  • group_id: 群号
  • user_id: QQ号
  • card: 新名片(空字符串表示删除)

信息获取接口

获取登录信息

• 接口：/get_login_info
• 返回：当前登录QQ号和昵称

获取群成员列表

• 接口：/get_group_member_list
• 参数：
  • group_id: 群号
• 返回：群成员详细信息数组

获取图片/语音文件

• 接口：/get_image 和 /get_record
• 参数：
  • file: 文件名
• 返回：文件路径

高级功能

异步调用

在任何接口URL后添加 _async 后缀可进行异步调用，适用于不需要即时结果的场景。

示例：/send_private_msg_async

限速调用

添加 _rate_limited 后缀可启用限速队列，特别适合消息发送接口以避免频率限制。

需要配置：

enable_rate_limited_actions=true
rate_limit_interval=500  # 毫秒

特殊接口说明

试验性接口

以 _ 开头的接口为试验性接口，稳定性较差，包括：

• 获取好友列表 /_get_friend_list
• 获取群公告 /_get_group_notice
• 发布群公告 /_send_group_notice

隐藏接口

以 . 开头的接口仅供内部使用，如：

• 检查更新 /.check_update
• 快速操作 /.handle_quick_operation

最佳实践建议

1. 消息发送：优先使用限速调用方式，避免消息频率过高
2. 错误处理：检查 retcode 并做好错误处理
3. 缓存策略：对频繁查询的信息适当缓存
4. 异步处理：非关键操作使用异步接口提高响应速度
5. 安全防护：务必配置 access_token 并妥善保管

常见问题解决方案

1. 403错误：检查 access_token 配置是否正确
2. 消息发送失败：确认机器人有相应权限
3. 数据获取为空：尝试设置 no_cache=true
4. 语音转换失败：确认已安装语音组件

通过合理使用这些API接口，开发者可以构建功能丰富的QQ机器人应用，实现自动回复、群管理、数据查询等各种功能。