Client commands¶

Clients send commands over the Gateway WebSocket, with an integer opcode in op and the command data in d. A command can produce a Dispatch, a close frame, or no response.

Except for Heartbeat, Identify, and Resume, every command needs an attached session. Sending one too early closes with 4003 and reason Not authenticated. Heartbeat is accepted in any open state. Identify and Resume are accepted only while no session is attached.

Command index¶

Payload handling¶

A frame that fails the size, decompression, or decoding checks closes the connection. A frame that decodes to something other than an object closes with 4002 and reason Decode failed, and an object with no op closes with 4002 and reason Invalid payload.

TEBHOS charges every command that gets past those checks against the source IP, session, and connection payload budgets before it handles the opcode. Each session has its own session budget, and that budget is skipped while the connection is unauthenticated.

An opcode outside the registry closes with 4001 and reason Unknown opcode once a session is attached, and with 4003 while the connection is unauthenticated. A payload that has op but no d also closes with 4001, except Identify and Resume, which close with 4005.

Heartbeat¶

Opcode 1 carries the last Dispatch sequence the client processed, or null before the first Dispatch.

{
  "op": 1,
  "d": 42
}

Before authentication the Gateway accepts any d value and sends Opcode 11. A payload with no d key closes with 4001 and reason Unknown opcode.

Once authenticated, a d that is neither null nor an integer closes with 4007 and reason Invalid sequence. Every integer is accepted, but acknowledgements never move backwards. Dispatches at or below the highest acknowledged sequence are no longer available for Resume.

When the session ends, TEBHOS sends Opcode 9 with d: false, after which heartbeats are acknowledged again. A heartbeat that arrives in the short window between the session ending and that frame closes with 4007.

See Gateway overview for the timing contract.

Identify¶

Opcode 2 authenticates and creates a new session.

{
  "op": 2,
  "d": {
    "token": "...",
    "properties": {
      "os": "Linux",
      "browser": "my-client",
      "device": "desktop"
    },
    "presence": {
      "status": "online",
      "afk": false,
      "mobile": false
    },
    "ignored_events": ["TYPING_START"],
    "flags": 2,
    "initial_guild_id": "1189375284394692608"
  }
}

token and properties are required. Unknown fields are ignored. There is no intents field and no intent system.

The following faults close with 4002 and reason Invalid identify payload:

• A missing token or properties.
• properties that is not an object.
• properties whose os, browser, or device is missing or is not a string.
• An ignored_events value that is not an array of strings, or one that holds more than 256 entries.
• A flags value that is not a non-negative integer.

A malformed shard closes with 4010 and reason Invalid shard.

A bot session that resolves to more than 2,500 guilds after the shard filter closes with 4011 and reason Sharding required. A user session is never refused for its guild count.

A token the API rejects closes with 4004 and reason Invalid token. A user session token is accepted only while its login session exists, so a signed-out token fails here. A user account that already holds 100 live sessions closes with 4008 and reason Too many sessions. A bot credential is not bounded by that count. An Identify sent on a socket that already has a session attached closes with 4005 and reason Already authenticated, whether or not it has d.

The API also limits session starts to 20 per minute for each token. An Identify over that limit is held and retried silently, like any other temporary failure.

Session flags¶

Every other bit is undefined. An undefined bit is accepted and ignored.

DEBOUNCE_MESSAGE_REACTIONS applies to reactions in direct messages and group direct messages. A reaction in a guild channel is never merged and arrives as its own Message Reaction Add.

Identify properties object¶

Structure¶

os, browser, and device are required strings. The remaining fields are optional hints, and unrecognised properties are ignored.

latitude and longitude order the Ready rtc_regions array by distance. Send them only as strings: the API rejects a session request that carries a JSON number here, the Gateway treats that as a temporary failure and keeps retrying the held Identify, and Ready never arrives. Both must be sent to have any effect, and a string that does not parse as a number counts as absent. A client with no location omits them.

Initial presence object¶

Structure¶

The account's saved status is used when status is absent or null, when it is the string unknown, and when it is online while the saved status is not online. Otherwise the value is used as sent.

