Skip to main content
The Gateway API lets apps open secure WebSocket connections with Discord to receive events about actions that take place in a server/guild, like when a channel is updated or a role is created. There are a few cases where apps will also use Gateway connections to update or request resources, like when updating voice state.
In most cases, performing REST operations on Discord resources can be done using the HTTP API rather than the Gateway API.
The Gateway is Discord’s form of real-time communication used by clients (including apps), so there are nuances and data passed that simply isn’t relevant to apps. Interacting with the Gateway can be tricky, but there are community-built libraries with built-in support that simplify the most complicated bits and pieces. If you’re planning on writing a custom implementation, be sure to read the following documentation in its entirety so you understand the sacred secrets of the Gateway (or at least those that matter for apps).

​
Gateway Events

Gateway events are payloads sent over a Gateway connection—either from an app to Discord, or from Discord to an app. An app typically sends events when connecting and managing its connection to the Gateway, and receives events when listening to actions taking place in a server. All Gateway events are encapsulated in a Gateway event payload. A full list of Gateway events and their details are in the Gateway events documentation.
Example Gateway Event
{
  "op": 0,
  "d": {},
  "s": 42,
  "t": "GATEWAY_EVENT_NAME"
}
Details about Gateway event payloads are in the Gateway events documentation.

​
Sending Events

When sending a Gateway event (like when performing an initial handshake or updating presence), your app must send an event payload object with a valid opcode (op) and inner data object (d).
Specific rate limits are applied when sending events, which you can read about in the Rate Limiting section.
Event payloads sent over a Gateway connection:
  1. Must be serialized in plain-text JSON or binary ETF.
  2. Must not exceed 4096 bytes. If an event payload does exceed 4096 bytes, the connection will be closed with a 4002 close event code.
All events that your app can send via a connection are in Gateway event documentation.

​
Receiving Events

Receiving a Gateway event from Discord (like when a reaction is added to a message) is much more common (and slightly more complex) than sending them. While some events are sent to your app automatically, most events require your app to define intents when Identifying. Intents are bitwise values that can be ORed (|) to indicate which events (or groups of events) you want Discord to send your app. A list of intents and their corresponding events are listed in the intents section. When receiving events, you can also configure how events will be sent to your app, like the encoding and compression, or whether sharding should be enabled). All events that your app can receive via a connection are in the Gateway event documentation.

​
Dispatch Events

Dispatch (opcode 0) events are the most common type of event your app will receive. Most Gateway events which represent actions taking place in a guild will be sent to your app as Dispatch events. When your app is parsing a Dispatch event:
  • The t field can be used to determine which Gateway event the payload represents the data you can expect in the d field.
  • The s field represents the sequence number of the event, which is the relative order in which it occurred. You need to cache the most recent non-null s value for heartbeats, and to pass when Resuming a connection.

​
Connections

Gateway connections are persistent WebSockets which introduce more complexity than sending HTTP requests or responding to interactions (like Slash Commands). When interacting with the Gateway, your app must know how to open the initial connection, as well as maintain it and handle any disconnects.

​
Connection Lifecycle

There are nuances that aren’t included in the overview below. More details about each step and event can be found in the individual sections below.
At a high-level, Gateway connections consist of the following cycle: