Gateway & WebSocket Guide
The Discord Gateway is a real-time, bi-directional WebSocket connection used by bots to receive events and send presences.
Gateway Lifecycle
Section titled “Gateway Lifecycle”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 BackoffHealth and reconnect storms
Section titled “Health and reconnect storms”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.
Gateway Intents
Section titled “Gateway Intents”Lunibee exposes both camelCase and Discord-standard PascalCase intent constants:
IntentBits— camelCase constants such asIntentBits.guilds.GatewayIntentBits— PascalCase constants such asGatewayIntentBits.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, ],});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, ],});Privileged Intents
Section titled “Privileged Intents”MessageContent, GuildMembers, and GuildPresences are privileged Gateway intents. Enable the corresponding intents for your bot in the Discord Developer Portal before requesting them.
Intents Reference
Section titled “Intents Reference”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 |