Protocol model

Every WebSocket frame is one JSON object. Client requests contain cmd; fields beside it form that command’s payload.

type Request = {
  cmd: string;
  listener?: unknown;
  [field: string]: unknown;
};

Correlation

The dispatcher copies the request’s optional listener to every direct response. It is not interpreted, so strings and numbers both work. Use unique strings for predictable client maps.

Errors

Malformed JSON receives an uncorrelated error. Valid requests that fail validation or domain checks use:

{
  "cmd": "error",
  "val": "Message not found",
  "src": "message_get",
  "listener": "request-42"
}

src is the failed command. Authentication failures instead use { "cmd": "auth_error", "val": "…" }. Unknown commands intentionally return nothing.

Authentication and command permissions

Every command except auth requires authentication. The central gate additionally requires:

Permission	Commands gated centrally
manage_channels	channel_create, channel_update, channel_move, channel_delete
manage_emojis	emoji/sticker add, update, and delete
manage_server	attachment listing, server update/stats, webhook management
manage_users	banned-user listing, user update/kick/timeout
manage_roles	role CRUD/reorder and user_roles_set
review_reports	report listing and resolution
manage_config	config read and update

Handlers may enforce additional channel, ownership, hierarchy, or moderation rules.

Broadcasts

A handler marks an internal response global: true and includes channel. The transport removes global, sends the response to the caller with its listener, removes the listener, then sends the event to every other authenticated connection allowed to view that channel.

Some server-wide changes use the authenticated broadcast helper directly. Clients should therefore keep command handlers idempotent: the same logical state can be refreshed by a command result, a broadcast, or a full collection response.

Compatibility

Protocol version is currently the string "1". Use capabilities for fine-grained compatibility. Some capabilities are event shapes or HTTP features rather than dispatched WebSocket commands (channel_get, unreads_update, attachment_upload, signature versions, and server-side embeds).