The gateway

The gateway pushes events to your bot over one WebSocket. The SDKs handle all of this for you; this page is for writing your own client or understanding what happens.

Connect

GET /api/bot/v1/gateway (with the token) returns the gateway's address, the heartbeat interval and the connection cap; the same path is the gateway when the request is a WebSocket upgrade.

Send Authorization: Bot <token> with the upgrade request. The token is never taken from the URL, so it cannot end up in logs. Clients that cannot set headers (browsers) may put the token in IDENTIFY instead; an upgrade without a valid token closes with 4004.

Frames

Every frame is JSON, {"op": n, "d": ..., "s": seq, "t": "NAME"}; s and t are only set on dispatches (op 0). Frames from the bot are at most 4096 bytes and 120 a minute. All opcodes and close codes are in the gateway reference.

  1. The server sends HELLO (op 10) with heartbeat_interval in milliseconds.
  2. The bot sends IDENTIFY (op 2) with its intents, within 10 seconds.
  3. The server dispatches READY: user (id, bot_id, username, handle, bot, avatar_url), session_id, the granted intents, resume_gateway_url and heartbeat_interval.
  4. The bot sends HEARTBEAT (op 1) every interval, with the last s; the server answers op 11.

username is the name members see; handle is the unique name they type to mention the bot, taken from its name when it is created (for example @dice, or @bot-… when the name gives nothing usable). A message's mentions lists the bot's id.

Heartbeats and resume

A bot that sends nothing for 1.5 intervals after identifying is closed with 4009; one that does not identify within 10 seconds, with 4003.

Keep the last s. After a disconnect, open a new connection and send RESUME (op 6, {"token", "session_id", "seq"}) within 2 minutes: the server replays the events after seq (it keeps the last 512 per session) and sends RESUMED. If it cannot, it answers INVALID_SESSION (op 9) and the bot identifies again. Events during the gap are replayed through the same visibility checks that applied when they happened. At most 3 live connections and 6 resumable sessions per bot.

Presence

A bot sets its own status and activity with op 3, after IDENTIFY (IDENTIFY may also carry the starting presence as d.presence):

{"op": 3, "d": {"since": null, "afk": false, "status": "idle",
  "activities": [{"name": "chess", "type": 0}]}}
  • status: online, idle, dnd or invisible.
  • activities: only the first is used. type 0 playing, 2 listening, 3 watching, 4 custom, 5 competing; streaming (1) is refused. The text is cut to 64 characters.
  • At most 5 updates per 60 seconds per bot; further ones are dropped. The status belongs to the bot, and ends with its last connection.

Events

The intents you ask for decide which events arrive; see Concepts and the event list. INTERACTION_CREATE needs no intent. The bot's own messages are dispatched to it too, and message content is always included.

A minimal client

Node 22 or newer, no libraries:

const token = process.env.TOKEN
const ws = new WebSocket('wss://talk.example.org/api/bot/v1/gateway', { headers: { Authorization: `Bot ${token}` } })
let seq = null, timer
const send = (op, d) => ws.send(JSON.stringify({ op, d }))
ws.onmessage = ({ data }) => {
  const f = JSON.parse(data)
  if (f.s != null) seq = f.s
  if (f.op === 10) {
    send(2, { intents: 512, properties: { os: 'linux' } }) // GUILD_MESSAGES
    timer = setInterval(() => send(1, seq), f.d.heartbeat_interval)
  } else if (f.op === 0 && f.t === 'MESSAGE_CREATE' && !f.d.is_bot && f.d.content === '!ping') {
    fetch(`https://talk.example.org/api/bot/v1/channels/${f.d.channel_id}/messages`, {
      method: 'POST',
      headers: { Authorization: `Bot ${token}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ content: 'pong', message_reference: { message_id: f.d.id } })
    })
  }
}
ws.onclose = (e) => { clearInterval(timer); console.log('closed', e.code) } // resume or identify again

Something wrong on this page? Tell us.