Gateway Events - Discord Developer Platform

Gateway connections are WebSockets, meaning they’re bidirectional and either side of the WebSocket can send events to the other. Events are split into two types:

Send events are Gateway events sent by an app to Discord (like when identifying with the Gateway).
Receive events are Gateway events sent by Discord to an app. These typically represent something happening inside a server where an app is installed.

All Gateway events are encapsulated in a Gateway event payload.

Not all Gateway event fields are documented. Assume that undocumented fields are not supported for apps, and their format and data may change at any time.

Event Names

In practice, event names are UPPER_CASED_WITH_UNDERSCORES. For instance, Channel Create would be CHANNEL_CREATE and Voice State Update would be VOICE_STATE_UPDATE.

Payload Structure

Gateway event payloads have a common structure, but the contents of the associated data (d) varies between events.

Field	Type	Description
op	integer	Gateway opcode, which indicates payload type
d	?mixed (any JSON value)	Event data
s	?integer *	Sequence number used for resuming sessions and heartbeating
t	?string *	Event name

* s and t are null when op is not 0 (Gateway Dispatch opcode).

{
  "op": 0,
  "d": {},
  "s": 42,
  "t": "GATEWAY_EVENT_NAME"
}

Send Events

Send events are Gateway events sent by an app to Discord through a Gateway connection.

Name	Description
Identify	Triggers the initial handshake with the gateway
Resume	Resumes a dropped gateway connection
Heartbeat	Maintains an active gateway connection
Request Guild Members	Requests members for a guild
Request Soundboard Sounds	Requests soundboard sounds in a set of guilds
Update Voice State	Joins, moves, or disconnects the app from a voice channel
Update Presence	Updates an app’s presence

Identify

Used to trigger the initial handshake with the gateway. See the Gateway documentation for full details.

Identify Structure

Field	Type	Description	Default
token	string	Authentication token	-
properties	object	Connection properties	-
compress?	boolean	Whether this connection supports compression of packets	false
large_threshold?	integer	Value between 50 and 250, total number of members where the gateway will stop sending offline members in the guild member list	50
shard?	array of two integers (shard_id, num_shards)	Used for Guild Sharding	-
presence?	update presence object	Presence structure for initial presence information	-
intents	integer	Gateway Intents you wish to receive	-

Identify Connection Properties

Field	Type	Description
os	string	Your operating system
browser	string	Your library name
device	string	Your library name

These fields originally were $-prefixed (e.g., $browser) but that syntax is deprecated. Use non-prefixed field names.

{
  "op": 2,
  "d": {
    "token": "my_token",
    "properties": {
      "os": "linux",
      "browser": "disco",
      "device": "disco"
    },
    "compress": true,
    "large_threshold": 250,
    "shard": [0, 1],
    "presence": {
      "activities": [{
        "name": "Cards Against Humanity",
        "type": 0
      }],
      "status": "dnd",
      "since": 91879201,
      "afk": false
    },
    "intents": 7
  }
}

Resume

Used to replay missed events when a disconnected client resumes. See Resuming for details.

Resume Structure

Field	Type	Description
token	string	Session token
session_id	string	Session ID
seq	integer	Last sequence number received