Identify accepts offline as a distinct initial status, and Presence Update normalises offline to invisible. A session whose resolved status is offline or invisible publishes status: "offline" and a null custom_status to other users.

Custom status object¶

Structure¶

Only these fields are read. Presence Update validates the object through the API before publishing it: an emoji_id that names no emoji rejects the object, and an emoji_id from an account without TEBHOS Pro is dropped from the published object while the rest is kept. The published presence adds emoji_animated, and fills emoji_name from the custom emoji's name.

Resume¶

Opcode 6 restores a retained session on a fresh socket.

All fields are required. A payload that is not an object, a missing field, a non-string token or session_id, or a seq that is not an integer closes with 4002 and reason Invalid resume payload.

An unknown or expired session produces Opcode 9 with d: false and leaves the socket unauthenticated. A token that does not own the session closes with 4004 and reason Invalid token. A seq above the session's current sequence, or below the sequence it has already acknowledged, closes with 4007 and reason Invalid sequence. A session that cannot be reached closes with 4000 and reason Session unavailable. None of those closes ends the retained session that session_id names.

A successful Resume replays every retained Dispatch strictly above seq in order and finishes with Resumed. It also replaces the session's socket, and the displaced socket receives Opcode 7 followed by a close with 4000.

A Resume sent on a socket that already has a session attached closes with 4005 and reason Already authenticated. Resume shares the source IP Identify budget: an over-budget Resume is discarded without a reply, so reconnect and send it again.

Presence Update¶

Opcode 3 replaces the current session presence.

{
  "op": 3,
  "d": {
    "status": "idle",
    "afk": true,
    "mobile": false,
    "custom_status": {
      "text": "away from keyboard"
    }
  }
}

status is required. A payload that is not an object, an object with no status key, and a status string outside the accepted set all close with 4002 and reason Invalid presence payload. The empty string resolves to online. Send a string: non-string values are not rejected, and their effect is not part of the contract.

offline is normalised to invisible, so a Presence Update cannot publish a session as offline while it is connected.

custom_status is replaced only when the key is present. Omitting the key keeps the current custom status, and null clears it. An object the API rejects, such as an emoji_id that names no emoji, leaves the current custom status in place. The connection stays open.

The published presence carries a custom status object and no activities.

Presence Update has its own limit of five accepted commands per 20 seconds on one WebSocket. A further update inside that window is discarded without closing the connection, after it has consumed the shared payload budgets.

Voice State Update¶

Opcode 4 joins, moves, updates, or leaves the voice membership associated with the current Gateway session. See Voice for the full placement model.

{
  "op": 4,
  "d": {
    "guild_id": "1189375284394692608",
    "channel_id": "1189375284394692610",
    "self_mute": false,
    "self_deaf": false,
    "self_video": false,
    "self_stream": false
  }
}

Every field is optional, but d must be an object: any other value closes with 4002 and reason Invalid voice payload. A non-null guild_id or channel_id is a decimal snowflake string. Any other value fails validation, and the update is dropped with no close code and no event.

The command has no session_id field. TEBHOS identifies the voice membership by the Gateway session that sends it.

Joining or replacing a grant produces Voice Server Update with the LiveKit token and endpoint for the media connection, and Voice State Update for every session that can see the channel. A refused update produces no event.

The first two updates in a rolling one-second window take effect immediately. Later updates can be delayed or replaced by newer updates for the same guild_id and connection_id. See command rate limits.

Request Guild Members¶

Opcode 8 requests bounded member chunks.

{
  "op": 8,
  "d": {
    "guild_id": "1189375284394692608",
    "query": "ann",
    "limit": 50,
    "presences": true,
    "nonce": "a1b2c3"
  }
}

The command never closes the connection. Invalid input is coerced or discarded:

• A guild ID that is not a positive snowflake abandons the whole request.
• Duplicate guild IDs are collapsed.
• A user_ids array longer than 100 entries abandons the whole request. Individual entries that are not positive snowflakes are dropped.
• A limit that is not a non-negative integer becomes 0, and a larger value is clamped to 100.
• Any non-string query becomes the empty string.
• A nonce that is not a string of at most 32 bytes becomes null. The nonce is echoed only when the request named exactly one guild.

