Gateways

Gateways are Discord's form of real-time communication over secure websockets. Clients will receive events and data over the gateway they are connected to and send data over the REST API. The API for interacting with Gateways is complex and fairly unforgiving, therefore its highly recommended you read all of the following documentation before writing a custom implementation.The Discord Gateway has a versioning system which is separate from the core APIs. The documentation herein is only for the latest version in the following table, unless otherwise specified.
Gateway Versions
VersionStatus
6Available
5Discontinued
4Discontinued

Payloads

Gateway Payload Structure
FieldTypeDescriptionPresent
opintegeropcode for the payloadAlways
d?mixed (any JSON value)event dataAlways
sintegersequence number, used for resuming sessions and heartbeatsOnly for Opcode 0
tstringthe event name for this payloadOnly for Opcode 0

Sending Payloads

Packets sent from the client to the Gateway API are encapsulated within a gateway payload object and must have the proper opcode and data object set. The payload object can then be serialized in the format of choice (see ETF/JSON), and sent over the websocket. Payloads to the gateway are limited to a maximum of 4096 bytes sent, going over this will cause a connection termination with error code 4002.
Example Gateway Dispatch
{
    "op": 0,
    "d": {},
    "s": 42,
    "t": "GATEWAY_EVENT_NAME"
}

Receiving Payloads

Receiving payloads with the Gateway API is slightly more complex than sending. When using the JSON encoding with compression enabled, the Gateway has the option of sending payloads as compressed JSON binaries using zlib, meaning your library must detect (see RFC1950 2.2) and decompress these payloads before attempting to parse them. The gateway does not implement a shared compression context between messages sent.

Encoding and Compression

ETF/JSON

When initially creating and handshaking connections to the Gateway, a user can chose whether they wish to communicate over plain-text JSON or binary ETF. When using ETF, the client must not send compressed messages to the server. Note that Snowflake IDs are transmitted as 64-bit integers over ETF, but are transmitted as strings over JSON. See erlpack for an implementation example.

Payload Compression

When using JSON encoding with payload compression enabled (compress: true in identify), the Gateway may optionally send zlib-compressed payloads (see RFC1950 2.2). Your library must detect and decompress these payloads to plain-text JSON before attempting to parse them. If you are using payload compression, the gateway does not implement a shared compression context between messages sent. Payload compression will be disabled if you use transport compression (see below).

Transport Compression

Currently the only available transport compression option is zlib-stream. You will need to run all received packets through a shared zlib context, as seen in the example below. Every connection to the gateway should use its own unique zlib context.
Transport Compression Example
# Z_SYNC_FLUSH suffix
ZLIB_SUFFIX = '\x00\x00\xff\xff'
# initialize a buffer to store chunks
buffer = bytearray()
# create a zlib inflation context to run chunks through
inflator = zlib.decompressobj()

# ...
def on_websocket_message(msg):
  # always push the message data to your cache
  buffer.extend(msg)

  # check if the last four bytes are equal to ZLIB_SUFFIX
  if len(msg) < 4 or msg[-4:] != ZLIB_SUFFIX:
    return

  # if the message *does* end with ZLIB_SUFFIX,
  # get the full message by decompressing the buffers
  msg = inflator.decompress(buffer).decode('utf-8')
  buffer = bytearray()

  # here you can treat `msg` as either JSON or ETF encoded,
  # depending on your `encoding` param

Connecting to the Gateway

Connecting

Gateway URL Params
FieldTypeDescription
vintegerGateway Version to use
encodingstring'json' or 'etf'
compress?string'zlib-stream'
The first step in establishing connectivity to the gateway is requesting a valid websocket endpoint from the API. This can be done through either the Get Gateway or the Get Gateway Bot endpoint.With the resulting payload, you can now open a websocket connection to the "url" (or endpoint) specified. Generally, it is a good idea to explicitly pass the gateway version and encoding. For example, we may connect to wss://gateway.discord.gg/?v=6&encoding=json.Once connected, the client should immediately receive an Opcode 10 Hello payload, with information on the connection's heartbeat interval:
Example Gateway Hello
{
    "heartbeat_interval": 45000,
    "_trace": ["discord-gateway-prd-1-99"]
}

