API 文档 - Qmsg

基础信息

Base URL

https://qmsg.cn/api

推荐鉴权

Authorization: Bearer <API_KEY>

兼容鉴权

X-Conduit-OpenAPI-Key: <API_KEY>

内容类型

application/json

鉴权说明

API 文档可无需登录查看；调用 OpenAPI 接口仍需要有效的 API Key。

新生成的 Key 使用 qmsg_ 前缀；历史 conduit_ Key 继续兼容。

HTTP 200 不一定表示发送成功，还需检查 JSON 中的 code。单条接口 code 为 0 表示成功；批量接口还需逐项检查 results 和失败数量。

auth-header

$ Authorization: Bearer YOUR_QMSG_API_KEY

也兼容旧 Header：X-Conduit-OpenAPI-Key: YOUR_QMSG_API_KEY

API Key 仅显示一次，忘记后请重新生成。

API 端点

POST 发送单条消息

向一个已绑定的目标推送一条消息

请求 URL

request

POST /api/openapi/v1/push/private

请求参数

参数	类型	必填	说明
`botId`	integer	是	机器人 ID，必须属于当前 API Key 对应账户
`target`	string	除 Server 酱、钉钉外必填	机器人下分配的 Target 编号，不是 QQ/平台用户 ID；需先绑定目标。Server 酱、钉钉可省略
`content`	string	否	消息内容，普通文本最多 2000 个字符；图片消息可用 imageUrl 替代
`msgType`	integer	否	消息类型：0=普通文本（默认）；2=Markdown；7=图片。格式支持因平台而异；当前 Telegram 的 2 使用 HTML 解析模式
`imageUrl`	string	否	图片 URL；设置后自动按图片消息处理
`targetType`	string	否	目标类型：user 或 group；默认使用已绑定 Target 的类型
`isWakeup`	boolean	否	是否使用唤醒方式发送，默认 false

请求示例

request.json

{
  "botId": 1,
  "target": "1",
  "content": "Hello from Qmsg!",
  "msgType": 0
}

响应示例

response.json

{
  "code": 0,
  "message": "",
  "data": {
    "id": 123,
    "bot": 1,
    "user": 456,
    "content": "Hello from Qmsg!",
    "msg_type": 0,
    "status": "SUCCESS",
    "platformIndex": "123456"
  }
}

POST 发送单条消息（兼容接口）

兼容旧版参数命名的单条发送接口

推荐新项目使用 /api/openapi/v1/push/private；本接口保留 bot_id、target_id、msg_type、image_url 参数兼容。

请求 URL

request

POST /api/openapi/send

请求参数

参数	类型	必填	说明
`bot_id`	integer	是	机器人 ID
`target_id`	integer	除 Server 酱、钉钉外必填	机器人下分配的 Target 编号，不是 QQ/平台用户 ID；Server 酱、钉钉可省略
`content`	string	否	消息内容，普通文本最多 2000 个字符
`msg_type`	integer	否	消息类型：0=普通文本（默认）；2=Markdown；7=图片。格式支持因平台而异；当前 Telegram 的 2 使用 HTML 解析模式
`image_url`	string	否	图片 URL；设置后按图片消息处理

请求示例

request.json

{
  "bot_id": 1,
  "target_id": 1,
  "content": "Hello from Qmsg!",
  "msg_type": 0
}

响应示例

response.json

{
  "code": 0,
  "message": "",
  "data": {
    "id": 123,
    "bot": 1,
    "user": 456,
    "content": "Hello from Qmsg!",
    "msg_type": 0,
    "status": "SUCCESS",
    "platformIndex": "123456"
  }
}

POST 批量发送消息

向同一个机器人下的多个已绑定 Target 推送消息

本版本批量接口为 QQ、飞书、企业微信提供发送分支；其他平台请使用单条接口。飞书不支持 URL 图片，企业微信将图片 URL 作为文本发送。

请求 URL

request

POST /api/openapi/batch-send

请求参数