A guild the session is not connected to is skipped. A bot requests one guild at a time, and a bot request naming two or more guilds is abandoned.

An empty query, a limit of 0, and an empty user_ids together request the complete member list (up to 100,000 entries). A user account requesting the complete list needs MANAGE_ROLES, KICK_MEMBERS, and BAN_MEMBERS in that guild, and a request without them is dropped silently. The guild owner and members with ADMINISTRATOR pass the check.

A bot requesting the complete list is limited to one accepted request per guild every 30 seconds. A request inside that window produces Rate Limited and no member chunk.

Results arrive as Guild Members Chunk in pages of at most 1,000 members, each with chunk_index and chunk_count. Those chunks are delivered live and never retained for Resume.

Only one member request runs at a time on one WebSocket. While one runs, a newer request replaces any earlier pending request and starts when the active one finishes. Bounded requests covers the four-slot limit this command shares with the other three.

Lazy Request¶

Opcode 14 sets the per-guild subscriptions that decide member list, typing, and synchronisation traffic for the session.

{
  "op": 14,
  "d": {
    "subscriptions": {
      "1189375284394692608": {
        "active": true,
        "typing": true,
        "member_list_channels": {
          "1189375284394692610": [[0, 99]]
        }
      }
    }
  }
}

A key that is not a valid snowflake, a value that is not an object, and a guild the session is not connected to are skipped without affecting the rest of the command. The command never closes the connection.

Guild subscription object¶

Structure¶

TEBHOS applies each option only when its key is present, in the order active, sync, member_list_channels, members, typing. active and sync must be booleans when present: any other value stops processing of the remaining options for that guild and every guild not yet processed, without a close.

Marking a guild active changes how much traffic it produces, as Event filtering specifies. A transition from passive to active, and from active to passive, both imply a sync even when sync is absent.

member_list_channels maps a channel ID to a list of [start, end] ranges. A range needs start at least 0, end at least start, end at most 100,000, and end - start at most 99. Ranges that fail those bounds are dropped, and each channel keeps at most the first 10 that pass. Subscriptions sent within 100 ms of each other may be merged. A channel the session cannot view, or can view without VIEW_CHANNEL_MEMBERS, receives no Guild Member List Update. Subscribing a channel to at least one range drops the session's other member list subscriptions in that guild, so one session holds at most one member list per guild.

members entries that are not snowflakes are dropped, and the first 1,000 that pass are kept. A member the session shares no viewable channel with is dropped as well. Each members array replaces the session's previous presence subscription set for that guild.

typing decides Typing Start delivery for the guild independently of the active flag. Non-boolean values are ignored.

Request Guild Counts¶

Opcode 15 requests the current member and online counts for guilds.

{
  "op": 15,
  "d": {
    "guild_ids": ["1189375284394692608"],
    "nonce": "counts-1"
  }
}

Entries that are not positive snowflakes are dropped, and a guild the session is not connected to is skipped. A nonce outside the length bound is omitted from the result. The command never closes the connection.

Results arrive in one Guild Counts Update. The request has a 3,000 ms deadline, and a guild that does not answer within 2,000 ms is omitted.

Request Channel Member Counts¶

Opcode 16 requests the member and online counts for channels in one guild.

{
  "op": 16,
  "d": {
    "guild_id": "1189375284394692608",
    "channel_ids": ["1189375284394692610"],
    "nonce": "channel-counts-1"
  }
}

A guild_id that is not a positive snowflake, or a guild the session is not connected to, produces an empty result. Channel entries that are not positive snowflakes are dropped. The command never closes the connection.

Results arrive in one Channel Member Counts Update with a 2,000 ms guild deadline. A channel is counted only when the session holds both VIEW_CHANNEL and VIEW_CHANNEL_MEMBERS there.

Bounded requests¶

One WebSocket processes at most four bounded requests at once across Request Guild Members, Lazy Request, Request Guild Counts, and Request Channel Member Counts. A command that arrives when all four slots are taken is dropped, without a close and without a result. Each request has a 10,000 ms deadline, after which it produces no further events.

Request Guild Members also keeps one replaceable pending request while another member request is active. See Bounded commands.