Heartbeating

The client should now begin sending Opcode 1 Heartbeat payloads every heartbeat_interval milliseconds, until the connection is eventually closed or terminated. This OP code is also bidirectional. The gateway may request a heartbeat from you in some situations, and you should send a heartbeat back to the gateway as you normally would.
In the event of a service outage where you stay connected to the gateway, you should continue to heartbeat and receive ACKs. The gateway will eventually respond and issue a session once it's able to.
Clients can detect zombied or failed connections by listening for Opcode 11 Heartbeat ACK:
Example Gateway Heartbeat ACK
{
    "op": 11
}
If a client does not receive a heartbeat ack between its attempts at sending heartbeats, it should immediately terminate the connection with a non-1000 close code, reconnect, and attempt to resume.

Identifying

Next, the client is expected to send an Opcode 2 Identify:
Example Gateway Identify
{
    "token": "my_token",
    "properties": {
        "$os": "linux",
        "$browser": "disco",
        "$device": "disco"
    },
    "compress": true,
    "large_threshold": 250,
    "shard": [1, 10],
    "presence": {
        "game": {
            "name": "Cards Against Humanity",
            "type": 0
        },
        "status": "dnd",
        "since": 91879201,
        "afk": false
    }
}
If the payload is valid, the gateway will respond with a Ready event. Your client is now considered in a "connected" state. Clients are limited to 1 identify every 5 seconds; if they exceed this limit, the gateway will respond with an Opcode 9 Invalid Session. It is important to note that although the ready event contains a large portion of the required initial state, some information (such as guilds and their members) is sent asynchronously (see Guild Create event).
Clients are limited to 1000 IDENTIFY calls to the websocket in a 24-hour period. This limit is global and across all shards, but does not include RESUME calls. Upon hitting this limit, all active sessions for the bot will be terminated, the bot's token will be reset, and the owner will receive an email notification. It's up to the owner to update their application with the new token.

Resuming

The internet is a scary place. Disconnections happen, especially with persistent connections. Due to Discord's architecture, this is a semi-regular event and should be expected and handled. Discord has a process for "resuming" (or reconnecting) a connection that allows the client to replay any lost events from the last sequence number they received in the exact same way they would receive them normally.Your client should store the session_id from the Ready, and the sequence number of the last event it received. When your client detects that it has been disconnected, it should completely close the connection and open a new one (following the same strategy as Connecting). Once the new connection has been opened, the client should send a Gateway Resume:
Example Gateway Resume
{
    "token": "my_token",
    "session_id": "session_id_i_stored",
    "seq": 1337
}
If successful, the gateway will respond by replaying all missed events in order, finishing with a Resumed event to signal replay has finished, and all subsequent events are new. It's also possible that your client cannot reconnect in time to resume, in which case the client will receive a Opcode 9 Invalid Session and is expected to wait a random amount of time—between 1 and 5 seconds—then send a fresh Opcode 2 Identify.

Disconnections

If the gateway ever issues a disconnect to your client, it will provide a close event code that you can use to properly handle the disconnection. A full list of these close codes can be found in the Response Codes documentation.

Rate Limiting

Clients are allowed 120 events every 60 seconds, meaning you can send on average at a rate of up to 2 events per second. Clients who surpass this limit are immediately disconnected from the Gateway, and similarly to the HTTP API, repeat offenders will have their API access revoked. Clients are also limited to one gateway connection per 5 seconds. If you hit this limit, the Gateway will respond with an Opcode 9 Invalid Session.

Tracking State

Most of a client's state is provided during the initial Ready event and the Guild Create events that immediately follow. As objects are further created/updated/deleted, other events are sent to notify the client of these changes and to provide the new or updated data. To avoid excessive API calls, Discord expects clients to locally cache as many object states as possible, and to update them as gateway events are received.An example of state tracking can be found with member status caching. When initially connecting to the gateway, the client receives information regarding the online status of guild members (online, idle, dnd, offline). To keep this state updated, a client must track and parse Presence Update events as they are received, and apply the provided data to the cached member objects.

