Skip to content

gateway-events.mdx

Latest commit

 

History

History
1678 lines (1226 loc) · 133 KB

gateway-events.mdx

File metadata and controls

1678 lines (1226 loc) · 133 KB
Raw
title Gateway Events
description Complete reference for all Gateway events.

import {ManualAnchor} from '/snippets/manualanchor.jsx'

Gateway connections are WebSockets, meaning they're bidirectional and either side of the WebSocket can send events to the other. The following events are split up 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 that are sent by Discord to an app. These events typically represent something happening inside of a server where an app is installed, like a channel being updated.

All Gateway events are encapsulated in a Gateway event payload.

For more information about interacting with the Gateway, you can reference the Gateway documentation.

Not all Gateway event fields are documented. You should 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 under_scores joining each word in the name. For instance, Channel Create would be CHANNEL_CREATE and Voice State Update would be VOICE_STATE_UPDATE.

For readability, event names in the following documentation are typically left in Title Case.

Payload Structure

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

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

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

###### Example Gateway Event Payload 
{
  "op": 0,
  "d": {},
  "s": 42,
  "t": "GATEWAY_EVENT_NAME"
}

Send Events

Send events are Gateway events encapsulated in an event payload, and are sent by an app to Discord through a Gateway connection.

Previously, Gateway send events were labeled as commands
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
Request Channel Info Requests ephemeral channel data for channels in a guild
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.

Details about identifying is in the Gateway documentation.

###### 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 (i.e: `$browser`) but [this syntax is deprecated](/developers/change-log#updated-connection-property-field-names). While they currently still work, it is recommended to move to non-prefixed fields. ###### Example Identify 
{
  "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
    },
    // This intent represents 1 << 0 for GUILDS, 1 << 1 for GUILD_MEMBERS, and 1 << 2 for GUILD_BANS
    // This connection will only receive the events defined in those three intents
    "intents": 7
  }
}

Resume

Used to replay missed events when a disconnected client resumes.

Details about resuming are in the Gateway documentation.

