WebSockets: Persistent Connections and the Discord Gateway

The WebSocket Protocol

HTTP is a request/response protocol: the client asks, the server answers, and the exchange is over. That model is a poor fit for a chat bot that must react the instant a user sends a message. Polling is wasteful, and webhooks require a publicly reachable server. The WebSocket protocol solves this by keeping a single connection open indefinitely, over which either side may send data at any moment.

From HTTP to WebSocket: the Upgrade Handshake

A WebSocket connection begins as an ordinary HTTP request. The client sends a GET request carrying an Upgrade: websocket header, signalling it wishes to switch protocols on this very TCP connection. If the server agrees, it responds not with 200 OK but with HTTP status 101 Switching Protocols, and from that point the same TCP connection is repurposed to speak the WebSocket framing protocol.

The beauty of reusing the HTTP handshake is compatibility. Because the connection starts as HTTP (typically HTTPS), it traverses the same ports (443) and the same proxies and firewalls that already permit web traffic — no new port to open, no new protocol for a firewall to distrust.

Figure 6.3: The HTTP-to-WebSocket upgrade handshake

Frames, Text vs. Binary, and Ping/Pong

Once upgraded, data flows as frames — small, self-describing units of the WebSocket wire format. Data frames carry payloads and are either text (UTF-8 strings, the common case for JSON gateways) or binary (raw bytes for compressed payloads). Control frames manage the connection: a Close frame initiates orderly shutdown, and Ping/Pong form a low-level keepalive.