Guild Availability

When connecting to the gateway as a bot user, guilds that the bot is a part of start out as unavailable. Don't fret! The gateway will automatically attempt to reconnect on your behalf. As guilds become available to you, you will receive Guild Create events.

Sharding

As bots grow and are added to an increasing number of guilds, some developers may find it necessary to break or split portions of their bots operations into separate logical processes. As such, Discord gateways implement a method of user-controlled guild sharding which allows for splitting events across a number of gateway connections. Guild sharding is entirely user controlled, and requires no state-sharing between separate connections to operate.To enable sharding on a connection, the user should send the shard array in the Identify payload. The first item in this array should be the zero-based integer value of the current shard, while the second represents the total number of shards. DMs will only be sent to shard 0. To calculate what events will be sent to what shard, the following formula can be used:
Sharding Formula
(guild_id >> 22) % num_shards == shard_id
As an example, if you wanted to split the connection between three shards, you'd use the following values for shard for each connection: [0, 3], [1, 3], and [2, 3]. Note that only the first shard ([0, 3]) would receive DMs.

Sharding for Very Large Bots

If you own a bot that is in over 100,000 guilds, there are some additional considerations you must take around sharding. We will contact you if you are required to adhere to these changes.The number of shards you run must be a multiple of a fixed number we will determine when reaching out to you. If you attempt to start your bot with an invalid number of shards, your websocket connection will close with a 4010 Invalid Shard opcode. The gateway bot bootstrap endpoint will return the correct amount of shards, so if you're already using this endpoint to determine your number of shards, you shouldn't require any further changes.The session start limit for these bots will also be increased from 1000 to 2000 per day. Finally, the Get Current User Guilds endpoint will no longer return results for your bot. We will be creating a new endpoint that is more shard-aware to iterate through your bot's guilds if needed.

Commands and Events

Commands are requests made to the gateway socket by a client.
Gateway Commands
namedescription
Identifytriggers the initial handshake with the gateway
Resumeresumes a dropped gateway connection
Heartbeatmaintains an active gateway connection
Request Guild Membersrequests offline members for a guild
Update Voice Statejoins, moves, or disconnects the client from a voice channel
Update Statusupdates a client's presence
Events are payloads sent over the socket to a client that correspond events in Discord.
Gateway Events
namedescription
Hellodefines the heartbeat interval
Readycontains the initial state information
Resumedresponse to Resume
Invalid Sessionfailure response to Identify or Resume or invalid active session
Channel Createnew channel created
Channel Updatechannel was updated
Channel Deletechannel was deleted
Channel Pins Updatemessage was pinned or unpinned
Guild Createlazy-load for unavailable guild, guild became available, or user joined a new guild
Guild Updateguild was updated
Guild Deleteguild became unavailable, or user left/was removed from a guild
Guild Ban Adduser was banned from a guild
Guild Ban Removeuser was unbanned from a guild
Guild Emojis Updateguild emojis were updated
Guild Integrations Updateguild integration was updated
Guild Member Addnew user joined a guild
Guild Member Removeuser was removed from a guild
Guild Member Updateguild member was updated
Guild Members Chunkresponse to Request Guild Members
Guild Role Createguild role was created
Guild Role Updateguild role was updated
Guild Role Deleteguild role was deleted
Message Createmessage was created
Message Updatemessage was edited
Message Deletemessage was deleted
Message Delete Bulkmultiple messages were deleted at once
Message Reaction Adduser reacted to a message
Message Reaction Removeuser removed a reaction from a message
Message Reaction Remove Allall reactions were explicitly removed from a message
Presence Updateuser's presence was updated in a guild
Typing Startuser started typing in a channel
User Updateproperties about a user changed
Voice State Updatesomeone joined, left, or moved a voice channel
Voice Server Updateguild's voice server was updated
Webhooks Updateguild channel webhook was created, update, or deleted