{
  "op": 6,
  "d": {
    "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.

{
  "op": 1,
  "d": 251
}

Request Guild Members

Used to request all members for a guild or a list of guilds. The server responds with Guild Members Chunk events with up to 1000 members per chunk.

A new rate limit is being introduced for this opcode. See Introducing Rate Limit When Requesting All Guild Members for details.

Limitations:

GUILD_PRESENCES intent required to set presences = true
GUILD_MEMBERS intent required to request the entire member list
Limited to 1 guild_id per request
query prefix returns a maximum of 100 members
user_ids limited to returning 100 members

Request Guild Members Structure

Field	Type	Description	Required
guild_id	snowflake	ID of the guild to get members for	true
query?	string	String that username starts with, or an empty string to return all members	one of query or user_ids
limit	integer	Maximum number of members to send matching the `query`; a limit of `0` can be used with an empty string `query` to return all members	true when specifying query
presences?	boolean	Used to specify if we want the presences of the matched members	false
user_ids?	snowflake or array of snowflakes	Used to specify which users you wish to fetch	one of query or user_ids
nonce?	string	Nonce to identify the Guild Members Chunk response	false

Nonce can only be up to 32 bytes. Invalid nonces are ignored and the reply member_chunk(s) will not have a nonce set.

{
  "op": 8,
  "d": {
    "guild_id": "41771983444115456",
    "query": "",
    "limit": 0
  }
}

Request Soundboard Sounds

Used to request soundboard sounds for a list of guilds. The server responds with Soundboard Sounds events for each guild.

Request Soundboard Sounds Structure

Field	Type	Description
guild_ids	array of snowflakes	IDs of the guilds to get soundboard sounds for

{
  "op": 31,
  "d": {
    "guild_ids": ["613425648685547541", "81384788765712384"]
  }
}

Update Voice State

Sent when a client wants to join, move, or disconnect from a voice channel.

Gateway Voice State Update Structure

Field	Type	Description
guild_id	snowflake	ID of the guild
channel_id	?snowflake	ID of the voice channel client wants to join (null if disconnecting)
self_mute	boolean	Whether the client is muted
self_deaf	boolean	Whether the client is deafened

{
  "op": 4,
  "d": {
    "guild_id": "41771983423143937",
    "channel_id": "127121515262115840",
    "self_mute": false,
    "self_deaf": false
  }
}

Update Presence

Sent by the client to indicate a presence or status update.

Gateway Presence Update Structure

Field	Type	Description
since	?integer	Unix time (in milliseconds) of when the client went idle, or null if the client is not idle
activities	array of activity objects	User’s activities
status	string	User’s new status
afk	boolean	Whether or not the client is AFK

Status Types

Status	Description
online	Online
dnd	Do Not Disturb
idle	AFK
invisible	Invisible and shown as offline
offline	Offline

{
  "op": 3,
  "d": {
    "since": 91879201,
    "activities": [{
      "name": "Save the Oxford Comma",
      "type": 0
    }],
    "status": "online",
    "afk": false
  }
}

Receive Events

Receive events are Gateway events sent by Discord to an app through a Gateway connection.

Connection
Guilds
Channels & Messages
Voice & Presence

Name	Description
Hello	Defines the heartbeat interval
Ready	Contains the initial state information
Resumed	Response to Resume
Reconnect	Server is going away, client should reconnect and resume
Rate Limited	Application was rate limited for a gateway opcode
Invalid Session	Failure response to Identify or Resume or invalid active session

Name	Description
Guild Create	Lazy-load for unavailable guild, guild became available, or user joined a new guild
Guild Update	Guild was updated
Guild Delete	Guild became unavailable, or user left/was removed from a guild
Guild Audit Log Entry Create	A guild audit log entry was created
Guild Ban Add	User was banned from a guild
Guild Ban Remove	User was unbanned from a guild
Guild Emojis Update	Guild emojis were updated
Guild Stickers Update	Guild stickers were updated
Guild Integrations Update	Guild integration was updated
Guild Member Add	New user joined a guild
Guild Member Remove	User was removed from a guild
Guild Member Update	Guild member was updated
Guild Members Chunk	Response to Request Guild Members
Guild Role Create	Guild role was created
Guild Role Update	Guild role was updated
Guild Role Delete	Guild role was deleted
Guild Scheduled Event Create	Guild scheduled event was created
Guild Scheduled Event Update	Guild scheduled event was updated
Guild Scheduled Event Delete	Guild scheduled event was deleted
Guild Scheduled Event User Add	User subscribed to a guild scheduled event
Guild Scheduled Event User Remove	User unsubscribed from a guild scheduled event
Guild Soundboard Sound Create	Guild soundboard sound was created
Guild Soundboard Sound Update	Guild soundboard sound was updated
Guild Soundboard Sound Delete	Guild soundboard sound was deleted
Guild Soundboard Sounds Update	Guild soundboard sounds were updated
Soundboard Sounds	Response to Request Soundboard Sounds

Name	Description
Channel Create	New guild channel created
Channel Update	Channel was updated
Channel Delete	Channel was deleted
Channel Pins Update	Message was pinned or unpinned
Thread Create	Thread created, also sent when being added to a private thread
Thread Update	Thread was updated
Thread Delete	Thread was deleted
Thread List Sync	Sent when gaining access to a channel
Thread Member Update	Thread member for the current user was updated
Thread Members Update	Some user(s) were added to or removed from a thread
Message Create	Message was created
Message Update	Message was edited
Message Delete	Message was deleted
Message Delete Bulk	Multiple messages were deleted at once
Message Reaction Add	User reacted to a message
Message Reaction Remove	User removed a reaction from a message
Message Reaction Remove All	All reactions were explicitly removed from a message
Message Reaction Remove Emoji	All reactions for a given emoji were explicitly removed from a message
Typing Start	User started typing in a channel
Webhooks Update	Guild channel webhook was created, updated, or deleted
Interaction Create	User used an interaction
Message Poll Vote Add	User voted on a poll
Message Poll Vote Remove	User removed a vote on a poll

Name	Description
Presence Update	User was updated
Voice Channel Effect Send	Someone sent an effect in a voice channel the current user is connected to
Voice State Update	Someone joined, left, or moved a voice channel
Voice Server Update	Guild’s voice server was updated
Stage Instance Create	Stage instance was created
Stage Instance Update	Stage instance was updated
Stage Instance Delete	Stage instance was deleted or closed

Hello

Sent on connection to the websocket. Defines the heartbeat interval.

Hello Structure

Field	Type	Description
heartbeat_interval	integer	Interval (in milliseconds) an app should heartbeat with

{
  "op": 10,
  "d": {
    "heartbeat_interval": 45000
  }
}

Ready

The ready event is dispatched when a client has completed the initial handshake with the gateway. It contains all state required for a client to begin interacting with the rest of the platform. guilds starts out as unavailable when you connect. As they become available, you’ll be notified via Guild Create events.

Ready Event Fields

Field	Type	Description
v	integer	API version
user	user object	Information about the user including email
guilds	array of Unavailable Guild objects	Guilds the user is in
session_id	string	Used for resuming connections
resume_gateway_url	string	Gateway URL for resuming connections
shard?	array of two integers (shard_id, num_shards)	Shard information associated with this session, if sent when identifying
application	partial application object	Contains `id` and `flags`

Resumed

Dispatched when a client has sent a resume payload to the gateway for resuming an existing session. No data fields.

Reconnect

Dispatched when a client should reconnect to the gateway (and resume their existing session, if they have one). A few seconds after this event, the connection may be closed by the server.

{
  "op": 7,
  "d": null
}

Invalid Session

Sent to indicate one of:

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.

The inner d key is a boolean indicating whether the session may be resumable.

{
  "op": 9,
  "d": false
}

Rate Limited

Sent when an app encounters a gateway rate limit for an event, such as Request Guild Members.

Field	Type	Description
opcode	integer	Gateway opcode that was rate limited
retry_after	float	Number of seconds to wait before submitting another request
meta	object	Metadata for the event that was rate limited

Application Commands

Application Command Permissions Update

APPLICATION_COMMAND_PERMISSIONS_UPDATE — Sent when an application command’s permissions are updated. The inner payload is an application command permissions object.

Auto Moderation

All Auto Moderation events are only sent to bot users with the MANAGE_GUILD permission.

Auto Moderation Rule Create

Sent when a rule is created. Inner payload is an auto moderation rule object.

Auto Moderation Rule Update

Sent when a rule is updated. Inner payload is an auto moderation rule object.

Auto Moderation Rule Delete

Sent when a rule is deleted. Inner payload is an auto moderation rule object.

Auto Moderation Action Execution

Sent when a rule is triggered and an action is executed (e.g. when a message is blocked).

Field	Type	Description
guild_id	snowflake	ID of the guild in which action was executed
action	auto moderation action object	Action which was executed
rule_id	snowflake	ID of the rule which action belongs to
rule_trigger_type	trigger_type	Trigger type of rule which was triggered
user_id	snowflake	ID of the user which generated the content which triggered the rule
channel_id?	snowflake	ID of the channel in which user content was posted
message_id?	snowflake	ID of any user message which content belongs to *
alert_system_message_id?	snowflake	ID of any system auto moderation messages posted as a result of this action **
content ***	string	User-generated text content
matched_keyword	?string	Word or phrase configured in the rule that triggered the rule
matched_content ***	?string	Substring in content that triggered the rule

* message_id will not exist if message was blocked by Auto Moderation or content was not part of any message. ** alert_system_message_id will not exist if this event does not correspond to an action with type SEND_ALERT_MESSAGE. *** MESSAGE_CONTENT (1 << 15) gateway intent is required to receive the content and matched_content fields.

Channels

Channel Create

Sent when a new guild channel is created. Inner payload is a channel object.

Channel Update

Sent when a channel is updated. Inner payload is a channel object. Not sent when last_message_id is altered.

Channel Delete

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

Thread Create

Sent when a thread is created or when the current user is added to a thread. Inner payload is a channel object.

When a thread is created, includes an additional newly_created boolean field.
When being added to an existing private thread, includes a thread member object.

Thread Update

Sent when a thread is updated. Inner payload is a channel object.

Thread Delete

Sent when a thread is deleted. Inner payload is a subset of the channel object: id, guild_id, parent_id, and type fields only.

Thread List Sync

Sent when the current user gains access to a channel.

Field	Type	Description
guild_id	snowflake	ID of the guild
channel_ids?	array of snowflakes	Parent channel IDs whose threads are being synced. If omitted, threads were synced for the entire guild.
threads	array of channel objects	All active threads in the given channels that the current user can access
members	array of thread member objects	All thread member objects from the synced threads for the current user

Thread Member Update

Sent when the thread member object for the current user is updated.

Field	Type	Description
guild_id	snowflake	ID of the guild

Thread Members Update

Sent when anyone is added to or removed from a thread. If the current user does not have the GUILD_MEMBERS intent, this event will only be sent if the current user was added or removed.

Field	Type	Description
id	snowflake	ID of the thread
guild_id	snowflake	ID of the guild
member_count	integer	Approximate number of members in the thread, capped at 50
added_members?*	array of thread member objects	Users who were added to the thread
removed_member_ids?	array of snowflakes	ID of the users who were removed from the thread

* In this event, the thread member objects also include the guild member and nullable presence objects for each added thread member.

Channel Pins Update

Sent when a message is pinned or unpinned in a text channel (not when a pinned message is deleted).

Field	Type	Description
guild_id?	snowflake	ID of the guild
channel_id	snowflake	ID of the channel
last_pin_timestamp?	?ISO8601 timestamp	Time at which the most recent pinned message was pinned

Entitlements

Entitlement Create

ENTITLEMENT_CREATE event behavior changed on October 1, 2024. See the Change Log for details.

Sent when an entitlement is created. Inner payload is an entitlement object.

Entitlement Update

ENTITLEMENT_UPDATE event behavior changed on October 1, 2024. See the Change Log for details.

Sent when an entitlement is updated. For subscription entitlements, this is triggered when a user’s subscription ends, providing an ends_at timestamp.

Entitlement Delete

Sent when an entitlement is deleted. Entitlement deletions are infrequent and occur when Discord issues a refund, removes an entitlement via internal tooling, or deletes an app-managed entitlement. Entitlements are not deleted when they expire.

Guilds

Guild Create

This event can be sent in three scenarios:

When initially connecting, to lazily load and backfill information for all unavailable guilds sent in the Ready event.
When a guild becomes available again to the client.
When the current user joins a new guild.

During an outage, the guild object in scenarios 1 and 3 may be marked as unavailable.

Guild Create Extra Fields

Field	Type	Description
joined_at	ISO8601 timestamp	When this guild was joined at
large	boolean	`true` if this is considered a large guild
unavailable?	boolean	`true` if this guild is unavailable due to an outage
member_count	integer	Total number of members in this guild
voice_states	array of partial voice state objects	States of members currently in voice channels; lacks the `guild_id` key
members	array of guild member objects	Users in the guild
channels	array of channel objects	Channels in the guild
threads	array of channel objects	All active threads in the guild that the current user has permission to view
presences	array of partial presence update objects	Presences of the members in the guild (only includes non-offline members if size is greater than `large threshold`)
stage_instances	array of stage instance objects	Stage instances in the guild
guild_scheduled_events	array of guild scheduled event objects	Scheduled events in the guild
soundboard_sounds	array of soundboard sound objects	Soundboard sounds in the guild

If your bot does not have the GUILD_PRESENCES Gateway Intent, or if the guild has over 75k members, members and presences returned in this event will only contain your bot and users in voice channels.

Guild Update

Sent when a guild is updated. Inner payload is a guild object.

Guild Delete

Sent when a guild becomes or was already unavailable due to an outage, or when the user leaves or is removed from a guild. Inner payload is an unavailable guild object. If unavailable is not set, the user was removed from the guild.

Guild Audit Log Entry Create

Sent when a guild audit log entry is created. Only sent to bots with the VIEW_AUDIT_LOG permission.

Field	Type	Description
guild_id	snowflake	ID of the guild

Guild Ban Add

Sent when a user is banned from a guild. Only sent to bots with the BAN_MEMBERS or VIEW_AUDIT_LOG permission.

Field	Type	Description
guild_id	snowflake	ID of the guild
user	user object	User who was banned

Guild Ban Remove

Sent when a user is unbanned from a guild. Only sent to bots with the BAN_MEMBERS or VIEW_AUDIT_LOG permission.

Field	Type	Description
guild_id	snowflake	ID of the guild
user	user object	User who was unbanned

Guild Emojis Update

Field	Type	Description
guild_id	snowflake	ID of the guild
emojis	array	Array of emojis

Guild Stickers Update

Field	Type	Description
guild_id	snowflake	ID of the guild
stickers	array	Array of stickers

Guild Integrations Update

Field	Type	Description
guild_id	snowflake	ID of the guild whose integrations were updated

Guild Member Add

The GUILD_MEMBERS intent is required to receive this event.

Sent when a new user joins a guild. Inner payload is a guild member object with an extra guild_id key.

Guild Member Remove

The GUILD_MEMBERS intent is required to receive this event.

Sent when a user is removed from a guild (leave/kick/ban).

Field	Type	Description
guild_id	snowflake	ID of the guild
user	user object	User who was removed

Guild Member Update

The GUILD_MEMBERS intent is required to receive this event.

Sent when a guild member is updated, including when the user object of a guild member changes.

Field	Type	Description
guild_id	snowflake	ID of the guild
roles	array of snowflakes	User role ids
user	user object	User
nick?	?string	Nickname of the user in the guild
avatar	?string	Member’s guild avatar hash
banner	?string	Member’s guild banner hash
joined_at	?ISO8601 timestamp	When the user joined the guild
premium_since?	?ISO8601 timestamp	When the user started boosting the guild
deaf?	boolean	Whether the user is deafened in voice channels
mute?	boolean	Whether the user is muted in voice channels
pending?	boolean	Whether the user has not yet passed the guild’s Membership Screening
communication_disabled_until?	?ISO8601 timestamp	When the user’s timeout expires; null or past if not timed out
avatar_decoration_data?	?object	Data for the member’s guild avatar decoration
collectibles?	?object	Data for the member’s collectibles

Guild Members Chunk

Sent in response to Request Guild Members. Use chunk_index and chunk_count to track progress.

Field	Type	Description
guild_id	snowflake	ID of the guild
members	array of guild member objects	Set of guild members
chunk_index	integer	Chunk index in the expected chunks for this response (`0 <= chunk_index < chunk_count`)
chunk_count	integer	Total number of expected chunks for this response
not_found?	array	When passing an invalid ID to REQUEST_GUILD_MEMBERS, it will be returned here
presences?	array of presence objects	When passing `true` to REQUEST_GUILD_MEMBERS, presences of the returned members
nonce?	string	Nonce used in the Guild Members Request

Guild Role Create

Field	Type	Description
guild_id	snowflake	ID of the guild
role	role object	Role that was created

Guild Role Update

Field	Type	Description
guild_id	snowflake	ID of the guild
role	role object	Role that was updated

Guild Role Delete

Field	Type	Description
guild_id	snowflake	ID of the guild
role_id	snowflake	ID of the role

Guild Scheduled Event Create

Sent when a guild scheduled event is created. Inner payload is a guild scheduled event object.

Guild Scheduled Event Update

Sent when a guild scheduled event is updated. Inner payload is a guild scheduled event object.

Guild Scheduled Event Delete

Sent when a guild scheduled event is deleted. Inner payload is a guild scheduled event object.

Guild Scheduled Event User Add

Field	Type	Description
guild_scheduled_event_id	snowflake	ID of the guild scheduled event
user_id	snowflake	ID of the user
guild_id	snowflake	ID of the guild

Guild Scheduled Event User Remove

Field	Type	Description
guild_scheduled_event_id	snowflake	ID of the guild scheduled event
user_id	snowflake	ID of the user
guild_id	snowflake	ID of the guild

Guild Soundboard Sound Create

Sent when a guild soundboard sound is created. Inner payload is a soundboard sound object.

Guild Soundboard Sound Update

Sent when a guild soundboard sound is updated. Inner payload is a soundboard sound object.

Guild Soundboard Sound Delete

Field	Type	Description
sound_id	snowflake	ID of the sound that was deleted
guild_id	snowflake	ID of the guild the sound was in

Guild Soundboard Sounds Update

Field	Type	Description
soundboard_sounds	array of soundboard sound objects	The guild’s soundboard sounds
guild_id	snowflake	ID of the guild

Soundboard Sounds

Response to Request Soundboard Sounds.

Field	Type	Description
soundboard_sounds	array of soundboard sound objects	The guild’s soundboard sounds
guild_id	snowflake	ID of the guild

Integrations

Integration Create

Sent when an integration is created. Inner payload is an integration object with user omitted and an additional guild_id key.

Integration Update

Sent when an integration is updated. Same structure as Integration Create.

Integration Delete

Field	Type	Description
id	snowflake	Integration ID
guild_id	snowflake	ID of the guild
application_id?	snowflake	ID of the bot/OAuth2 application for this discord integration

Invites

All invite-related events are only sent to bot users with the MANAGE_CHANNELS permission on the channel.

Invite Create

Field	Type	Description
channel_id	snowflake	Channel the invite is for
code	string	Unique invite code
created_at	ISO8601 timestamp	Time at which the invite was created
guild_id?	snowflake	Guild of the invite
inviter?	user object	User that created the invite
max_age	integer	How long the invite is valid for (in seconds)
max_uses	integer	Maximum number of times the invite can be used
target_type?	integer	Type of target for this voice channel invite
target_user?	user object	User whose stream to display for this voice channel stream invite
target_application?	partial application object	Embedded application to open for this voice channel embedded application invite
temporary	boolean	Whether or not the invite is temporary
uses	integer	How many times the invite has been used (always 0)
expires_at	?ISO8601 timestamp	The expiration date of this invite
role_ids?	array of snowflakes	Role IDs given to users that accept this invite

Invite Delete

Field	Type	Description
channel_id	snowflake	Channel of the invite
guild_id?	snowflake	Guild of the invite
code	string	Unique invite code

Messages

Unlike persistent messages, ephemeral messages are sent directly to the user and bot rather than through the guild channel. They are tied to the DIRECT_MESSAGES intent, and the message object won’t include guild_id or member.

Message Create

Sent when a message is created. Inner payload is a message object with extra fields:

Field	Type	Description
guild_id?	snowflake	ID of the guild the message was sent in (unless ephemeral)
member?	partial guild member	Member properties for this message’s author. Missing for ephemeral messages and webhook messages
mentions	array of user objects	Users specifically mentioned in the message

Message Update

Sent when a message is edited. Same extra fields as Message Create.

The value for tts will always be false in message updates.

Message Delete

Field	Type	Description
id	snowflake	ID of the message
channel_id	snowflake	ID of the channel
guild_id?	snowflake	ID of the guild

Message Delete Bulk

Field	Type	Description
ids	array of snowflakes	IDs of the messages
channel_id	snowflake	ID of the channel
guild_id?	snowflake	ID of the guild

Message Reaction Add

Field	Type	Description
user_id	snowflake	ID of the user
channel_id	snowflake	ID of the channel
message_id	snowflake	ID of the message
guild_id?	snowflake	ID of the guild
member?	member object	Member who reacted if this happened in a guild
emoji	partial emoji object	Emoji used to react
message_author_id?	snowflake	ID of the user who authored the message that was reacted to
burst	boolean	`true` if this is a super-reaction
burst_colors?	array of strings	Colors used for super-reaction animation in “#rrggbb” format
type	integer	The type of reaction

Message Reaction Remove

Field	Type	Description
user_id	snowflake	ID of the user
channel_id	snowflake	ID of the channel
message_id	snowflake	ID of the message
guild_id?	snowflake	ID of the guild
emoji	partial emoji object	Emoji used to react
burst	boolean	`true` if this was a super-reaction
type	integer	The type of reaction

Message Reaction Remove All

Field	Type	Description
channel_id	snowflake	ID of the channel
message_id	snowflake	ID of the message
guild_id?	snowflake	ID of the guild

Message Reaction Remove Emoji

Field	Type	Description
channel_id	snowflake	ID of the channel
guild_id?	snowflake	ID of the guild
message_id	snowflake	ID of the message
emoji	partial emoji object	Emoji that was removed

Presence

Presence Update

You must specify the GUILD_PRESENCES intent to receive Presence Update events.

The user object within this event can be partial—only the id field is guaranteed. No fields are required and types are not validated. Your client should expect any combination of fields.

Field	Type	Description
user	user object	User whose presence is being updated
guild_id	snowflake	ID of the guild
status	string	Either “idle”, “dnd”, “online”, or “offline”
activities	array of activity objects	User’s current activities
client_status	client_status object	User’s platform-dependent status

Client Status Object

Active sessions are indicated with an “online”, “idle”, or “dnd” string per platform. Offline or invisible users do not have corresponding fields.

Field	Type	Description
desktop?	string	User’s status set for an active desktop (Windows, Linux, Mac) application session
mobile?	string	User’s status set for an active mobile (iOS, Android) application session
web?	string	User’s status set for an active web (browser, bot user) application session

Activity Object

Activity Structure

Field	Type	Description
name	string	Activity’s name
type	integer	Activity type
url?	?string	Stream URL (validated when type is 1)
created_at	integer	Unix timestamp (in milliseconds) of when the activity was added to the user’s session
timestamps?	timestamps object	Unix timestamps for start and/or end of the game
application_id?	snowflake	Application ID for the game
details?	?string	What the player is currently doing
state?	?string	User’s current party status, or text used for a custom status
emoji?	?emoji object	Emoji used for a custom status
party?	party object	Information for the current party of the player
assets?	assets object	Images for the presence and their hover texts
secrets?	secrets object	Secrets for Rich Presence joining and spectating
instance?	boolean	Whether or not the activity is an instanced game session
flags?	integer	Activity flags `OR`d together
buttons?	array of buttons	Custom buttons shown in the Rich Presence (max 2)

Bot users are only able to set name, state, type, and url.

Activity Types

ID	Name	Format	Example
0	Playing	Playing `{name}`	”Playing Rocket League”
1	Streaming	Streaming `{details}`	”Streaming Rocket League”
2	Listening	Listening to `{name}`	”Listening to Spotify”
3	Watching	Watching `{name}`	”Watching YouTube Together”
4	Custom	`{emoji}` `{state}`	”:smiley: I am cool”
5	Competing	Competing in `{name}`	”Competing in Arena World Champions”

The streaming type currently only supports Twitch and YouTube. Only https://twitch.tv/ and https://youtube.com/ URLs will work.

Activity Timestamps

Field	Type	Description
start?	integer	Unix time (in milliseconds) of when the activity started
end?	integer	Unix time (in milliseconds) of when the activity ends

Activity Flags

Name	Value
INSTANCE	`1 << 0`
JOIN	`1 << 1`
SPECTATE	`1 << 2`
JOIN_REQUEST	`1 << 3`
SYNC	`1 << 4`
PLAY	`1 << 5`
PARTY_PRIVACY_FRIENDS	`1 << 6`
PARTY_PRIVACY_VOICE_CHANNEL	`1 << 7`
EMBEDDED	`1 << 8`

Clients may only update their game status 5 times per 20 seconds.

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"
  }
}