参数	类型	必填	说明
`bot_id`	integer	是	机器人 ID
`target_ids`	integer[]	是	Target 编号数组，例如 [1,2,3]
`content`	string	否	消息内容，普通文本最多 2000 个字符
`msg_type`	integer	否	消息类型：0=普通文本（默认）；2=Markdown；7=图片。格式支持因平台而异；当前 Telegram 的 2 使用 HTML 解析模式
`image_url`	string	否	图片 URL；设置后按图片消息处理

请求示例

request.json

{
  "bot_id": 1,
  "target_ids": [1, 2, 3],
  "content": "批量推送",
  "msg_type": 0
}

响应示例

response.json

{
  "code": 0,
  "message": "批量发送完成：成功 3 条，失败 0 条",
  "data": {
    "total": 3,
    "success": 3,
    "failed": 0,
    "results": [
      { "target_id": 1, "success": true, "message_id": 123 },
      { "target_id": 2, "success": true, "message_id": 124 },
      { "target_id": 3, "success": true, "message_id": 125 }
    ]
  }
}

POST 多机器人批量推送

跨多个机器人向各自已绑定 Target 推送消息

targets 填写每个机器人下的 Target 编号，不是平台用户 ID；botId 也可写成 bot_id。有效分组需包含 botId 和非空 targets，无效分组会被跳过。本版本批量发送适用于 QQ、飞书、企业微信；其他平台请用单条接口。

请求 URL

request

POST /api/openapi/v1/push/batch

请求参数

参数	类型	必填	说明
`bots`	array	是	机器人分组数组，至少包含一个有效分组
`bots[].botId`	integer	是	机器人 ID
`bots[].targets`	string[]	是	该机器人下的 Target 编号数组，例如 ["1","2"]
`content`	string	否	消息内容，普通文本最多 2000 个字符
`msgType`	integer	否	消息类型：0=普通文本（默认）；2=Markdown；7=图片。格式支持因平台而异；当前 Telegram 的 2 使用 HTML 解析模式
`imageUrl`	string	否	图片 URL；设置后按图片消息处理

请求示例

request.json

{
  "bots": [
    { "botId": 1, "targets": ["1", "2"] },
    { "botId": 2, "targets": ["4"] }
  ],
  "content": "系统维护通知",
  "msgType": 0
}

响应示例

response.json

{
  "code": 0,
  "message": "批量推送完成：成功 3 条，失败 0 条",
  "data": {
    "total": 3,
    "success_count": 3,
    "fail_count": 0,
    "results": [
      { "botId": 1, "target": "1", "status": "success", "message_id": 123 },
      { "botId": 1, "target": "2", "status": "success", "message_id": 124 },
      { "botId": 2, "target": "4", "status": "success", "message_id": 125 }
    ]
  }
}

错误码

错误码	说明	解决方案
`400`	参数错误或点数不足	检查请求体、机器人 ID、Target 编号和消息内容；开启点数系统时还需检查点数余额。
`401`	API Key 缺失或无效	检查 Authorization: Bearer <API_KEY> 或 X-Conduit-OpenAPI-Key 请求头。
`403`	权限不足、Key 被吊销/过期或账户异常	检查 API Key 状态及账户状态。
`404`	机器人或 Target 不存在	确认机器人属于当前 API Key 对应账户，并确认 Target 已绑定。
`429`	OpenAPI 请求过于频繁	降低请求频率；默认限制为每个 API Key 每分钟 120 次，可由服务端配置。
`500`	服务器或平台发送异常	查看返回 message，并检查机器人平台连接状态。

可运行代码示例

示例统一调用推荐接口 /api/openapi/v1/push/private，只需替换 API Key、机器人 ID 和 Target。

Bash 与 curl；直接粘贴到终端，或保存为下方文件。

qmsg-example.sh

curl -X POST "https://qmsg.cn/api/openapi/v1/push/private" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_QMSG_API_KEY" \
  -d '{
    "botId": 1,
    "target": "1",
    "content": "Hello from Qmsg!",
    "msgType": 0
  }'

保存后运行

terminal

bash qmsg-example.sh