Event Names

Event names are in standard constant form, fully upper-cased and replacing all spaces with underscores. For instance, Channel Create would be CHANNEL_CREATE and Voice State Update would be VOICE_STATE_UPDATE. Within the following documentation they have been left in standard English form to aid in readability.

Identify

Used to trigger the initial handshake with the gateway.
Identify Structure
FieldTypeDescriptionDefault
tokenstringauthentication token-
propertiesobjectconnection properties-
compress?boolwhether this connection supports compression of packetsfalse
large_threshold?integervalue between 50 and 250, total number of members where the gateway will stop sending offline members in the guild member list50
shard?array of two integers (shard_id, num_shards)used for Guild Sharding-
presence?update status objectpresence structure for initial presence information-
Identify Connection Properties
FieldTypeDescription
$osstringyour operating system
$browserstringyour library name
$devicestringyour library name
Example Identify
{
    "token": "my_token",
    "properties": {
        "$os": "linux",
        "$browser": "disco",
        "$device": "disco"
    },
    "compress": true,
    "large_threshold": 250,
    "shard": [1, 10],
    "presence": {
        "game": {
            "name": "Cards Against Humanity",
            "type": 0
        },
        "status": "dnd",
        "since": 91879201,
        "afk": false
    }
}

Resume

Used to replay missed events when a disconnected client resumes.
Resume Structure
FieldTypeDescription
tokenstringsession token
session_idstringsession id
seqintegerlast sequence number received
Example Resume
{
    "token": "randomstring",
    "session_id": "evenmorerandomstring",
    "seq": 1337
}

Heartbeat

Used to maintain an active gateway connection. Must be sent every heartbeat_interval milliseconds after the Opcode 10 Hello payload is received. The inner d key is the last sequence number—s—received by the client. If you have not yet received one, send null.
Example Heartbeat
{
    "op": 1,
    "d": 251
}

Request Guild Members

Used to request offline members for a guild. When initially connecting, the gateway will only send offline members if a guild has less than the large_threshold members (value in the Gateway Identify). If a client wishes to receive additional members, they need to explicitly request them via this operation. The server will send Guild Members Chunk events in response with up to 1000 members per chunk until all members that match the request have been sent.
Guild Request Members Structure
FieldTypeDescription
guild_idsnowflakeid of the guild to get offline members for
querystringstring that username starts with, or an empty string to return all members
limitintegermaximum number of members to send or 0 to request all members matched
Guild Request Members
{
    "guild_id": "41771983444115456",
    "query": "",
    "limit": 0
}

Update Voice State

Sent when a client wants to join, move, or disconnect from a voice channel.
Gateway Voice State Update Structure
FieldTypeDescription
guild_idsnowflakeid of the guild
channel_id?snowflakeid of the voice channel client wants to join (null if disconnecting)
self_muteboolis the client muted
self_deafboolis the client deafened
Example Gateway Voice State Update
{
    "guild_id": "41771983423143937",
    "channel_id": "127121515262115840",
    "self_mute": false,
    "self_deaf": false
}

Update Status

Sent by the client to indicate a presence or status update.
Gateway Status Update Structure
FieldTypeDescription
since?integerunix time (in milliseconds) of when the client went idle, or null if the client is not idle
game?activity objectnull, or the user's new activity
statusstringthe user's new status
afkboolwhether or not the client is afk
Status Types
StatusDescription
onlineOnline
dndDo Not Disturb
idleAFK
invisibleInvisible and shown as offline
offlineOffline
Example Gateway Status Update
{
    "since": 91879201,
    "game": {
        "name": "Save the Oxford Comma",
        "type": 0
    },
    "status": "online",
    "afk": false
}

Connecting and Resuming

Hello

Sent on connection to the websocket. Defines the heartbeat interval that the client should heartbeat to.
Hello Structure
FieldTypeDescription
heartbeat_intervalintegerthe interval (in milliseconds) the client should heartbeat with
_tracearray of stringsused for debugging, array of servers connected to
Example Hello
{
    "heartbeat_interval": 45000,
    "_trace": ["discord-gateway-prd-1-99"]
}

