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.

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

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

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

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

Used to trigger the initial handshake with the Gateway.

Details about identifying is in the Gateway documentation.

¹ 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.

² Required for bots on API v8 and above.

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

Used to replay missed events when a disconnected client resumes.

Details about resuming are in the Gateway documentation.

{
  "op": 6,
  "d": {
    "token": "randomstring",
    "session_id": "evenmorerandomstring",
    "seq": 1337
  }
}

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.

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

Sent by the client to indicate a presence update.

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

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

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

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

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

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

¹ 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.

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

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.

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

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

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

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.

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

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.

¹ 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.

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

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

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

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

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

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

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

Details about heartbeats are in the Gateway documentation.

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

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.

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

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.

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

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.

¹ 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.

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

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).

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

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

{
  "_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}]}]"
  ]
}

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

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

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

Sent when a WebAuthn authenticator is deleted.

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

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

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

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

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

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

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.

Sent when metadata about a call changes.

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

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

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.

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

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

Sent when a voice channel's status is updated.

Sent when a message is pinned or unpinned in a text channel. This is not sent when a pinned message is deleted.

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

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

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.

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.

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.

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.

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.

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.

¹ Also include member and nullable presence fields.

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

Sent when a friend suggestion is deleted.

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

¹ 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.

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

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

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.

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

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.

Sent when a guild audit log entry is created. The inner payload is an Audit Log Entry object. Requires the VIEW_AUDIT_LOG permission.

Sent when a user is banned from a guild.

Sent when a user is unbanned from a guild.

Sent when a guild's emojis have been updated.

Sent when a guild's stickers have been updated.

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

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

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

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.

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.

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.

¹ 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.

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.

Sent when a guild role is created.

Sent when a guild role is updated.

Sent when a guild role is deleted.

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

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

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

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

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

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

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

Sent when a guild soundboard sound is deleted.

Sent in response to Request Soundboard Sounds.

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

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

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

Sent when an integration is deleted.

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

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

¹ Ephemeral messages will not include these fields.

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

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

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

Sent when a message is deleted.

Sent when multiple messages are deleted at once.

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

Sent when a user removes their vote on a poll. If the poll allows for multiple selections, one event will be sent per answer.

Sent when a user adds a reaction to a message.

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

Sent when a user removes a reaction from a message.

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

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

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

Sent in response to Request Last Messages.

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.

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

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

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

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

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

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

Sent when a user starts typing in a channel.

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

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

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

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

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.

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

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.

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

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

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

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.

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

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.

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