The Ping/Pong pair recurs at two layers. At the protocol layer, either endpoint may send a Ping; the receiver must reply with a Pong, confirming liveness and measuring round-trip latency — the Python websockets library handles these automatically. Confusingly, some application protocols (like Discord's) also define their own heartbeat layered on ordinary data frames. Keeping these two layers distinct is essential: the protocol-level Ping/Pong is your library's job; the application-level heartbeat is often yours.

Persistent, Full-Duplex Communication

The defining property of a WebSocket is that it is full-duplex: both endpoints can send independently and simultaneously, without turn-taking. In a webhook, the platform must open a fresh connection for every event, wait for your 200 OK, and close it. Over a WebSocket, the platform simply writes the event onto the always-open socket the moment it occurs, and your bot writes commands back over the same socket whenever it likes.

Because the connection is long-lived and carries session context, it is inherently stateful. The socket is the session; if it drops, that session (and any un-replayed events) is at risk — a theme we return to when weighing trade-offs.

Consuming a Real-Time Gateway

The Discord Gateway: Identify, Dispatch, and Intents

To connect, a bot fetches the Gateway URL from the Get Gateway Bot REST endpoint (and caches it), then opens a WebSocket to something like wss://gateway.discord.gg/?v=10&encoding=json. Every message is a JSON object with an opcode (op), a data payload (d), and — for dispatched events — a sequence number (s) and event name (t). The lifecycle unfolds through a small set of opcodes:

• Hello (op 10): sent immediately after connecting; its data contains heartbeat_interval in milliseconds (e.g. 41250 ms). The bot caches this and begins heartbeating.
• Heartbeat (op 1) / Heartbeat ACK (op 11): the bot sends a heartbeat every interval carrying the last sequence; Discord replies with an ACK.
• Identify (op 2): the bot authenticates by sending its token, a properties object, and an intents integer.
• Ready (a Dispatch, op 0): on successful identify, returns session_id and resume_gateway_url, which the bot must cache for recovery.
• Dispatch (op 0): every actual event arrives with an event name t and an incrementing sequence s, which the bot caches.

Gateway intents deserve attention: an intent is a bitmask declaring which categories of events the bot wants — you pay only for what you subscribe to (e.g. GUILDS (1 << 0), MESSAGE_CONTENT (1 << 15)). Some intents are privileged and must be enabled in the Developer Portal. Identify is also heavily rate-limited (roughly 1000 per 24 hours), a strong incentive to reconnect via resume rather than a fresh identify.

Figure 6.1: The Discord Gateway lifecycle

Reading an Async Stream of Events in Python

The websockets library turns the socket into something you iterate with async for, fitting the coroutine model perfectly. A minimal read loop parses each raw JSON message and dispatches on the opcode — op 0 for a Dispatch event, op 11 for a Heartbeat ACK. This skeleton is deliberately incomplete: it identifies and reads events but does not yet heartbeat or reconnect. Reading events is the easy part; keeping the connection alive and recoverable is where production robustness lives.

Slack Socket Mode: a WebSocket Alternative to Public Webhooks

Slack apps can receive events two ways: the traditional HTTP model (Events API via public webhooks) or Socket Mode, a WebSocket alternative. With Socket Mode, the app initiates an outbound WebSocket to Slack, and all dispatches flow back over that socket — nothing via HTTP. Because the app dials out, it needs no public URL, no inbound firewall rule, and no tunneling tool. Setup involves toggling Socket Mode on and generating an app-level token (prefixed xapp-, requiring the connections:write scope).

Two details distinguish Slack's design from Discord's. First, the WebSocket URL is not static: the app calls apps.connections.open to obtain a fresh, ticketed URL like wss://wss.slack.com/link/?ticket=..., which refreshes regularly. Second, every event carries an envelope_id, and the app must acknowledge each one by sending that envelope_id back — Slack's equivalent of the HTTP 200 OK. Slack sends a hello on connect and a disconnect (with a reason) before teardown, so a well-behaved client opens a new connection before the old one closes.

For a multi-channel gateway the consequence is architectural: Discord only offers a WebSocket gateway, while Slack offers both. A unified service must abstract over a persistent-socket consumer and, optionally, an inbound HTTP webhook receiver — normalizing both into a single internal event stream.

Keeping the Connection Alive

A persistent socket is a liability as much as an asset: over hours and days it faces network partitions, proxy timeouts, container restarts, and platform maintenance. Production-grade means three things: proving the connection is alive (heartbeats), reconnecting cleanly when it dies (backoff), and resuming without data loss when possible (session resume).

Heartbeats and Detecting a Dead Connection

At the protocol layer, the websockets library ships built-in keepalive using Ping/Pong control frames — by default a Ping every 20 seconds expecting a Pong within 20 seconds; if none arrives, the connection is deemed broken and a ConnectionClosed exception surfaces. This generates periodic traffic (so idle-killing proxies don't close the socket), detects half-open connections, and measures latency.

At the application layer, Discord's op-1 heartbeat requires the bot to send {"op": 1, "d": <last_seq>} every heartbeat_interval ms and expect a Heartbeat ACK (op 11). If it sends a heartbeat and does not receive an ACK before the next is due, the connection is a "zombie": the bot must close the socket (ideally non-1000) and reconnect. Discord may also proactively send op 1, in which case the bot must respond immediately.

One subtlety resurfaces: the first Discord heartbeat should be delayed by heartbeat_interval * jitter (jitter random between 0 and 1). This spreads reconnecting clients so a fleet does not heartbeat in lockstep — a real defence against the "thundering herd" problem. The heartbeat is best run as a background task alongside the read loop.

Reconnect with Exponential Backoff and Jitter

The websockets library offers a clean pattern: use connect() as an infinite asynchronous iterator, so each iteration establishes a fresh connection and a close transparently triggers a reconnect. Under the hood it retries transient errors with exponential backoff while fatal errors are raised, breaking the loop. Which errors count as transient is decided by process_exception(): by default it retries on EOFError, OSError, asyncio.TimeoutError, and InvalidStatus with HTTP 500/502/503/504, treating others (like auth failures) as fatal.

Even with built-in backoff, production clients codify the policy explicitly. Exponential backoff grows the delay geometrically after each failure (1s, 2s, 4s, 8s…) rather than hammering a struggling server at a fixed rate. Two refinements are essential: cap the backoff at a ceiling (e.g. 30s) so it never grows unbounded, and add jitter so that after an outage thousands of clients don't reconnect at exactly the same instant.

Figure 6.4: Reconnect-with-backoff state machine

Session Resumption and Replaying Missed Events

Reconnecting alone is not enough — a naive reconnect re-identifies from scratch, losing events that occurred during the gap and burning one of your limited identify allocations. Discord distinguishes recoverable from unrecoverable drops. When a connection breaks, the bot opens a new WebSocket to the cached resume_gateway_url (not the original) and sends a Resume (op 6) with token, session_id, and seq (last sequence received). Discord replays every missed event and finishes with a Resumed dispatch — making delivery at-least-once rather than lossy.

Discord signals how to recover via opcodes and close codes: Reconnect (op 7) means "close and resume"; Invalid Session (op 9) carries a boolean where true means still resumable and false means dead (fresh identify needed). Close codes guide recovery too: 4000, 4001, 4008 are resumable, whereas 4004 (auth failed), 4007 (invalid seq), 4009 (session timeout), and 4013/4014 (invalid/disallowed intents) require a fresh identify or are fatal.

Figure 6.5: Deciding to resume vs. re-identify after a disconnect

Design Trade-offs

Statefulness and Connection Affinity

The central trade-off is state. A webhook is stateless: each event is an independent HTTP request any instance can handle, with no session to protect. A WebSocket is stateful: the connection holds session context (Discord's session_id, the sequence cursor, Slack's ticketed URL) and is pinned — has connection affinity — to one process. If that process dies, the session dies with it, and only resume-with-replay saves you from lost events. Slack articulates this bluntly: the webhook's very transience is a reliability feature; the WebSocket's persistence is simultaneously its greatest strength (for latency) and its greatest operational burden.

Scaling WebSocket Consumers and Sharding

Statelessness scales trivially: put more webhook receivers behind a load balancer and they share load with no coordination. Persistent sockets are harder — pinned to a server, you cannot freely spread one logical connection across instances. Slack caps an app at 10 concurrent Socket Mode connections. For high-volume Discord bots, the answer is sharding: splitting guilds across multiple gateway connections, each shard an independent WebSocket with its own identify, heartbeat, and resume state — the WebSocket analogue of horizontally scaling stateless workers, but each unit of scale is itself a stateful connection.

When to Prefer WebSockets Over Webhooks

Figure 6.2: WebSocket vs. Webhook delivery comparison

Slack's own guidance crystallizes the choice: Socket Mode for development, local use, and apps behind a firewall, while HTTP is recommended for production and required for the Slack Marketplace. The overriding practical factor, though, is often simply what the platform supports. Discord offers only a WebSocket gateway, so a Discord bot has no choice. A multi-channel gateway will typically need both capabilities — a hardened WebSocket consumer for platforms that mandate it, and a webhook receiver for those that prefer HTTP — feeding both into one normalized internal stream.