Ready

The ready event is dispatched when a client has completed the initial handshake with the gateway (for new sessions). The ready event can be the largest and most complex event the gateway will send, as it contains all the state required for a client to begin interacting with the rest of the platform.guilds are the guilds of which your bot is a member. They start out as unavailable when you connect to the gateway. As they become available, your bot will be notified via Guild Create events. private_channels will be an empty array. As bots receive private messages, they will be notified via Channel Create events.
Ready Event Fields
FieldTypeDescription
vintegergateway protocol version
useruser objectinformation about the user including email
private_channelsarray of DM channel objectsthe direct message channels the user is in
guildsarray of Unavailable Guild objectsthe guilds the user is in
session_idstringused for resuming connections
_tracearray of stringsused for debugging - the guilds the user is in

Resumed

The resumed event is dispatched when a client has sent a resume payload to the gateway (for resuming existing sessions).
Resumed Event Fields
FieldTypeDescription
_tracearray of stringsused for debugging - the guilds the user is in

Invalid Session

Sent to indicate one of at least three different situations: - the gateway could not initialize a session after receiving an Opcode 2 Identify - the gateway could not resume a previous session after receiving an Opcode 6 Resume - the gateway has invalidated an active session and is requesting client actionThe inner d key is a boolean that indicates whether the session may be resumable. See Connecting and Resuming for more information.
Example Gateway Invalid Session
{
    "op": 9,
    "d": false
}

Channels

Channel Create

Sent when a new channel is created, relevant to the current user. The inner payload is a channel object.

Channel Update

Sent when a channel is updated. The inner payload is a channel object.

Channel Delete

Sent when a channel relevant to the current user is deleted. The inner payload is a channel object.

Channel Pins Update

Sent when a message is pinned or unpinned in a text channel. This is not sent when a pinned message is deleted.
Channel Pins Update Event Fields
FieldTypeDescription
channel_idsnowflakethe id of the channel
last_pin_timestamp?ISO8601 timestampthe time at which the most recent pinned message was pinned

Guilds

Guild Create

This event can be sent in three different scenarios:
  1. When a user is initially connecting, to lazily load and backfill information for all unavailable guilds sent in the Ready event.
  2. When a Guild becomes available again to the client.
  3. When the current user joins a new Guild.
The inner payload is a guild object, with all the extra fields specified.

Guild Update

Sent when a guild is updated. The inner payload is a guild object.

Guild Delete

Sent when a guild becomes unavailable during a guild outage, or when the user leaves or is removed from a guild. The inner payload is an unavailable guild object. If the unavailable field is not set, the user was removed from the guild.

Guild Ban Add

Sent when a user is banned from a guild. The inner payload is a user object, with an extra guild_id key.
Guild Ban Add Extra Fields
FieldTypeDescription
guild_idsnowflakeid of the guild

Guild Ban Remove

Sent when a user is unbanned from a guild. The inner payload is a user object, with an extra guild_id key.
Guild Ban Remove Extra Fields
FieldTypeDescription
guild_idsnowflakeid of the guild

Guild Emojis Update

Sent when a guild's emojis have been updated.
Guild Emojis Update Event Fields
FieldTypeDescription
guild_idsnowflakeid of the guild
emojisarrayarray of emojis

Guild Integrations Update

Sent when a guild integration is updated.
Guild Integrations Update Event Fields
FieldTypeDescription
guild_idsnowflakeid of the guild whose integrations were updated

Guild Member Add

Sent when a new user joins a guild. The inner payload is a guild member object with an extra guild_id key:
Guild Member Add Extra Fields
FieldTypeDescription
guild_idsnowflakeid of the guild

Guild Member Remove

Sent when a user is removed from a guild (leave/kick/ban).
Guild Member Remove Event Fields
FieldTypeDescription
guild_idsnowflakethe id of the guild
usera user objectthe user who was removed

Guild Member Update