Typing

Typing Start

Sent when a user starts typing in a channel.

Field	Type	Description
channel_id	snowflake	ID of the channel
guild_id?	snowflake	ID of the guild
user_id	snowflake	ID of the user
timestamp	integer	Unix time (in seconds) of when the user started typing
member?	member object	Member who started typing if this happened in a guild

Users

User Update

Sent when properties about the current bot’s user change. Inner payload is a user object.

Voice

Voice Channel Effect Send

Sent when someone sends an effect (emoji reaction or soundboard sound) in a voice channel the current user is connected to.

Field	Type	Description
channel_id	snowflake	ID of the channel the effect was sent in
guild_id	snowflake	ID of the guild the effect was sent in
user_id	snowflake	ID of the user who sent the effect
emoji?	?emoji object	The emoji sent, for emoji reaction and soundboard effects
animation_type?	?integer	The type of emoji animation (`0` = PREMIUM, `1` = BASIC)
animation_id?	integer	The ID of the emoji animation
sound_id?	snowflake or integer	The ID of the soundboard sound
sound_volume?	double	The volume of the soundboard sound, from 0 to 1

Voice State Update

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

Voice Server Update

Sent when a guild’s voice server is updated (initially connecting to voice, or when the current voice instance fails over).

A null endpoint means the voice server allocated has gone away and is being reallocated. Disconnect from the current voice server and do not attempt to reconnect until a new voice server is allocated.

