消息 API (Message)

消息 API (Message API) 是发送顶层瞬时通知的主要入口。接口同步返回网关是否受理，具体的下发过程在后台异步执行。

接口地址 (Endpoint)

POST /message

---

全局限制 (Global Constraints)

• 请求体大小: 最大 32KB (DefaultBodyLimit::max(32 * 1024))。
• ID 格式: 网关生成的 ID（如 message_id）为 32 位小写十六进制字符串。

---

请求头 (Headers)

参数名	值	描述
Content-Type	application/json	必填。
Authorization	Bearer <token>	可选。仅在网关启用了鉴权（私有部署）时为必填。

---

请求体 (Request Body - JSON)

核心字段

字段名	类型	是否必填	描述与约束
channel_id	string	是	目标频道 ID。
password	string	是	频道密码 (8-128 个字符)。
title	string	是	消息标题。
body	string	否	消息正文。支持 Markdown。
op_id	string	否	幂等键 (1-128 个字符，仅限字母、数字及 _:-)。

扩展字段

字段名	类型	是否必填	描述与约束
severity	enum	否	优先级：critical, high, normal, low。默认：normal。
url	string	否	可选的点击跳转 URL。
images	string[]	否	最多 32 条图片 URL，每条最大 2048 字符。
tags	string[]	否	最多 32 个标签，每个最大 64 字符。
ttl	number	否	Unix 秒级过期时间。最大按 28 天 处理。
thing_id	string	否	关联的 实体 (Thing) ID。
ciphertext	string	否	透传的密文字段。
metadata	object	否	自定义键值对。仅限标量 (scalar)。Key ≤ 64, Value ≤ 512。

---

优先级映射 (Severity Mapping)

PushGo 将四种优先级级别映射到不同平台的原生级别：

• APNs (Apple): critical, time-sensitive, active, passive。
• FCM (Android): HIGH, NORMAL。
• WNS (Windows): 1, 2, 3。

未知值将按 normal 处理。

---

代码示例 (cURL)

curl -X POST https://gateway.pushgo.cn/message \
     -H "Content-Type: application/json" \
     -d '{
       "channel_id": "你的频道ID",
       "password": "你的频道密码",
       "title": "警报：CPU 负载过高",
       "body": "**警告**：CPU 使用率已达到 92%。",
       "severity": "high",
       "tags": ["监控", "服务器-01"]
     }'

---

响应格式 (Envelope)

所有 API 响应都遵循统一的格式：

{
  "success": true,
  "data": {
    "channel_id": "01HZX9G7G7JPRV4M3H5T9B3C6A",
    "op_id": "8a1fc4b3...",
    "message_id": "8a1fc4b3d9f04fd2857f92f66f7cc5d1",
    "accepted": true
  },
  "error": null,
  "error_code": null
}

响应状态码

• 200: 网关已受理。
• 400: 校验错误（如密码太短）。
• 401: 鉴权失败（缺少或错误的 Token）。
• 404: 频道不存在。
• 413: 请求体超过 32KB。
• 503: 分发部分失败 (accepted=false)。

---

兼容性接口 (Compatibility Endpoints)

PushGo 提供了兼容性接口，以便从其他通知服务轻松迁移。

鉴权规则

对于兼容性接口，请使用 <channel_id>:<password> 的格式作为 Key（称为 compat_key）。

提供商	方法	路径	参数映射
ntfy	POST/PUT	/message/ntfy/{topic}	{topic} = compat_key
ServerChan	GET/POST	/message/serverchan/{sendkey}	{sendkey} = compat_key
Bark v1	GET	/message/bark/{device_key}/{body}	{device_key} = compat_key
Bark v2	POST	/message/bark/push	device_key = compat_key (JSON 字段)

注意：兼容性接口不支持 thing_id。