Sent when a guild member is updated.
Guild Member Update Event Fields
FieldTypeDescription
guild_idsnowflakethe id of the guild
rolesarray of snowflakesuser role ids
usera user objectthe user
nickstringnickname of the user in the guild

Guild Members Chunk

Sent in response to Guild Request Members.
Guild Members Chunk Event Fields
FieldTypeDescription
guild_idsnowflakethe id of the guild
membersarray of guild membersset of guild members

Guild Role Create

Sent when a guild role is created.
Guild Role Create Event Fields
FieldTypeDescription
guild_idsnowflakethe id of the guild
rolea role objectthe role created

Guild Role Update

Sent when a guild role is updated.
Guild Role Update Event Fields
FieldTypeDescription
guild_idsnowflakethe id of the guild
rolea role objectthe role updated

Guild Role Delete

Sent when a guild role is deleted.
Guild Role Delete Event Fields
FieldTypeDescription
guild_idsnowflakeid of the guild
role_idsnowflakeid of the role

Messages

Message Create

Sent when a message is created. The inner payload is a message object.

Message Update

Sent when a message is updated. The inner payload is a message object.
Unlike creates, message updates may contain only a subset of the full message object payload (but will always contain an id and channel_id).

Message Delete

Sent when a message is deleted.
Message Delete Event Fields
FieldTypeDescription
idsnowflakethe id of the message
channel_idsnowflakethe id of the channel

Message Delete Bulk

Sent when multiple messages are deleted at once.
Message Delete Bulk Event Fields
FieldTypeDescription
idsarray of snowflakesthe ids of the messages
channel_idsnowflakethe id of the channel

Message Reaction Add

Sent when a user adds a reaction to a message.
Message Reaction Add Event Fields
FieldTypeDescription
user_idsnowflakethe id of the user
channel_idsnowflakethe id of the channel
message_idsnowflakethe id of the message
emojia partial emoji objectthe emoji used to react - example

Message Reaction Remove

Sent when a user removes a reaction from a message.
Message Reaction Remove Event Fields
FieldTypeDescription
user_idsnowflakethe id of the user
channel_idsnowflakethe id of the channel
message_idsnowflakethe id of the message
emojia partial emoji objectthe emoji used to react - example

Message Reaction Remove All

Sent when a user explicitly removes all reactions from a message.
Message Reaction Remove All Event Fields
FieldTypeDescription
channel_idsnowflakethe id of the channel
message_idsnowflakethe id of the message

Presence

Presence Update

A user's presence is their current state on a guild. This event is sent when a user's presence is updated for a guild.
The user object within this event can be partial, the only field which must be sent is the id field, everything else is optional. Along with this limitation, no fields are required, and the types of the fields are not validated. Your client should expect any combination of fields and types within this event.
Presence Update Event Fields
FieldTypeDescription
useruser objectthe user presence is being updated for
rolesarray of snowflakesroles this user is in
game?activity objectnull, or the user's current activity
guild_idsnowflakeid of the guild
statusstringeither "idle", "dnd", "online", or "offline"

Activity Object