Field	Type	Description
token	string	Voice connection token
guild_id	snowflake	Guild this voice server update is for
endpoint	?string	Voice server host

{
  "token": "my_token",
  "guild_id": "41771983423143937",
  "endpoint": "sweetwater-12345.discord.media:2048"
}

Webhooks

Webhooks Update

Sent when a guild channel’s webhook is created, updated, or deleted.

Field	Type	Description
guild_id	snowflake	ID of the guild
channel_id	snowflake	ID of the channel

Interactions

Interaction Create

Sent when a user uses an Application Command or Message Component. Inner payload is an Interaction object.

Stage Instances

Stage Instance Create

Sent when a Stage instance is created (Stage is now “live”). Inner payload is a Stage instance object.

Stage Instance Update

Sent when a Stage instance has been updated. Inner payload is a Stage instance object.

Stage Instance Delete

Sent when a Stage instance has been deleted (Stage has been closed). Inner payload is a Stage instance object.

Subscriptions

Subscription Create

Subscription status should not be used to grant perks. Use entitlements instead. See Implementing App Subscriptions for more information.

Sent when a Subscription for a Premium App is created. Inner payload is a Subscription object. A subscription’s status can be either inactive or active. You will receive subsequent SUBSCRIPTION_UPDATE events if the status updates to active.

