Skip to content

Gateway & WebSocket Guide

The Discord Gateway is a real-time, bi-directional WebSocket connection used by bots to receive events and send presences.

stateDiagram-v2
[*] --> Disconnected
Disconnected --> Connecting: connect()
Connecting --> Handshaking: Socket Open
Handshaking --> Identifying: Opcode 10 (Hello)
Identifying --> Ready: Opcode 0 (Ready)
Handshaking --> Resuming: Opcode 10 (Hello), session to resume
Resuming --> Ready: Opcode 0 (Resumed)
Ready --> Reconnecting: Network Drop / Recoverable Close
Ready --> Disconnected: Fatal Close
Reconnecting --> Connecting: Exponential Backoff

gateway.health() returns { state, latency, silentFor, reconnects }: the connection state, the last heartbeat round trip in milliseconds (-1 before the first), how long Discord has been silent, and how many reconnects were scheduled. ShardManager.health() reports the state, ping and lifecycle status of every shard.

A link that connects and drops again resets the usual backoff every time, which would loop at the base delay. Lunibee also counts reconnects over a window (reconnectStormLimit, default 5 per reconnectStormWindow, default 60 s): beyond it the wait doubles for each further reconnect, up to reconnectMaxDelay, and the Gateway emits unstable with { reconnects, delay }. A ShardManager re-emits it as shardUnstable.

Set compress: true on the client (or gateway: { compress: true }) to receive zlib-stream compressed frames, which cuts inbound bandwidth considerably.

Lunibee exposes both camelCase and Discord-standard PascalCase intent constants:

  • IntentBits — camelCase constants such as IntentBits.guilds.
  • GatewayIntentBits — PascalCase constants such as GatewayIntentBits.Guilds.

Both forms can be passed as an array or combined with bitwise OR.

import { Client, IntentBits, GatewayIntentBits } from "lunibee";
const client = new Client({
token: process.env.DISCORD_TOKEN!,
intents: [
IntentBits.guilds,
IntentBits.guildMessages,
IntentBits.messageContent,
],
});
const client2 = new Client({
token: process.env.DISCORD_TOKEN!,
intents: [
GatewayIntentBits.Guilds,
GatewayIntentBits.GuildMessages,
GatewayIntentBits.MessageContent,
],
});

MessageContent, GuildMembers, and GuildPresences are privileged Gateway intents. Enable the corresponding intents for your bot in the Discord Developer Portal before requesting them.

PascalCase (GatewayIntentBits) camelCase (IntentBits) Bit Shift Type
Guilds guilds 1 << 0 Standard
GuildMembers guildMembers 1 << 1 Privileged
GuildModeration guildModeration 1 << 2 Standard
GuildExpressions guildExpressions 1 << 3 Standard
GuildIntegrations guildIntegrations 1 << 4 Standard
GuildWebhooks guildWebhooks 1 << 5 Standard
GuildInvites guildInvites 1 << 6 Standard
GuildVoiceStates guildVoiceStates 1 << 7 Standard
GuildPresences guildPresences 1 << 8 Privileged
GuildMessages guildMessages 1 << 9 Standard
GuildMessageReactions guildMessageReactions 1 << 10 Standard
GuildMessageTyping guildMessageTyping 1 << 11 Standard
DirectMessages directMessages 1 << 12 Standard
DirectMessageReactions directMessageReactions 1 << 13 Standard
DirectMessageTyping directMessageTyping 1 << 14 Standard
MessageContent messageContent 1 << 15 Privileged
GuildScheduledEvents guildScheduledEvents 1 << 16 Standard
AutoModerationConfiguration autoModerationConfiguration 1 << 20 Standard
AutoModerationExecution autoModerationExecution 1 << 21 Standard
GuildMessagePolls guildMessagePolls 1 << 24 Standard
DirectMessagePolls directMessagePolls 1 << 25 Standard