Reference

Gateway

Connecting to the gateway, HELLO / IDENTIFY / READY, heartbeats and zombie detection, RESUME, Invalid Session, close codes, and the events each intent delivers.

The gateway is a WebSocket at wss://api.voidcom.app/ws (also returned by GET /gateway and GET /gateway/bot; shards is always 1). Frames are JSON text — no zlib-stream, no ETF; query parameters like ?v=10&encoding=json are accepted and ignored. Opcodes and payload shapes follow Discord's.

Connection flow

1. Open the socket. The gateway sends HELLO (op 10) immediately:

   { "op": 10, "d": { "heartbeat_interval": 41250 } }

2. Within 30 seconds send IDENTIFY (op 2) — or RESUME — otherwise the socket is closed:

   { "op": 2, "d": { "token": "YOUR_VOIDCOM_BOT_TOKEN", "intents": 33281 } }

   shard, large_threshold and presence are accepted and ignored. intents must stay within the token's grant — the intent toggles on the application page, baked into the token when it is minted; asking for more closes the socket with 4014 Disallowed intent(s) before any READY.
3. On success the gateway dispatches READY (op 0, t: "READY", s: 1):

   {
     "v": 10,
     "user": { "id": "…", "username": "mybot", "bot": true },
     "guilds": [{ "id": "…", "unavailable": true }],
     "session_id": "…",
     "resume_gateway_url": "wss://api.voidcom.app/ws",
     "application": { "id": "…", "flags": 0 }
   }

   guilds lists every server the bot is a member of as unavailable; with the GUILDS intent one GUILD_CREATE per listed guild follows (channels, roles and the bot's member, fetched as the bot), as on Discord — they are numbered dispatches, so a RESUME replays them. Without GUILDS nothing follows: fetch GET /users/@me/guilds when you need the objects.

Then events flow as op 0 frames with an increasing s.

Heartbeats

Send op 1 every heartbeat_interval ms (41 250) with your last received s as d; the gateway answers op 11 (HEARTBEAT ACK) and refreshes the session's TTL.

If no heartbeat arrives for 2.5 × the interval (≈ 103 s, counted from HELLO and re-armed by each heartbeat), the socket is a zombie: the gateway closes it with code 4000 and the bot should RESUME. It is deliberately not 4009, which would make libraries re-IDENTIFY and lose the replay.

RESUME

After a drop, reconnect to resume_gateway_url, wait for HELLO and send op 6:

{ "op": 6, "d": { "token": "YOUR_VOIDCOM_BOT_TOKEN", "session_id": "…", "seq": 1337 } }

Whichever replica you land on loads the session, checks the token belongs to the same bot, replays every recorded frame with s greater than your seq in order, then dispatches RESUMED with s continuing from where the session left off.

Bounds:

What RESUME replays: frames the gateway already produced that the dead socket did not deliver — the common case. What it cannot replay: events that happened while the bot had no session at all (between the session expiring and the next IDENTIFY). Bots that need exactly-once should refetch state on RESUMED the way they do on READY.

Invalid Session

Every failure is the same: op 9 with d: false, then the socket closes. Re-IDENTIFY with a fresh session (there is no d: true resumable variant). Causes:

• the first frame was not a valid IDENTIFY or RESUME payload;
• the token is invalid, revoked or rotated — a bad token is not reported as close 4004; if READY never arrives, check the token;
• RESUME for an unknown or expired session, or a session that belongs to a different bot;
• RESUME for a session whose intents the current token no longer grants (the token was rotated after intents were removed) — re-IDENTIFY with the smaller set;
• the session store is unavailable.

A RESUME whose seq is older than the ring still succeeds: nothing is replayed, then RESUMED.

Close codes

The gateway sends 4000 for a heartbeat timeout, 4014 Disallowed intent(s) when IDENTIFY asks for intents beyond the token's grant (fatal for libraries, as on Discord — enable the intent on the application page and rotate the token, or drop it from IDENTIFY), and a plain close (no 4xxx code) after Invalid Session or when the first frame did not arrive in time. Discord's other 4xxx codes (4004 authentication failed, 4008 rate limited, 4013 invalid intents, …) are not used.

Opcodes

Events

Every event the gateway dispatches, the intent that gates it, and where it comes from. INTERACTION_CREATE is delivered regardless of intents. GUILD_MEMBER_* need the privileged GUILD_MEMBERS intent. Message content / embeds / components / attachments need MESSAGE_CONTENT on server messages.

Not dispatched: friend, mention, emoji, call, key-rotation, notification-preference, server-organisation and voice-state events have no Discord equivalent or are not mapped; there is no VOICE_STATE_UPDATE, GUILD_BAN_ADD/REMOVE, INVITE_CREATE/DELETE, CHANNEL_PINS_UPDATE, MESSAGE_DELETE_BULK, MESSAGE_REACTION_REMOVE_ALL, thread, scheduled-event, stage, auto-moderation or poll event. The full machine-readable list is on Differences from Discord.

Intents

Bit values are Discord's. IDENTIFY with intents beyond the token's grant closes with 4014; granted intents without a row in the events table are accepted and deliver nothing.