Gateway Events

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 a client to Discord (like when identifying with the Gateway)
• Receive events are Gateway events that are sent by Discord to a client. These events typically represent something happening inside of a guild where the user is a member of, like a channel being updated.

All Gateway events are encapsulated in a Gateway payload.

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

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.

Gateway Payload Structure

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

¹ These fields are received only, and null when the op is not DISPATCH.

Example Gateway Payload (Send)

{
  "op": 2,
  "d": {}
}

Example Gateway Payload (Receive)

{
  "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 a client to Discord through a Gateway connection.

Identify

Used to trigger the initial handshake with the Gateway.

Details about identifying is in the Gateway documentation.

Identify Structure

¹ For user accounts, the status and activities specified may not always be respected. The field should only be used when re-identifying to communicate the last known presence of the user. Otherwise, the status should be unknown and activities an empty array.

² Required for bots on API v8 and above.

Example Identify

{
  "op": 2,
  "d": {
    "token": "my_token",
    "properties": {
      "os": "linux",
      "browser": "disco",
      "device": "disco"
    },
    "compress": false,
    "presence": {
      "activities": [],
      "status": "unknown",
      "since": 0,
      "afk": false
    },
    "capabilities": 16381,
    "client_state": {
      "api_code_version": 0,
      "guild_versions": {}
    }
  }
}

Resume

Used to replay missed events when a disconnected client resumes.

Details about resuming are in the Gateway documentation.

Resume Structure

Example Resume

{
  "op": 6,
  "d": {
    "token": "randomstring",
    "session_id": "30f32c5d54ae86130fc4a215c7474263",
    "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. Fires a Heartbeat ACK Gateway event.

Details about heartbeats are in the Gateway documentation.

Example Heartbeat

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

Update Presence

Sent by the client to indicate a presence update.

Update Presence Structure

Example Update Presence

{
  "op": 3,
  "d": {
    "since": 0,
    "activities": [
      {
        "application_id": "383226320970055681",
        "assets": {
          "large_image": "565945350846939145",
          "large_text": "Editing a TEXT file",
          "small_image": "565945770067623946",
          "small_text": "Visual Studio Code"
        },
        "buttons": ["View Repository"],
        "created_at": "1695164784863",
        "details": "Editing index.astro",
        "flags": 0,
        "id": "d11307d8c0abb135",
        "name": "Visual Studio Code",
        "session_id": "30f32c5d54ae86130fc4a215c7474263",
        "state": "Workspace: vendicated.dev",
        "timestamps": {
          "start": "1695164482423"
        },
        "type": 0
      }
    ],
    "status": "online",
    "afk": false
  }
}

Update Voice State

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

Update Voice State Structure

Example Update Voice State

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

Ping Voice Server

Sent when a client wants to ping a voice server. The inner d key should be set to null.

Example Ping Voice Server

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

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. Fires multiple Guild Members Chunk events 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:

• For bots, the GUILD_PRESENCES privileged intent is required to request presences
• For bots, the GUILD_MEMBERS privileged intent is required to request the entire member list (query of "" and limit of 0)
• For users, the MANAGE_ROLES, KICK_MEMBERS, or BAN_MEMBERS permissions are required to request the entire member list (query of "" and limit of 0)
• For bots, only one guild ID may be requested at a time
• Requesting a prefix (query parameter) will return a maximum of 100 members
• user_ids will be limited to 100 members

Request Guild Members Structure

¹ One of query or user_ids is required.

² Required when specifying query.

³ The 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 Call Connect

Used to request a private channel's pre-existing call data, created before the Gateway connection was established. Fires a Call Create Gateway event if a call is found.

Request Call Connect Structure

Example Request Call Connect

{
  "op": 13,
  "d": {
    "channel_id": "957057010334048288"
  }
}

Request Soundboard Sounds

Used to request soundboard sounds for a list of guilds. Fires a Soundboard Sounds Gateway event for every guild in response.

Request Soundboard Sounds Structure

Example Request Soundboard Sounds

{
  "op": 31,
  "d": {
    "guild_ids": ["41771983444115456", "1015060230222131221", "811255666990907402"]
  }
}

Request Last Messages

Used to request the last messages (indicated by the last_message_id field) from channels. Fires a Last Messages Gateway event with up to 100 messages that match the request.

Request Last Messages Structure

Example Request Last Messages

{
  "op": 34,
  "d": {
    "guild_id": "957057010334048288",
    "channel_ids": ["1145501524013895733", "1145501524013895734"]
  }
}

Search Recent Members

Used to search the 10,000 most recently joined members in a guild. Fires a Guild Members Chunk Gateway event with up to 1000 members that match the request.

Search Recent Members Structure

¹ When a query is provided, results are limited to one member.

² Pagination is based on the joined_at field descending. To paginate, you provide the member ID of the member that joined the earliest in the previously received Guild Members Chunk. You can only paginate up to 10,000 members back from the most recently joined member.

³ The nonce can only be up to 32 bytes. If you send an invalid nonce, it will be ignored, and the reply member chunk will not have a nonce set.

Example Search Recent Members

{
  "op": 35,
  "d": {
    "guild_id": "957057010334048288",
    "query": "",
    "continuation_token": null
  }
}

Request Channel Statuses

Used to request the voice channel statuses for a guild. Fires a Channel Statuses Gateway event with the requested statuses.

Request Channel Statuses Structure

Example Request Channel Statuses

{
  "op": 36,
  "d": {
    "guild_id": "957057010334048288"
  }
}

Receive Events

Received events are Gateway events encapsulated in an event payload, and are sent by Discord to a client through a Gateway connection. Most received events correspond to dispatch events that happen relevant to the current user and the guilds it is a member of.

Hello

Sent on connection to the WebSocket. Defines the heartbeat interval that the client should heartbeat to.

Hello Structure

Example Hello

{
  "op": 10,
  "d": {
    "heartbeat_interval": 41250,
    "_trace": ["[\"gateway-prd-us-east1-c-6w69\",{\"micros\":0.0}]"]
  },
  "s": null,
  "t": null
}

Heartbeat ACK

Sent in response to receiving a heartbeat to acknowledge that it has been received.

Details about heartbeats are in the Gateway documentation.

Example Heartbeat ACK

{
  "op": 11,
  "d": null,
  "s": null,
  "t": null
}

Reconnect

The reconnect event is dispatched when a client should reconnect to the Gateway (and resume their existing session, if they have one). This event usually occurs during deploys to migrate sessions gracefully off old hosts.

Example Reconnect

{
  "op": 7,
  "d": null,
  "s": null,
  "t": 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 Invalid Session

{
  "op": 9,
  "d": false,
  "s": null,
  "t": null
}

Dispatch Events

These events directly correspond with a specific action or state change that has occurred in the platform.

Ready

Sent when a client has completed the initial handshake with the Gateway (for new sessions). The Ready event is 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.

Ready Structure

¹ Feature is not available to or not tracked for bots. This field may be empty, omitted, or null.

² For bots, guilds start out as unavailable when they connect to the Gateway. As they become available, the bot will be notified via Guild Create events.

³ Requires the AUTH_TOKEN_REFRESH Gateway capability.

⁴ Omitted when using the USER_SETTINGS_PROTO Gateway capability.

⁵ Omitted when using the LAZY_USER_NOTES Gateway capability.

⁶ When using the DEDUPE_USER_OBJECTS Gateway capability, presences, as well as each guild's presences array, is replaced by merged_presences. In addition, each guild's members array will be collapsed into merged_members. Finally, the users array will contain the user objects for every user in the event. Any user object in the event will be omitted, with an ID left in its place (e.g. user_id in member objects, recipient_ids in private channel objects, etc.).

⁷ When using the PRIORITIZED_READY_PAYLOAD Gateway capability, merged_members in Ready will only include the client's member object for each guild. The rest will be sent in the Ready Supplemental event. See the gateway guild object documentation for more information about included data.

⁸ The tutorial state is cleared after a period of inactivity. A null tutorial means no indicators will be shown.

Session Type

Merged Presences Structure

¹ See the gateway guild object documentation for more information about included data.

Tutorial Structure

Gateway Application Structure

Ready Supplemental

Sent soon after Ready, with additional data that is not critical to begin interacting with the platform.

If this event is enabled, any fields received in it that are also present in Ready will not be received in Ready (unless otherwise specified).

Ready Supplemental Structure

¹ See the gateway guild object documentation for more information about included data.

Supplemental Guild Structure

Resumed

Sent when a client has sent a resume payload to the Gateway (for resuming existing sessions). Signifies the end of event replaying.

Resumed Structure

Example Resumed

{
  "_trace": [
    "[\"gateway-prd-us-east1-c-6w69\",{\"micros\":4493,\"calls\":[\"id_created\",{\"micros\":0,\"calls\":[]},\"session_lookup_time\",{\"micros\":4163,\"calls\":[]},\"session_lookup_finished\",{\"micros\":17,\"calls\":[]},\"discord-sessions-prd-2-31\",{\"micros\":66}]}]"
  ]
}

Authentication

Auth Session Change

Sent when the current session's associated auth session ID changes.

Auth Session Change Structure

Authenticator Create

Sent when a WebAuthn authenticator is created. The inner payload is an authenticator object.

Authenticator Update

Sent when a WebAuthn authenticator is updated. The inner payload is an authenticator object.

Authenticator Delete

Sent when a WebAuthn authenticator is deleted.

Authenticator Delete Structure

Application Commands

Application Command Permissions Update

Sent when an application command's permissions are updated. The inner payload is an application command permissions object.

Auto Moderation

Auto Moderation Rule Create

Sent when a rule is created. The inner payload is an automod rule object. Requires the MANAGE_GUILD permission.

Auto Moderation Rule Update

Sent when a rule is updated. The inner payload is an automod rule object. Requires the MANAGE_GUILD permission.

Auto Moderation Rule Delete

Sent when a rule is deleted. The inner payload is an automod rule object. Requires the MANAGE_GUILD permission.

Auto Moderation Action Execution

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

Auto Moderation Action Execution Structure

Auto Moderation Mention Raid Detection

Sent when a mention raid is detected. Requires the MANAGE_GUILD permission.

Auto Moderation Mention Raid Detection Structure

Calls

Call Create

Sent when a user creates a call in a private channel, or to inform the client of an existing call after a Request Call Connect.

Call Create Structure

Call Update

Sent when metadata about a call changes.

Call Update Structure

Call Delete

Sent when a call is deleted, or becomes unavailable due to an outage.

Call Delete Structure

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 or status is altered. To keep track of the last_message_id changes, you must listen for Message Create events (or Thread Create events for thread-only channels). To keep track of the status changes, you must listen for Voice Channel Status Update events.

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

Channel Delete

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

Channel Statuses

Sent in response to Request Channel Statuses. Contains the statuses for all voice channels that have one set.

Channel Statuses Structure

Channel Status Structure

Voice Channel Status Update

Sent when a voice channel's status is updated.

Voice Channel Status Update Structure

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 Structure

Channel Recipient Add

Sent when a user is added to a group direct message channel.

Channel Recipient Add Structure

Channel Recipient Remove

Sent when a user is removed from a group direct message channel.

Channel Recipient Remove Structure

Conversation Summary Update

Sent when conversation summaries are updated for a text channel. Only new or updated summaries are sent.

Conversation Summary Update Structure

DM Settings Upsell Show

May be sent when a user rejects a message request.

DM Settings Upsell Show Structure

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 the optional member field.

Thread Create Structure Extra Fields

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 to sync a guild's active thread list, or to sync specific channel lists when the current user gains access to a channel within a guild.

For bots, all active threads are synced at startup. For user accounts, only joined threads are synced, and the full list is sent through this event on subscription.

Thread List Sync Structure

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. For bots, his event largely is just a signal that you are a member of the thread. See the threads docs for more details.

Thread Member Update Structure Extra Fields

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 Structure

¹ Also include member and nullable presence fields.

Friend Suggestions

Friend Suggestion Create

Sent when a friend suggestion is created. The inner payload is a friend suggestion object.

Friend Suggestion Delete

Sent when a friend suggestion is deleted.

Friend Suggestion Delete Structure

Guilds

Gateway Guild Object

Guild objects received over the Gateway have extended attributes that are not provided in the REST API.

Gateway Guild Structure

¹ For bots without the GUILD_PRESENCES Gateway intent, user accounts, or guilds with over 75k members, this will only include the client's member and users in voice channels. User accounts additionally receive friends and implicit relationships (depending on the NO_AFFINE_USER_IDS Gateway capability), as well as users they have an open DM with.

² User accounts only receive presences for non-offline friends and implicit relationships (depending on the NO_AFFINE_USER_IDS Gateway capability), as well as users they have an open DM with. Bots with the GUILD_PRESENCES Gateway intent receive all presences.

³ User accounts are only synced threads they have been added to. Bots are synced all threads.

⁴ Omitted when using the PRIORITIZED_READY_PAYLOAD Gateway capability.

⁵ Requires the CLIENT_STATE_V2 Gateway capability. Without the capability, the properties field will be merged into the main object, along with the rest of the extended attributes.

⁶ Geo-restricted guilds will also be marked as unavailable and will not be joinable or accessable.

Unavailable Guild Object

A partial guild object. Represents an offline guild, or a guild the client is not connected to yet.

Unavailable Guild Structure

Example Unavailable Guild

{
  "id": "41771983423143937",
  "unavailable": true
}

Data Mode

Guild Create

This event can be sent in three different scenarios:

1. When a bot 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 or geo-restricted 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.

The inner payload can be:

• An available guild: a Gateway guild object.
• An unavailable guild: an unavailable guild object.

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. Requires the VIEW_AUDIT_LOG permission.

Guild Ban Add

Sent when a user is banned from a guild.

Guild Ban Add Structure

Guild Ban Remove

Sent when a user is unbanned from a guild.

Guild Ban Remove Structure

Guild Emojis Update

Sent when a guild's emojis have been updated.

Guild Emojis Update Structure

Guild Stickers Update

Sent when a guild's stickers have been updated.

Guild Stickers Update Structure

Guild Join Request Create

Sent when a user creates a guild join request. Requires the KICK_MEMBERS permission for users other than the current user.

Guild Join Request Create Structure

Guild Join Request Update

Sent when a guild join request is updated. Requires the KICK_MEMBERS permission for users other than the current user.

Guild Join Request Update Structure

Guild Join Request Delete

Sent when a guild join request is deleted. Requires the KICK_MEMBERS permission for users other than the current user.

Guild Join Request Delete Structure

Guild Member Add

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

For user accounts, this event is only sent for themselves. Users are not automatically subscribed to friends and implicit relationships or users they have an open DM with upon them joining.

Guild Member Add Extra Fields

Guild Member Remove

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

For user accounts, this event is only sent for themselves, members they are subscribed to, and in response to actions committed by the user. Users are automatically subscribed to friends and implicit relationships (depending on the NO_AFFINE_USER_IDS Gateway capability), as well as users they have an open DM with.

Guild Member Remove Structure

Guild Member Update

Sent when a guild member is updated. This will also fire when the user object of a guild member changes. Optional fields will only be included if changed.

For user accounts, this event is only sent for members they are subscribed to, and in response to actions committed by the user. Users are automatically subscribed to friends and implicit relationships (depending on the NO_AFFINE_USER_IDS Gateway capability), as well as users they have an open DM with.

Guild Member Update Structure

¹ Won't be included in contexts that are impossible for a pending member to exist in.

² If the value is a time in the past, the member's timeout has expired and they can communicate again. An event will not be sent when this happens.

Guild Members Chunk

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

Guild Members Chunk Structure

Guild Role Create

Sent when a guild role is created.

Guild Role Create Structure

Guild Role Update

Sent when a guild role is updated.

Guild Role Update Structure

Guild Role Delete

Sent when a guild role is deleted.

Guild Role Delete Structure

Guild Scheduled Events

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 Structure

Guild Scheduled Event User Remove

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

Guild Scheduled Event User Remove Structure

Guild Soundboard

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 Structure

Soundboard Sounds

Sent in response to Request Soundboard Sounds.

Soundboard Sounds Event Fields

Integrations

Guild Integrations Update

Sent when a guild integration is updated. This is sent in addition to one of the below events.

Guild Integrations Update Structure

Integration Create

Sent when an integration is created. The inner payload is an integration object with an additional guild_id key:

Integration Create Structure Extra Fields

Integration Update

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

Integration Update Structure Extra Fields

Integration Delete

Sent when an integration is deleted.

Integration Delete Structure

Invites

Invite Create

Sent when a new invite to a guild channel is created. Requires the MANAGE_CHANNELS permission.

Invite Create Structure

Invite Delete

Sent when a guild invite is deleted. Requires the MANAGE_CHANNELS permission.

Invite Delete Structure

Messages

Message Object Extra Fields

¹ Ephemeral messages will not include these fields.

² Messages sent by webhooks will not include this field, as webhooks are not guild members.

Message Create

Sent when a message is created. The inner payload is a message object with the extra structure above.

Message Update

Sent when a message is updated. The inner payload is a message object with the extra structure above.

Message Delete

Sent when a message is deleted.

Message Delete Structure

Message Delete Bulk

Sent when multiple messages are deleted at once.

Message Delete Bulk Structure

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

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

Message Reaction Add

Sent when a user adds a reaction to a message.

Message Reaction Add Structure

Message Reaction Add Many

Sent when multiple users add reactions to a message in a short period of time.

Message Reaction Add Many Structure

Debounced Reaction Structure

Message Reaction Remove

Sent when a user removes a reaction from a message.

Message Reaction Remove Structure

Message Reaction Remove All

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

Message Reaction Remove All Structure

Message Reaction Remove Emoji

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

Message Reaction Remove Emoji Structure

Recent Mention Delete

Sent when a message that mentioned the current user in the last week is acknowledged and deleted.

Recent Mention Delete Structure

Last Messages

Sent in response to Request Last Messages.

Last Messages Structure

OAuth2

OAuth2 Token Revoke

Sent when an OAuth2 application is deauthorized.

OAuth2 Token Revoke Structure

Presence

Presence Update

This event is sent when a user's presence or info, such as name or avatar, is updated. The inner payload is a presence object.

For user accounts, this event is only sent for presences they are subscribed to. Users are automatically subscribed to the overall user presence and every per-guild presence of friends and implicit relationships (depending on the NO_AFFINE_USER_IDS Gateway capability), as well as every per-guild presences of users they have an open DM with.

Relationships

Relationship Add

Sent when a relationship is created, relevant to the current user. Inner payload is a relationship object.

Relationship Add Structure Extra Fields

Relationship Update

Sent when a relationship is updated, relevant to the current user (e.g. friend nickname changed).

Relationship Update Structure

¹ Only applicable to relationships of type INCOMING_REQUEST.

Relationship Remove

Sent when a relationship is removed, relevant to the current user.

Relationship Remove Structure

¹ Only applicable to relationships of type INCOMING_REQUEST.

Stage Instances

Stage Instance Create

Sent when a stage instance is created (i.e. the stage is now "live"). The inner payload is a stage instance object.

Stage Instance Update

Sent when a stage instance is updated. The inner payload is a stage instance object.

Stage Instance Delete

Sent when a stage instance is deleted (i.e. the stage has been closed). The inner payload is a stage instance object.

Typing

Typing Start

Sent when a user starts typing in a channel.

Typing Start Structure

Current User

User Update

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

User Application Update

Sent when an integrated application is authorized or updated.

User Application Remove Structure

User Application Remove

Sent when the current user deauthorizes an integrated application.

User Application Remove Structure

User Connections Update

Sent when the current user has their connections updated. Inner payload is either a connection object, or the following object:

User Connections Update Structure

User Note Update

Sent when a note the current user has on another user is modified.

User Note Update Structure

User Settings Proto Update

Sent when the client protobuf user settings are modified.

User Settings Proto Update Structure

User Settings Proto Structure

User Settings Update

Sent when the client user `settings are modified. Inner payload is a legacy user settings object.

User Required Action Update

Sent when a user must complete a certain action (such as verifying their phone number) before continuing to use Discord.

User Required Action Update Structure

Voice

Voice State Update

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

Voice Server Update

Sent when a guild or call's voice server is updated. This is sent when initially connecting to voice, and when the current voice instance fails over to a new server.

Voice Server Update Structure

Example Voice Server Update Payload

{
  "token": "my_token",
  "guild_id": "41771983423143937",
  "endpoint": "smart.loyal.discord.media:443"
}

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 Structure

Example Voice Channel Effect Send Payload

{
  "guild_id": "839502008108580904",
  "animation_id": 0,
  "animation_type": 1,
  "channel_id": "850360749460553769",
  "emoji": {
    "animated": false,
    "id": null,
    "name": "🦆"
  },
  "sound_id": 1,
  "sound_volume": 1,
  "user_id": "852892297661906993"
}

Webhooks

Webhooks Update

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

Webhooks Update Structure

Interactions

Interaction Create

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

Session Start Limit Object

Session Start Limit Structure

Endpoints

Get Gateway

Returns an object with a single valid WebSocket URL, which the client can use for Connecting. Clients should cache this value and only call this endpoint to retrieve a new URL if they are unable to properly establish a connection using the cached version of the URL.

Response Body

Example Response

{
  "url": "wss://gateway.discord.gg/"
}

Get Gateway Bot

Returns an object based on the information in Get Gateway, plus additional metadata that can help during the operation of large or sharded bots. Unlike Get Gateway, this route should not be cached for extended periods of time as the value is not guaranteed to be the same per-call, and changes as the user joins/leaves guilds.

JSON Response

Example Response

{
  "url": "wss://gateway.discord.gg/",
  "shards": 9,
  "session_start_limit": {
    "total": 1000,
    "remaining": 999,
    "reset_after": 14400000,
    "max_concurrency": 1
  }
}