API REFERENCE · QMSG 2.0.0

API 文档

通过 HTTP 接口推送消息到各平台机器人 · 文档更新 2026-10-10-r21

基础信息

Base URL
https://qmsg.cn/api
推荐鉴权
Authorization: Bearer <API_KEY>
兼容鉴权
X-Conduit-OpenAPI-Key: <API_KEY>
内容类型
application/json
请求去重（建议）
Idempotency-Key: UNIQUE_REQUEST_ID

鉴权说明

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

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

先检查 code，再检查任务状态。单条 status=SUCCESS 或 succeeded 才表示成功；HTTP 202、pending=true 表示处理中，uncertain=true 表示送达待核实。批量还需逐项检查 results，处理中和待核实不计作成功或失败。

auth-header
$ Authorization: Bearer YOUR_QMSG_API_KEY

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

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

API 端点

POST 发送单条消息

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

建议每次逻辑推送带一个 Idempotency-Key 请求头。8 秒内未结束会先返回 HTTP 202、pending=true 和 jobId；使用下方查询接口跟踪结果，不要换编号重复发送。
请求 URL
request
POST /api/openapi/v1/push/private
请求参数
参数类型必填说明
botIdinteger是机器人 ID，必须属于当前 API Key 对应账户
targetstring除 Server 酱、钉钉外必填机器人下分配的 Target 编号，不是 QQ/平台用户 ID；需先绑定目标。Server 酱、钉钉可省略
contentstring否消息内容，普通文本最多 2000 个字符；图片消息可用 imageUrl 替代
msgTypeinteger否消息类型：0=普通文本（默认）；2=Markdown；7=图片。格式支持因平台而异；当前 Telegram 的 2 使用 HTML 解析模式
imageUrlstring否图片 URL；设置后自动按图片消息处理
targetTypestring否目标类型：user 或 group；默认使用已绑定 Target 的类型
isWakeupboolean否是否使用唤醒方式发送，默认 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_idinteger是机器人 ID
target_idinteger除 Server 酱、钉钉外必填机器人下分配的 Target 编号，不是 QQ/平台用户 ID；Server 酱、钉钉可省略
contentstring否消息内容，普通文本最多 2000 个字符
msg_typeinteger否消息类型：0=普通文本（默认）；2=Markdown；7=图片。格式支持因平台而异；当前 Telegram 的 2 使用 HTML 解析模式
image_urlstring否图片 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 推送消息

最多 50 个 Target。各平台使用同一推送通道及并发队列，图片按平台接口发送。响应等待总计最多 8 秒，尚未完成的项返回 jobId 和 queued 状态，使用任务查询接口跟踪。Server酱和钉钉无 Target，使用单条直接推送。
请求 URL
request
POST /api/openapi/batch-send
请求参数
参数类型必填说明
bot_idinteger是机器人 ID
target_idsinteger[]是Target 编号数组，例如 [1,2,3]
contentstring否消息内容，普通文本最多 2000 个字符
msg_typeinteger否消息类型：0=普通文本（默认）；2=Markdown；7=图片。格式支持因平台而异；当前 Telegram 的 2 使用 HTML 解析模式
image_urlstring否图片 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 编号；botId 也可写成 bot_id。每组必须含机器人和非空 targets，合计最多 50 个目标。返回 pending_count、uncertain_count 和每项 jobId，不能把排队项视为送达成功。
请求 URL
request
POST /api/openapi/v1/push/batch
请求参数
参数类型必填说明
botsarray是机器人分组数组，至少包含一个有效分组
bots[].botIdinteger是机器人 ID
bots[].targetsstring[]是该机器人下的 Target 编号数组，例如 ["1","2"]
contentstring否消息内容，普通文本最多 2000 个字符
msgTypeinteger否消息类型：0=普通文本（默认）；2=Markdown；7=图片。格式支持因平台而异；当前 Telegram 的 2 使用 HTML 解析模式
imageUrlstring否图片 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 }
    ]
  }
}

GET 查询推送任务

使用发送响应的 jobId 查询 API Key 所属账户的任务结果

queued/running 表示等待或发送中，succeeded 为成功，failed/canceled/expired 为未成功，uncertain 为结果待核实。等待超时或取消会返还已扣点数；网络超时或发送中重启不自动退款或重发。
请求 URL
request
GET /api/openapi/queue/:id
请求参数
参数类型必填说明
idstring是路径参数：发送响应返回的 jobId
请求示例
request.json
GET /api/openapi/queue/任务UUID
响应示例
response.json
{ "code": 0, "data": { "jobId": "任务UUID", "status": "running", "success": null, "pending": true, "uncertain": false } }

GET 找回单条请求

断线后用同一 Idempotency-Key 找回已提交的单条任务

Idempotency-Key 限 1–100 个字母、数字、下划线、冒号或连字符；同账号同编号须为同一消息，记录保留 30 天。批量推送用各项 jobId 查询；重放同一批量编号时消息与目标列表必须一致。未查到单条记录返回 data=null，可使用原编号和原请求重新提交。
请求 URL
request
GET /api/openapi/queue-request?key=请求编号
请求参数
参数类型必填说明
keystring是查询参数：单条发送时携带的 Idempotency-Key
请求示例
request.json
GET /api/openapi/queue-request?key=order-123
响应示例
response.json
{ "code": 0, "data": null }

错误码

错误码说明解决方案
400参数错误或点数不足检查请求体、机器人 ID、Target 编号和消息内容；开启点数系统时还需检查点数余额。
401API Key 缺失或无效检查 Authorization: Bearer <API_KEY> 或 X-Conduit-OpenAPI-Key 请求头。
403权限不足、Key 被吊销/过期或账户异常检查 API Key 状态及账户状态。
404机器人或 Target 不存在确认机器人属于当前 API Key 对应账户，并确认 Target 已绑定。
409请求编号冲突或任务状态已变化同一个编号只能对应同一消息；刷新任务结果，不要对结果未知的任务直接重发。
429请求过于频繁或队列积压已满降低频率或等待积压消退；单机器人最多 100 条，全站最多 1000 条。默认每个 API Key 每分钟 120 次，可由服务端配置。
503服务正在重启稍后使用原请求编号和原消息重新提交，避免重复推送。
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