Gateway

The gateway ("Stargate") is the real-time side of the API: one WebSocket connection over which the server pushes every event the connected account can see. Bots and clients use the same protocol.

This instance's gateway: wss://your-instance.example/gateway/events

Connecting#

Open a WebSocket to the gateway URL with the credential in the handshake:

GET /gateway/events HTTP/1.1
Host: your-instance.example
Authorization: Bot <bot token>
Upgrade: websocket

• Bots send Authorization: Bot <token>. Bot tokens are accepted from the header only - never in the URL, where they would end up in logs.
• The Strafe client uses its session token (Authorization: Bearer, or ?token= because browsers cannot set headers on a WebSocket). OAuth2 access tokens cannot open a gateway connection.

A rejected handshake is an HTTP error with a JSON body: 401 {"op": 8, "d": {"code": 401, "message": "invalid bot token"}}. A bot, unlike a browser page, sends no Origin header, so the instance's allowed-origins list does not apply to it.

The first frame after a successful upgrade is READY (op 4).

Frames#

Every frame is a JSON object with an op and, usually, a d.

Client → server#

Server → client#

An event frame nests: the outer d is the envelope, its t is the event type and its inner d the payload:

{
  "op": 3,
  "d": {
    "t": "MESSAGE_CREATE",
    "space_id": "2102443061534523392",
    "room_id": "2102443061534523392",
    "d": { "id": "2105141774585434112", "room_id": "2102443061534523392", "sender_id": "…", "plaintext": "ping" }
  }
}

room_id is set for room events (the field space_id repeats it - a historical quirk), user_id for events delivered on the account's own channel.

READY#

{
  "op": 4,
  "d": {
    "user": { "id": "2105141069376131072", "username": "Docs_Bot", "display_name": "Docs Bot", "public_flags": 0, "bot": true },
    "session_id": "0",
    "rooms": [ { "id": "…", "type": 1, "recipients": ["…"], "e2ee_enabled": true, "created_at": "…" } ],
    "relationships": [],
    "spaces": [
      {
        "id": "2102226824774811648", "name": "Unread Test Space 2", "icon": "", "owner_id": "…",
        "everyone_role_id": "2102226824779005952",
        "roles": [ { "id": "…", "name": "@everyone", "permissions": 2334751, "position": 0, "color": 0, "hoist": false, "mentionable": false } ],
        "system_room_id": "…", "default_message_notifications": 0, "afk_timeout": 0
      }
    ],
    "space_rooms": {
      "2102226824774811648": [
        { "id": "2102443061534523392", "type": 3, "name": "files-test", "topic": "", "position": 3, "parent_id": "…", "e2ee_enabled": false, "slowmode_seconds": 0,
          "permission_overrides": [ { "role_id": "…", "allow": 0, "deny": 2 } ], "user_overrides": [] }
      ]
    },
    "voice_states": [],
    "calls": []
  }
}

Member lists are not in READY - fetch GET /spaces/:id/members when you need one and keep it current from the member events.

Heartbeat#

The server sends a WebSocket ping frame every 54 seconds and closes the connection if nothing (a pong, or any frame) arrives within 60 seconds. Every mainstream WebSocket library answers pings automatically, so a bot has nothing to do. Sending {"op": 6} yourself is fine and gets {"op": 7} back - useful as a liveness check through proxies.

There is no resume: after a disconnect, reconnect and read READY again. To recover messages missed while offline, page GET /rooms/:id/messages (newest first, before= to go back) until you reach the last id you saw.

Subscriptions#

Events are published on channels, one per space (space-wide events: roles, members, settings) and one per room (messages, reactions, typing). Both are subscribed with op 1 and the id in space_id:

{ "op": 1, "d": { "space_id": "2102226824774811648" } }   // the space itself
{ "op": 1, "d": { "space_id": "2102443061534523392" } }   // a room in it

A subscription is refused (silently) when the account cannot access that room or is not in that space.

• Bots are auto-subscribed on connect to every space in READY.spaces, every room in READY.space_rooms, and every PM in READY.rooms. A bot only subscribes by hand to a space it joins after connecting (announced by SPACE_CREATE) and that space's rooms, or a room created while it is connected (SPACE_ROOM_CREATE).
• The account's own channel (user_id events: relationship requests, new PMs, SPACE_CREATE, SESSION_REVOKED, read receipts) is always subscribed.
• Clients manage their subscriptions themselves and use op 5 when they leave a space.

Sending over the gateway#

op 2 publishes a small event to a room's subscribers without going through REST. It is used for typing indicators:

{ "op": 2, "d": { "space_id": "2102443061534523392", "type": "typing" } }

It is rate limited per connection (a burst of 20, refilling one every 250 ms) and requires the room subscription. Everything that is stored - messages, reactions, membership changes - goes through REST, and the gateway reports it back as an event.

Activity#

op 9 sets what the account is doing - in this version, the game it is playing. The Strafe desktop app sends it when someone turns on sharing in its settings, and a bot can use it to show "Playing …" too:

{ "op": 9, "d": { "activities": [ { "type": "playing", "name": "Factory Builder", "started_at": 1761000000000 } ] } }
{ "op": 9, "d": null }   // stopped playing

• One entry at most. type must be "playing". name is cleaned before use - control characters, line and paragraph separators and bidi controls are removed, runs of whitespace become one space, the ends are trimmed - and must then hold 1 to 128 characters (counted in code points), at least one of them visible. started_at is unix milliseconds: 0 or absent means now, a time in the future becomes now, and one more than 7 days ago becomes 7 days ago.
• A malformed report (a second entry, another type, a name that is empty or too long) is answered with error 4007 and changes nothing. The connection stays open.
• Rate limit: a burst of 5 reports per connection, then one every 12 seconds. A report over the budget is not refused: it waits, a newer one replaces it, and the latest is applied when the next token frees, without an error frame. Reporting the same activity again changes nothing and costs nothing.
• It belongs to the connection. It is never written to the database: the instance holds it in its short-lived cache and forgets it when the connection closes (after a short grace period, so a quick reconnect does not flicker). A new connection starts with none, so report again after every READY. When several of an account's connections report, the most recent report wins.
• Who sees it: the account itself, its friends and the members of its spaces - in PRESENCE_UPDATE, on member objects and on friends' relationship entries, as presence.activities. Nobody else sees it while the account appears offline or invisible; its own connections still do. People on other instances see it the way they see the account's status.
• Show the name as plain text - never as Markdown, a link, emoji or a mention - and isolate its direction (<bdi>, dir="auto"), since it is someone else's text.

Events#

Room events reach every subscriber of the room; space events reach every subscriber of the space; account events reach only that account. Payloads are the objects described on the REST page unless noted.

Messages (room)#

Rooms#

Threads#

Sent space-wide when everyone can view the parent channel, otherwise only to the members who can; a private thread's events go to its members alone.

Spaces and members#

Account#

Errors#

Errors after the handshake arrive as {"op": 8, "d": {"code", "message"}} and never close the connection.

An op 2 frame that exceeds the send bucket is dropped without an error. An op 9 report over its budget is not dropped: the latest one is applied when the next token frees, also without an error.