Subscription Update

Sent when a Subscription for a Premium App is updated. Inner payload is a Subscription object.

Subscription Delete

Sent when a Subscription for a Premium App is deleted. Inner payload is a Subscription object.

Polls

Message Poll Vote Add

Sent when a user votes on a poll. If the poll allows multiple selection, one event is sent per answer.

Field	Type	Description
user_id	snowflake	ID of the user
channel_id	snowflake	ID of the channel
message_id	snowflake	ID of the message
guild_id?	snowflake	ID of the guild
answer_id	integer	ID of the answer

Message Poll Vote Remove

Sent when a user removes their vote on a poll.

Field	Type	Description
user_id	snowflake	ID of the user
channel_id	snowflake	ID of the channel
message_id	snowflake	ID of the message
guild_id?	snowflake	ID of the guild
answer_id	integer	ID of the answer

Core Reference

Resources

Events & Gateway

Monetization Resources

Voice & RPC

​Event Names

​Payload Structure

​Send Events

​Identify

​Identify Structure

​Identify Connection Properties

​Resume

​Resume Structure

​Heartbeat

​Request Guild Members

​Request Guild Members Structure

​Request Soundboard Sounds

​Request Soundboard Sounds Structure

​Update Voice State

​Gateway Voice State Update Structure

​Update Presence

