Message API

The Message API is the primary endpoint for sending top-level ephemeral notifications. Responses indicate whether the message was accepted by the gateway; delivery is performed asynchronously.

Endpoint

POST /message

---

Global Constraints

• Body Size: Maximum 32KB (DefaultBodyLimit::max(32 * 1024)).
• ID Format: Gateway-generated IDs (e.g., message_id) are 32-char lowercase hex strings.

---

Headers

Header	Value	Description
Content-Type	application/json	Always required.
Authorization	Bearer <token>	Optional. Required only if the gateway has authentication enabled (Private Gateways).

---

Request Body (JSON)

Core Fields

Field	Type	Required	Description & Constraints
channel_id	string	Yes	Target channel ID.
password	string	Yes	Channel password (8-128 characters).
title	string	Yes	Message title.
body	string	No	Message body. Supports Markdown.
op_id	string	No	Idempotency key (1-128 chars, alphanumeric and _:- only).

Enrichment Fields

Field	Type	Required	Description & Constraints
severity	enum	No	critical, high, normal, low. Default: normal.
url	string	No	Optional click-through URL.
images	string[]	No	Up to 32 URLs, each max 2048 chars.
tags	string[]	No	Up to 32 tags, each max 64 chars.
ttl	number	No	Unix epoch seconds. Capped at 28 days (2,419,200s).
thing_id	string	No	Associates message with a Thing. Marks the message as thing-scoped.
ciphertext	string	No	Passthrough field for encrypted payloads.
metadata	object	No	Scalar keys/values only. Key max 64, value max 512.

---

Severity Mapping

PushGo maps its four severity levels to platform-specific priorities:

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

Unknown values will fall back to normal.

---

Example (cURL)

curl -X POST https://gateway.pushgo.dev/message \
     -H "Content-Type: application/json" \
     -d '{
       "channel_id": "01HZX9G7G7JPRV4M3H5T9B3C6A",
       "password": "your_password",
       "title": "Alert: CPU High",
       "body": "**Warning**: CPU usage is at 92%.",
       "severity": "high",
       "tags": ["monitoring", "server-01"]
     }'

---

Response Envelope

All API responses follow a unified envelope:

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

Response Status Codes

• 200: Accepted by gateway.
• 400: Validation error (e.g., password too short).
• 401: Authentication failure (Missing/Invalid Token).
• 404: Channel not found.
• 413: Request body exceeds 32KB.
• 503: Partial dispatch failure (accepted=false).

---

Compatibility Endpoints

PushGo provides compatibility endpoints for easier migration from other notification services.

Authentication Rule

For compatibility endpoints, use the format <channel_id>:<password> as the key (referred to as compat_key).

Provider	Method	Path	Parameter Mapping
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 (in JSON)

Note: Compatibility endpoints do not support thing_id.