Activity Structure
FieldTypeDescription
namestringthe activity's name
typeintegeractivity type
url??stringstream url, is validated when type is 1
timestamps?timestamps objectunix timestamps for start and/or end of the game
application_id?snowflakeapplication id for the game
details??stringwhat the player is currently doing
state??stringthe user's current party status
party?party objectinformation for the current party of the player
assets?assets objectimages for the presence and their hover texts
secrets?secrets objectsecrets for Rich Presence joining and spectating
instance?booleanwhether or not the activity is an instanced game session
flags?intactivity flags ORd together, describes what the payload includes
Bots are only able to send name, type, and optionally url.
Activity Types
IDNameFormatExample
0GamePlaying {name}"Playing Rocket League"
1StreamingStreaming {name}"Streaming Rocket League"
2ListeningListening to {name}"Listening to Spotify"
The streaming type currently only supports Twitch. Only https://twitch.tv/ urls will work.
Activity Timestamps
FieldTypeDescription
start?intunix time (in milliseconds) of when the activity started
end?intunix time (in milliseconds) of when the activity ends
Activity Party
FieldTypeDescription
id?stringthe id of the party
size?array of two integers (current_size, max_size)used to show the party's current and maximum size
Activity Assets
FieldTypeDescription
large_image?stringthe id for a large asset of the activity, usually a snowflake
large_text?stringtext displayed when hovering over the large image of the activity
small_image?stringthe id for a small asset of the activity, usually a snowflake
small_text?stringtext displayed when hovering over the small image of the activity
Activity Secrets
FieldTypeDescription
join?stringthe secret for joining a party
spectate?stringthe secret for spectating a game
match?stringthe secret for a specific instanced match
Activity Flags
NameValue
INSTANCE1 << 0
JOIN1 << 1
SPECTATE1 << 2
JOIN_REQUEST1 << 3
SYNC1 << 4
PLAY1 << 5
Example Activity
{
    "name": "Rocket League",
    "type": 1,
    "url": "https://www.twitch.tv/123"
}
Example Activity with Rich Presence
{
    "name": "Rocket League",
    "type": 0,
    "application_id": "379286085710381999",
    "state": "In a Match",
    "details": "Ranked Duos: 2-1",
    "timestamps": {
        "start": 15112000660000
    },
    "party": {
        "id": "9dd6594e-81b3-49f6-a6b5-a679e6a060d3",
        "size": [2, 2]
    },
    "assets": {
        "large_image": "351371005538729000",
        "large_text": "DFH Stadium",
        "small_image": "351371005538729111",
        "small_text": "Silver III"
    },
    "secrets": {
        "join": "025ed05c71f639de8bfaa0d679d7c94b2fdce12f",
        "spectate": "e7eb30d2ee025ed05c71ea495f770b76454ee4e0",
        "match": "4b2fdce12f639de8bfa7e3591b71a0d679d7c93f"
    }
}
Clients may only update their game status 5 times per minute.

Typing Start

Sent when a user starts typing in a channel.
Typing Start Event Fields
FieldTypeDescription
channel_idsnowflakeid of the channel
user_idsnowflakeid of the user
timestampintegerunix time (in seconds) of when the user started typing

User Update

Sent when properties about the user change. Inner payload is a user object.

Voice

Voice State Update

Sent when someone joins/leaves/moves voice channels. Inner payload is a voice state object.

Voice Server Update

Sent when a guild's voice server is updated. This is sent when initially connecting to voice, and when the current voice instance fails over to a new server.
Voice Server Update Event Fields
FieldTypeDescription
tokenstringvoice connection token
guild_idsnowflakethe guild this voice server update is for
endpointstringthe voice server host
Example Voice Server Update Payload
{
    "token": "my_token",
    "guild_id": "41771983423143937",
    "endpoint": "smart.loyal.discord.gg"
}

Webhooks

Webhooks Update

Sent when a guild channel's webhook is created, updated, or deleted.
Webhook Update Event Fields
FieldTypeDescription
guild_idsnowflakeid of the guild
channel_idsnowflakeid of the channel

Get Gateway

GET/gateway
This endpoint does not require authentication.
Returns an object with a single valid WSS URL, which the client can use for Connecting. Clients should cache this value and only call this endpoint to retrieve a new URL if they are unable to properly establish a connection using the cached version of the URL.
Example Response
{
    "url": "wss://gateway.discord.gg/"
}

Get Gateway Bot

GET/gateway/bot
This endpoint requires authentication using a valid bot token.
Returns an object with the same information as Get Gateway, plus a shards key, containing the recommended number of shards to connect with (as an integer). Bots that want to dynamically/automatically spawn shard processes should use this endpoint to determine the number of processes to run. This route should be called once when starting up numerous shards, with the response being cached and passed to all sub-shards/processes. Unlike the Get Gateway, this route should not be cached for extended periods of time as the value is not guaranteed to be the same per-call, and changes as the bot joins/leaves guilds.
Example Response
{
  "url": "wss://gateway.discord.gg/",
  "shards": 9
}