​Gateway Presence Update Structure

​Status Types

​Receive Events

​Hello

​Hello Structure

​Ready

​Ready Event Fields

​Resumed

​Reconnect

​Invalid Session

​Rate Limited

​Application Commands

​Application Command Permissions Update

​Auto Moderation

​Auto Moderation Rule Create

​Auto Moderation Rule Update

​Auto Moderation Rule Delete

​Auto Moderation Action Execution

​Channels

​Channel Create

​Channel Update

​Channel Delete

​Thread Create

​Thread Update

​Thread Delete

​Thread List Sync

​Thread Member Update

​Thread Members Update

​Channel Pins Update

​Entitlements

​Entitlement Create

​Entitlement Update

​Entitlement Delete

​Guilds

​Guild Create

​Guild Create Extra Fields

​Guild Update

​Guild Delete

​Guild Audit Log Entry Create

​Guild Ban Add

​Guild Ban Remove

​Guild Emojis Update

​Guild Stickers Update

​Guild Integrations Update

​Guild Member Add

​Guild Member Remove

​Guild Member Update

​Guild Members Chunk

​Guild Role Create

​Guild Role Update

​Guild Role Delete

​Guild Scheduled Event Create

​Guild Scheduled Event Update

​Guild Scheduled Event Delete

​Guild Scheduled Event User Add