###### Resume Structure
Field Type Description
token string Session token
session_id string Session ID
seq integer Last sequence number received
###### Example Resume 
{
  "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.

Details about heartbeats are in the Gateway documentation.

###### Example Heartbeat 
{
  "op": 1,
  "d": 251
}

Request Guild Members

Used to request all members for a guild or a list of guilds. When initially connecting, if you don't have the GUILD_PRESENCES Gateway Intent, or if the guild is over 75k members, it will only send members who are in voice, plus the member for you (the connecting user). Otherwise, if a guild has over large_threshold members (value in the Gateway Identify), it will only send members who are online, have a role, have a nickname, or are in a voice channel, and if it has under large_threshold members, it will send all members. 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.

Due to our privacy and infrastructural concerns with this feature, there are some limitations that apply:

  • GUILD_PRESENCES intent is required to set presences = true. Otherwise, it will always be false
  • GUILD_MEMBERS intent is required to request the entire member list—(query=‘’, limit=0<=n)
  • You will be limited to requesting 1 guild_id per request
  • Requesting a prefix (query parameter) will return a maximum of 100 members
  • Requesting user_ids will continue to be limited to returning 100 members
We are introducing a new rate limit to the Request Guild Members opcode. See [Introducing Rate Limit When Requesting All Guild Members](/developers/change-log#introducing-rate-limit-when-requesting-all-guild-members) for more information and timeline on this new rate limit. ###### 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. If you send an invalid nonce it will be ignored and the reply member_chunk(s) will not have a nonce set. ###### Example Request Guild Members 
{
  "op": 8,
  "d": {
    "guild_id": "41771983444115456",
    "query": "",
    "limit": 0
  }
}

Request Soundboard Sounds

Used to request soundboard sounds for a list of guilds. The server will send Soundboard Sounds events for each guild in response.

###### Request Soundboard Sounds Structure
Field Type Description
guild_ids array of snowflakes IDs of the guilds to get soundboard sounds for
###### Example Request Soundboard Sounds 
{
  "op": 31,
  "d": {
    "guild_ids": ["613425648685547541", "81384788765712384"]
  }
}

Request Channel Info

Requests ephemeral channel data for channels in a guild. The server will send a Channel Info event in response.

###### Request Channel Info Structure
Field Type Description
guild_id snowflake The guild id to request channel info for
fields array of strings The fields to request. The current available fields are status and voice_start_time.
###### Example Request Channel Info 
{
  "guild_id": "613425648685547541",
  "fields": ["status", "voice_start_time"]
}

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 deafened
###### Example Gateway Voice State Update 
{
  "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
###### Example Gateway Presence Update 
{
  "op": 3,
  "d": {
    "since": 91879201,
    "activities": [{
      "name": "Save the Oxford Comma",
      "type": 0
    }],
    "status": "online",
    "afk": false
  }
}

Receive Events

Receive events are Gateway events encapsulated in an event payload, and are sent by Discord to an app through a Gateway connection. Receive events correspond to events that happen in a Discord server where the app is installed.

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 to gateway and resume
Rate Limited Application was rate limited for a gateway opcode
Invalid Session Failure response to Identify or Resume or invalid active session
Application Command Permissions Update Application command permission was updated
Auto Moderation Rule Create Auto Moderation rule was created
Auto Moderation Rule Update Auto Moderation rule was updated
Auto Moderation Rule Delete Auto Moderation rule was deleted
Auto Moderation Action Execution Auto Moderation rule was triggered and an action was executed (e.g. a message was blocked)
Channel Create New guild channel created
Channel Update Channel was updated
Channel Delete Channel was deleted
Channel Info Response to Request Channel Info
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, contains all active threads in that 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
Entitlement Create Entitlement was created
Entitlement Update Entitlement was updated or renewed
Entitlement Delete Entitlement was deleted
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
Integration Create Guild integration was created
Integration Update Guild integration was updated
Integration Delete Guild integration was deleted
Interaction Create User used an interaction, such as an Application Command
Invite Create Invite to a channel was created
Invite Delete Invite to a channel was deleted
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
Presence Update User 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
Subscription Create Premium App Subscription was created
Subscription Update Premium App Subscription was updated
Subscription Delete Premium App Subscription was deleted
Typing Start User started typing in a channel
User Update Properties about the user changed
Voice Channel Effect Send Someone sent an effect in a voice channel the current user is connected to
Voice Channel Start Time Update Voice channel start time was updated
Voice Channel Status Update Voice channel status was updated
Voice State Update Someone joined, left, or moved a voice channel
Voice Server Update Guild's voice server was updated
Webhooks Update Guild channel webhook was created, update, or deleted
Message Poll Vote Add User voted on a poll
Message Poll Vote Remove User removed a vote on a poll
Guild Scheduled Event Exception Create Guild scheduled event exception was created
Guild Scheduled Event Exception Update Guild scheduled event exception was updated
Guild Scheduled Event Exception Delete Guild scheduled event exception was deleted

Hello

Sent on connection to the websocket. Defines the heartbeat interval that an app should heartbeat to.

###### Hello Structure
Field Type Description
heartbeat_interval integer Interval (in milliseconds) an app should heartbeat with
###### Example Hello 
{
  "op": 10,
  "d": {
    "heartbeat_interval": 45000
  }
}

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.

###### 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

The resumed event is dispatched when a client has sent a resume payload to the gateway (for resuming existing sessions).

Reconnect

The reconnect event is dispatched when a client should reconnect to the gateway (and resume their existing session, if they have one). This can occur at any point in the gateway connection lifecycle, even before/in place of receiving a Hello event. A few seconds after the reconnect event is dispatched, the connection may be closed by the server.

###### Example Gateway Reconnect 
{
  "op": 7,
  "d": null
}

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 action

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

Application Commands

Application Command Permissions Update

APPLICATION_COMMAND_PERMISSIONS_UPDATE event, sent when an application command's permissions are updated. The inner payload is an application command permissions object.

Auto Moderation

All Auto Moderation related events are only sent to bot users which have the MANAGE_GUILD permission.

Auto Moderation Rule Create

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

Auto Moderation Rule Update

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

Auto Moderation Rule Delete

Sent when a rule is deleted. The 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).

###### Auto Moderation Action Execution Event Fields
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, 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. This is not sent when the field last_message_id is altered. To keep track of the last_message_id changes, you must listen for Message Create events (or Thread Create events for GUILD_FORUM and GUILD_MEDIA channels).

This event may reference roles or guild members that no longer exist in the guild.

Channel Delete

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

Channel Info

Includes ephemeral data for channels in a guild. Sent in response to Request Channel Info.

###### Channel Info Structure
Field Type Description
guild_id snowflake The guild id
channels array of channel info objects Ephemeral data for channels in the guild
###### Channel Info Channel Structure
Field Type Description
id snowflake The channel id
status? ?string The voice channel status
voice_start_time? ?integer Unix timestamp (in seconds) of when the voice session started

Voice Channel Status Update

Sent when the voice channel status changes.

Field Type Description
id snowflake The channel id
guild_id snowflake The guild id
status ?string The new voice channel status

Voice Channel Start Time Update

Sent when the voice channel start time changes.

Field Type Description
id snowflake The channel id
guild_id snowflake The guild id
voice_start_time? ?integer Unix timestamp (in seconds) of when the voice session started

Thread Create

Sent when a thread is created, relevant to the current user, or when the current user is added to a thread. The 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. The inner payload is a channel object. This is not sent when the field last_message_id is altered. To keep track of the last_message_id changes, you must listen for Message Create events.

Thread Delete

Sent when a thread relevant to the current user is deleted. The inner payload is a subset of the channel object, containing just the id, guild_id, parent_id, and type fields.

Thread List Sync

Sent when the current user gains access to a channel.

###### Thread List Sync Event Fields
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, then threads were synced for the entire guild. This array may contain channel_ids that have no active threads as well, so you know to clear that data.
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, indicating which threads the current user has been added to

Thread Member Update

Sent when the thread member object for the current user is updated. The inner payload is a thread member object with an extra guild_id field. This event is documented for completeness, but unlikely to be used by most bots. For bots, this event largely is just a signal that you are a member of the thread. See the threads docs for more details.

###### Thread Member Update Event Extra Fields
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 Gateway Intent, then this event will only be sent if the current user was added to or removed from the thread.

###### Thread Members Update Event Fields
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 gateway event, the thread member objects will 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. This is not sent when a pinned message is deleted.

###### Channel Pins Update Event Fields
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

Note: The `ENTITLEMENT_CREATE` event behavior changed on October 1, 2024. Please see the [Change Log and Entitlement Migration Guide](/developers/change-log#premium-apps-entitlement-migration-and-new-subscription-api) for more information on what changed.

Sent when an entitlement is created. The inner payload is an entitlement object.

Entitlement Update

Note: The `ENTITLEMENT_UPDATE` event behavior changed on October 1, 2024. Please see the [Change Log and Entitlement Migration Guide](/developers/change-log#premium-apps-entitlement-migration-and-new-subscription-api) for more information on what changed.

Sent when an entitlement is updated. The inner payload is an entitlement object.

For subscription entitlements, this event is triggered only when a user's subscription ends, providing an ends_at timestamp that indicates the end of the entitlement.

Entitlement Delete

Sent when an entitlement is deleted. The inner payload is an entitlement object.

Entitlement deletions are infrequent, and occur when:

  • Discord issues a refund for a subscription
  • Discord removes an entitlement from a user via internal tooling
  • Discord deletes an app-managed entitlement they created via the API

Entitlements are not deleted when they expire.

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. Guilds that are unavailable due to an outage will send a Guild Delete event.
  2. When a Guild becomes available again to the client.
  3. When the current user joins a new Guild.
During an outage, the guild object in scenarios 1 and 3 may be marked as unavailable.

The inner payload can be:

  • An available Guild: a guild object with extra fields, as noted below.
  • An unavailable Guild: an unavailable guild object.
###### 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 current user has permission to view
presences array of partial presence update objects Presences of the members in the guild, will only include non-offline members if the 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](/developers/events/gateway#gateway-intents), 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. The 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. The inner payload is an unavailable guild object. If the unavailable field is not set, the user was removed from the guild.

Guild Audit Log Entry Create

Sent when a guild audit log entry is created. The inner payload is an Audit Log Entry object with an extra guild_id key. This event is only sent to bots with the VIEW_AUDIT_LOG permission.

###### Guild Audit Log Entry Create Event Extra Fields
Field Type Description
guild_id snowflake ID of the guild

Guild Ban Add

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

###### Guild Ban Add Event Fields
Field Type Description
guild_id snowflake ID of the guild
user a user object User who was banned

Guild Ban Remove

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

###### Guild Ban Remove Event Fields
Field Type Description
guild_id snowflake ID of the guild
user a user object User who was unbanned

Guild Emojis Update

Sent when a guild's emojis have been updated.

###### Guild Emojis Update Event Fields
Field Type Description
guild_id snowflake ID of the guild
emojis array Array of emojis

Guild Stickers Update

Sent when a guild's stickers have been updated.

###### Guild Stickers Update Event Fields
Field Type Description
guild_id snowflake ID of the guild
stickers array Array of stickers

Guild Integrations Update

Sent when a guild integration is updated.

###### Guild Integrations Update Event Fields
Field Type Description
guild_id snowflake ID of the guild whose integrations were updated

Guild Member Add

If using [Gateway Intents](/developers/events/gateway#gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event.

Sent when a user joins a guild. This event may also be sent for users who are already members of the guild. The inner payload is a guild member object with an extra guild_id key:

###### Guild Member Add Extra Fields
Field Type Description
guild_id snowflake ID of the guild

Guild Member Remove

If using [Gateway Intents](/developers/events/gateway#gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event.

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

###### Guild Member Remove Event Fields
Field Type Description
guild_id snowflake ID of the guild
user a user object User who was removed

Guild Member Update

If using [Gateway Intents](/developers/events/gateway#gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event.

Sent when a guild member is updated. This will also fire when the user object of a guild member changes.

###### Guild Member Update Event Fields
Field Type Description
guild_id snowflake ID of the guild
roles array of snowflakes User role ids
user a 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 starting 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 requirements
communication_disabled_until? ?ISO8601 timestamp When the user's timeout will expire and the user will be able to communicate in the guild again, null or a time in the past if the user is not timed out
avatar_decoration_data? ?avatar decoration data Data for the member's guild avatar decoration
collectibles? ?collectibles object data for the member's collectibles

Guild Members Chunk

Sent in response to Guild Request Members. You can use the chunk_index and chunk_count to calculate how many chunks are left for your request.

###### Guild Members Chunk Event Fields
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 will be here
nonce? string Nonce used in the Guild Members Request

Guild Role Create

Sent when a guild role is created.

###### Guild Role Create Event Fields
Field Type Description
guild_id snowflake ID of the guild
role a role object Role that was created

Guild Role Update

Sent when a guild role is updated.

###### Guild Role Update Event Fields
Field Type Description
guild_id snowflake ID of the guild
role a role object Role that was updated

Guild Role Delete

Sent when a guild role is deleted.

###### Guild Role Delete Event Fields
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. The inner payload is a guild scheduled event object.

Guild Scheduled Event Update

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

Guild Scheduled Event Delete

Sent when a guild scheduled event is deleted. The inner payload is a guild scheduled event object.

Guild Scheduled Event User Add

Sent when a user has subscribed to a guild scheduled event.

###### Guild Scheduled Event User Add Event Fields
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_exception_id? snowflake ID of the guild scheduled event exception, if applicable

Guild Scheduled Event User Remove

Sent when a user has unsubscribed from a guild scheduled event.

###### Guild Scheduled Event User Remove Event Fields
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_exception_id? snowflake ID of the guild scheduled event exception, if applicable

Guild Scheduled Event Exception Create

Sent when a guild scheduled event exception is created. The inner payload is a guild scheduled event exception object with an additional guild_id key.

Guild Scheduled Event Exception Update

Sent when a guild scheduled event exception is updated. The inner payload is a guild scheduled event exception object with an additional guild_id key.

Guild Scheduled Event Exception Delete

Sent when a guild scheduled event exception is deleted. The inner payload is a guild scheduled event exception object with an additional guild_id key.

Guild Soundboard Sound Create

Sent when a guild soundboard sound is created. The inner payload is a soundboard sound object.

Guild Soundboard Sound Update

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

Guild Soundboard Sound Delete

Sent when a guild soundboard sound is deleted.

###### Guild Soundboard Sound Delete Event Fields
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

Sent when multiple guild soundboard sounds are updated.

###### Guild Soundboard Sounds Update Event Fields
Field Type Description
soundboard_sounds array of soundboard sound objects The guild's soundboard sounds
guild_id snowflake ID of the guild

Soundboard Sounds

Includes a guild's list of soundboard sounds. Sent in response to Request Soundboard Sounds.

###### Soundboard Sounds Event Fields
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. The inner payload is an integration object with user omitted and an additional guild_id key:

###### Integration Create Event Additional Fields
Field Type Description
guild_id snowflake ID of the guild

Integration Update

Sent when an integration is updated. The inner payload is an integration object with user omitted and an additional guild_id key:

###### Integration Update Event Additional Fields
Field Type Description
guild_id snowflake ID of the guild

Integration Delete

Sent when an integration is deleted.

###### Integration Delete Event Fields
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

Sent when a new invite to a channel is created.

###### Invite Create Event Fields
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 (invited users will be kicked on disconnect unless they're assigned a role)
uses integer How many times the invite has been used (always will be 0)
expires_at ?ISO8601 timestamp the expiration date of this invite
role_ids? array of snowflakes the role ID(s) for roles in the guild given to the users that accept this invite

Invite Delete

Sent when an invite is deleted.

###### Invite Delete Event Fields
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 the bot who sent the message rather than through the guild channel. Because of this, ephemeral messages are tied to the [`DIRECT_MESSAGES` intent](/developers/events/gateway#list-of-intents), and the message object won't include `guild_id` or `member`.

Message Create

Sent when a message is created. The inner payload is a message object with the following extra fields:

###### Message Create Extra Fields
Field Type Description
guild_id? snowflake ID of the guild the message was sent in - unless it is an ephemeral message
member? partial guild member object Member properties for this message's author. Missing for ephemeral messages and messages from webhooks
mentions array of user objects, optionally with an additional partial member field Users specifically mentioned in the message
channel_type? integer The type of channel the message was sent in

Message Update

Sent when a message is updated. The inner payload is a message object with the same extra fields as MESSAGE_CREATE.

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

Message Delete

Sent when a message is deleted.

###### Message Delete Event Fields
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

Sent when multiple messages are deleted at once.

###### Message Delete Bulk Event Fields
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

Sent when a user adds a reaction to a message.

###### Message Reaction Add Event Fields
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 a partial emoji object Emoji used to react - example
message_author_id? snowflake ID of the user who authored the message which 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

Sent when a user removes a reaction from a message.

###### Message Reaction Remove Event Fields
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 a partial emoji object Emoji used to react - example
burst boolean true if this was a super-reaction
type integer The type of reaction

Message Reaction Remove All

Sent when a user explicitly removes all reactions from a message.

###### Message Reaction Remove All Event Fields
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

Sent when a bot removes all instances of a given emoji from the reactions of a message.

###### Message Reaction Remove Emoji Event Fields
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

If you are using [Gateway Intents](/developers/events/gateway#gateway-intents), you _must_ specify the `GUILD_PRESENCES` intent in order to receive Presence Update events

A user's presence is their current state on a guild. This event is sent when a user's presence or info, such as name or avatar, is updated.

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
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. If a user is offline or invisible, the corresponding field is not present.

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, is 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
status_display_type? ?integer Status display type; controls which field is displayed in the user's status text in the member list
details? ?string What the player is currently doing
details_url? ?string URL that is linked when clicking on the details text
state? ?string User's current party status, or text used for a custom status
state_url? ?string URL that is linked when clicking on the state text
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 ORd together, describes what the payload includes
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. ###### Status Display Types
ID Name Example
0 Name "Listening to Spotify"
1 State "Listening to Rick Astley"
2 Details "Listening to Never Gonna Give You Up"
This applies to all activity types. "Listening" was used to serve as a consistent example of what the different fields might be used for. ###### 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
For Listening and Watching activities, you can include both start and end timestamps to display a time bar. ###### Activity Emoji
Field Type Description
name string Name of the emoji
id? snowflake ID of the emoji
animated? boolean Whether the emoji is animated
###### Activity Party
Field Type Description
id? string 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
Field Type Description
large_image? string See Activity Asset Image
large_text? string Text displayed when hovering over the large image of the activity
large_url? string URL that is opened when clicking on the large image
small_image? string See Activity Asset Image
small_text? string Text displayed when hovering over the small image of the activity
small_url? string URL that is opened when clicking on the small image
invite_cover_image? string See Activity Asset Image. Displayed as a banner on a Game Invite.
###### Activity Asset Image

Activity asset images are arbitrary strings which usually contain snowflake IDs or prefixed image IDs. Treat data within this field carefully, as it is user-specifiable and not sanitized.

To use an external image via media proxy, specify the URL as the field's value when sending. You will only receive the mp: prefix via the gateway.

Type Format Image URL
Application Asset {application_asset_id} See Application Asset Image Formatting
Media Proxy Image mp:{image_id} https://media.discordapp.net/{image_id}
**Uploaded assets** (Application Asset type) support PNG, JPEG, and WebP. Animated images are not supported for uploaded assets.

External URL assets (Media Proxy Image type) support any publicly accessible image URL, including GIF, animated WebP, and AVIF.

###### Activity Secrets
Field Type Description
join? string Secret for joining a party
spectate? string Secret for spectating a game
match? string Secret for a specific instanced match
###### 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
###### Activity Buttons

When received over the gateway, the buttons field is an array of strings, which are the button labels. Bots cannot access a user's activity button URLs. When sending, the buttons field must be an array of the below object:

Field Type Description
label string Text shown on the button (1-32 characters)
url string URL opened when clicking the button (1-512 characters)
###### Example Activity 
{
  "details": "24H RL Stream for Charity",
  "state": "Rocket League",
  "name": "Twitch",
  "type": 1,
  "url": "https://www.twitch.tv/discord"
}
###### 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 20 seconds.

Typing Start

Sent when a user starts typing in a channel.

###### Typing Start Event Fields
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

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, such as an emoji reaction or a soundboard sound, in a voice channel the current user is connected to.

###### Voice Channel Effect Send Event Fields
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, for emoji reaction and soundboard effects
animation_id? integer The ID of the emoji animation, for emoji reaction and soundboard effects
sound_id? snowflake or integer The ID of the soundboard sound, for soundboard effects
sound_volume? double The volume of the soundboard sound, from 0 to 1, for soundboard effects
###### Animation Types
Type Value Description
PREMIUM 0 A fun animation, sent by a Nitro subscriber
BASIC 1 The standard animation

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.

A null endpoint means that the voice server allocated has gone away and is trying to be reallocated. You should attempt to disconnect from the currently connected voice server, and not attempt to reconnect until a new voice server is allocated. ###### Voice Server Update Event Fields
Field Type Description
token string Voice connection token
guild_id snowflake Guild this voice server update is for
endpoint ?string Voice server host
###### Example Voice Server Update Payload 
{
  "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.

###### Webhooks Update Event Fields
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.

Stage Instances

Stage Instance Create

Sent when a Stage instance is created (i.e. the Stage is now "live"). Inner payload is a Stage instance

Stage Instance Update

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

Stage Instance Delete

Sent when a Stage instance has been deleted (i.e. the Stage has been closed). Inner payload is a Stage instance

Subscriptions

Subscription Create

Subscription status should not be used to grant perks. Use [entitlements](/developers/resources/entitlement#entitlement-object) as an indication of whether a user should have access to a specific SKU. See our guide on [Implementing App Subscriptions](/developers/monetization/implementing-app-subscriptions) for more information.

Sent when a Subscription for a Premium App is created. Inner payload is a Subscription.

A Subscription's status can be either inactive or active when this event is received. You will receive subsequent SUBSCRIPTION_UPDATE events if the status is updated to active. As a best practice, you should not grant any perks to users until the entitlements are created.

Subscription Update

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

Subscription Delete

Sent when a Subscription for a Premium App has been 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 will be sent per answer.

###### Message Poll Vote Add Fields
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. If the poll allows for multiple selections, one event will be sent per answer.

###### Message Poll Vote Remove Fields
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

Rate Limits

Rate Limited

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

See changelog for [Introducing Rate Limit When Requesting All Guild Members](/developers/change-log#introducing-rate-limit-when-requesting-all-guild-members) for more information and timeline on this new rate limit.
Rate Limited Fields
Field Type Description
opcode integer Gateway opcode of the event that was rate limited
retry_after float The number of seconds to wait before submitting another request
meta Rate Limit Metadata for Opcode Metadata for the event that was rate limited
Rate Limit Metadata for Opcode Structure
Opcode Type
8 Request Guild Member Rate Limit Metadata
Request Guild Member Rate Limit Metadata Structure
Field Type Description
guild_id snowflake ID of the guild to get members for
nonce? string nonce to identify the Guild Members Chunk response