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

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.

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

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

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

Used to trigger the initial handshake with the gateway.

Details about identifying is in the Gateway documentation.

capabilities is a bitfield you can use to opt a bot client into gateway behaviors. It's a separate Identify bitfield from intents: intents control which events your bot client receives, while capabilities affects gateway behaviors.

{
  "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
    },
    // These intents represent 1 << 0 for GUILDS and 1 << 2 for GUILD_MODERATION
    // This connection will only receive the events defined in those two intents
    "intents": 5
  }
}

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.

Details about heartbeats are in the Gateway documentation.

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

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

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

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

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

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

{
  "op": 43,
  "d": {
    "guild_id": "613425648685547541",
    "fields": ["status", "voice_start_time"]
  }
}

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

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

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

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.

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

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

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.

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

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.

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

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

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

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

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

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

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

* 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

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

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

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

Sent when the voice channel status changes.

Sent when the voice channel start time changes.

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.

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 when the current user gains access to a channel.

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.

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.

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

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

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

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.

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.

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.

The inner payload can be:

• An available Guild: a guild object with extra fields, as noted below.
• 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 with an extra guild_id key. This event is only sent to bots with the VIEW_AUDIT_LOG permission.

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.

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.

Sent when a guild's emojis have been updated.

Sent when a guild's stickers have been updated.

Sent when a guild integration is updated.

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:

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

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

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.

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 when multiple guild soundboard sounds are updated.

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

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

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

Sent when an integration is deleted.

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

Sent when a new invite to a channel is created.

Sent when an invite is deleted.

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

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

Sent when a message is deleted.

Sent when multiple messages are deleted at once.

Sent when a user adds a reaction to a message.

Sent when a user removes a reaction from a message.

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

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

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.

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.

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.

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:

{
  "details": "24H RL Stream for Charity",
  "state": "Rocket League",
  "name": "Twitch",
  "type": 1,
  "url": "https://www.twitch.tv/discord"
}

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

Sent when a user starts typing in a channel.

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

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.

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

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.

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

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.

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

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

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

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.

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

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

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 an app encounters a gateway rate limit for an event, such as Request Guild Members.