​Guild Scheduled Event User Remove

​Guild Soundboard Sound Create

​Guild Soundboard Sound Update

​Guild Soundboard Sound Delete

Event Names

Payload Structure

Send Events

Identify

Identify Structure

Identify Connection Properties

Resume

Resume Structure

Heartbeat

Request Guild Members

Request Guild Members Structure

Request Soundboard Sounds

Request Soundboard Sounds Structure

Update Voice State

Gateway Voice State Update Structure

Update Presence

Gateway Presence Update Structure

Status Types

Receive Events

Hello

Hello Structure

Ready

Ready Event Fields

Resumed

Reconnect

Invalid Session

Rate Limited

Application Commands

Application Command Permissions Update

Auto Moderation

Auto Moderation Rule Create

Auto Moderation Rule Update

Auto Moderation Rule Delete

Auto Moderation Action Execution

Channels

Channel Create

Channel Update

Channel Delete

Thread Create

Thread Update

Thread Delete

Thread List Sync

Thread Member Update

Thread Members Update

Channel Pins Update

Entitlements

Entitlement Create

Entitlement Update

Entitlement Delete

Guilds

Guild Create

Guild Create Extra Fields

Guild Update

Guild Delete

Guild Audit Log Entry Create

Guild Ban Add

Guild Ban Remove

Guild Emojis Update

Guild Stickers Update

Guild Integrations Update

Guild Member Add

Guild Member Remove

Guild Member Update

Guild Members Chunk

Guild Role Create

Guild Role Update

Guild Role Delete

Guild Scheduled Event Create

Guild Scheduled Event Update

Guild Scheduled Event Delete

Guild Scheduled Event User Add

Guild Scheduled Event User Remove

Guild Soundboard Sound Create

Guild Soundboard Sound Update

Guild Soundboard Sound Delete

Guild Soundboard Sounds Update

Soundboard Sounds

Integrations

Integration Create

Integration Update