Webhook Payloads
Message fields, the two offline UID representations, and the presence-string format.
The event name travels in ?event=...; request bodies have no common envelope.
Message object
The msg.notify body is an array of these objects. msg.offline flattens the same object into its top level.
| Field | JSON type | Meaning |
|---|---|---|
header.no_persist | number | always 0 for these committed messages |
header.red_dot | number | 0 or 1 |
header.sync_once | number | 0 or 1 |
setting | number | WKProto Setting bit mask |
topic | string, optional | omitted when empty |
expire | number (u32) | expiry value |
message_id | number (u64) | global message ID; JavaScript can lose precision |
message_idstr | string | decimal message_id; prefer this across languages |
client_msg_no | string | client idempotency identifier |
message_seq | number (u64) | sequence within the Channel |
from_uid | string | sender UID |
channel_id | string | Channel ID |
channel_type | number (u8) | Channel Type |
timestamp | number (i32) | Unix seconds |
payload | string | null | non-empty Go []byte uses standard Base64; an empty Payload encodes as null |
[
{
"header": {"no_persist": 0, "red_dot": 1, "sync_once": 0},
"setting": 0,
"expire": 0,
"message_id": 123456789,
"message_idstr": "123456789",
"client_msg_no": "order-0001",
"message_seq": 42,
"from_uid": "system",
"channel_id": "u1001",
"channel_type": 1,
"timestamp": 1785398400,
"payload": "eyJ0eXBlIjoib3JkZXJfdXBkYXRlIn0="
}
]msg.offline
In addition to the message fields, the top level has one of these mutually exclusive recipient representations:
| Condition | Fields |
|---|---|
| UID count below the compression threshold | to_uids: string[] |
| UID count at or above the threshold | compress: "gzip" and compress_to_uids: string |
compress_to_uids is a JSON string array, gzip-compressed, then standard-Base64 encoded. The default offline_uid_batch_size=512 is both the UID chunk limit and compression threshold. Numeric source_id is included when the sending node ID is nonzero.
user.onlinestatus
The body is an array of strings in this format:
{uid}-{device_flag}-{online:0|1}-{session_id}-{device_online_count}-{total_online_count}Counts come from the UID owner's local active-session projection. A UID can contain hyphens. Treat the whole record as opaque for compatibility, or parse the final five numeric fields from the right; do not use a fixed naïve - split.
Receives one bounded batch of committed durable messages.
Query Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
Example Requests
/msg.notify?event=msg.notifyReceives one committed message and one bounded UID chunk, either plain or gzip-compressed.
Query Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
Example Requests
/msg.offline?event=msg.offlineReceives a bounded, best-effort array of legacy status strings derived from active sessions on the UID owner's current node; it is not cluster-global presence.
Query Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
uid-deviceFlag-online-sessionID-deviceOnlineCount-totalOnlineCount; parse the final five numeric fields from the right because UID may contain hyphens
Response Body
Example Requests
/user.onlinestatus?event=user.onlinestatus