Gateway overview

Status Stable · Last verified 2026-07-11 · API v10 · Sources Gateway, Gateway events

The gateway is Discord’s persistent WebSocket connection for real-time events: messages, member joins, reactions, voice state, typing, and more. If you need to observe what happens in a server, you need the gateway (or interactions, for the narrower case of user-invoked commands).

When you need it

• Moderation, logging, welcome messages, auto-roles.
• Anything reactive to live events (reactions, voice, presence).
• Receiving interactions if you’d rather not run an HTTP endpoint.

You don’t need it for post-only notifications (webhooks) or for purely command-driven apps that use an interaction endpoint.

Connection lifecycle (conceptual)

1. GET the gateway URL   →  /gateway/bot  (also tells you shard count + limits)
2. Open the WebSocket    →  receive HELLO (heartbeat_interval)
3. Start heartbeating    →  send OP 1 every heartbeat_interval ms
4. IDENTIFY              →  send token + intents  (or RESUME to replay)
5. Receive READY         →  session_id + resume_gateway_url
6. Receive events        →  DISPATCH (MESSAGE_CREATE, GUILD_MEMBER_ADD, …)
7. On disconnect         →  RESUME with session_id + last sequence, or re-IDENTIFY

In practice you use a library (discord.js, discord.py, serenity, discord4j, D++, etc.) that implements heartbeats, resuming, and sharding for you. The bot-gateway-minimal example uses discord.js.

Intents decide what you receive

You do not receive all events by default. You subscribe to groups of events with intents, declared at IDENTIFY. Three are privileged and gated: GUILD_MEMBERS, GUILD_PRESENCES, and MESSAGE_CONTENT. This is important and security-relevant enough to have its own page → Intents.

Heartbeats, resuming, and reconnects

• Heartbeat (OP 1) on the interval from HELLO; if Discord stops acking, your connection is considered zombied — reconnect.
• Resume replays missed events using your session_id and last sequence number via the resume_gateway_url — cheaper than a fresh IDENTIFY.
• Expect periodic reconnects; treat them as normal, not errors.

Sharding (scale)

A single gateway connection can serve many guilds, but past ~2,500 guilds Discord requires sharding — splitting guilds across multiple connections. Your library handles the mechanics; you provide the shard count (from /gateway/bot). Large bots also coordinate an identify rate limit (max concurrency) across shards. Details are tracked in the research backlog.

Rate limits on the gateway

Separate from REST limits, the gateway caps how fast you can send (e.g. ~120 commands / 60 s) and how many IDENTIFYs you may do. Libraries queue for you; if you hand-roll a client, respect these or you’ll be disconnected.

Next

• Intents — exactly what you can and can’t receive, and the 2026 privileged-intent access changes.
• Prefer no socket? → Interactions endpoint.