diff --git a/docs/Reference.mdx b/docs/Reference.mdx index c59732229a..44187d361b 100644 --- a/docs/Reference.mdx +++ b/docs/Reference.mdx @@ -126,7 +126,7 @@ All HTTP-layer services and protocols (e.g. HTTP, WebSocket) within the Discord ## Snowflakes -Discord utilizes Twitter's [snowflake](https://github.com/twitter-archive/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See [Gateway ETF/JSON](#DOCS_TOPICS_GATEWAY/encoding-and-compression) for more information regarding Gateway encoding. +Discord utilizes Twitter's [snowflake](https://github.com/twitter-archive/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See [Gateway ETF/JSON](#DOCS_EVENTS_GATEWAY/encoding-and-compression) for more information regarding Gateway encoding. ###### Snowflake ID Broken Down in Binary @@ -245,7 +245,7 @@ Certain endpoints in the API are documented to accept booleans for their query s ## Gateway (WebSocket) API -Discord's Gateway API is used for maintaining persistent, stateful websocket connections between your client and our servers. These connections are used for sending and receiving real-time events your client can use to track and update local state. The Gateway API uses secure websocket connections as specified in [RFC 6455](https://tools.ietf.org/html/rfc6455). For information on opening Gateway connections, please see the [Gateway API](#DOCS_TOPICS_GATEWAY/connections) section. +Discord's Gateway API is used for maintaining persistent, stateful websocket connections between your client and our servers. These connections are used for sending and receiving real-time events your client can use to track and update local state. The Gateway API uses secure websocket connections as specified in [RFC 6455](https://tools.ietf.org/html/rfc6455). For information on opening Gateway connections, please see the [Gateway API](#DOCS_EVENTS_GATEWAY/connections) section. ## Message Formatting @@ -337,7 +337,7 @@ Discord uses ids and hashes to render images in the client. These hashes can be | Avatar Decoration | avatar-decoration-presets/[avatar_decoration_data_asset](#DOCS_RESOURCES_USER/avatar-decoration-data-object).png | PNG | | Application Icon | app-icons/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/[icon](#DOCS_RESOURCES_APPLICATION/application-object).png | PNG, JPEG, WebP | | Application Cover | app-icons/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/[cover_image](#DOCS_RESOURCES_APPLICATION/application-object).png | PNG, JPEG, WebP | -| Application Asset | app-assets/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/[asset_id](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-assets).png | PNG, JPEG, WebP | +| Application Asset | app-assets/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/[asset_id](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-assets).png | PNG, JPEG, WebP | | Achievement Icon | app-assets/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/achievements/[achievement_id](https://github.com/discord/discord-api-docs/blob/legacy-gamesdk/docs/game_sdk/Achievements.md#user-achievement-struct)/icons/[icon_hash](https://github.com/discord/discord-api-docs/blob/legacy-gamesdk/docs/game_sdk/Achievements.md#user-achievement-struct).png | PNG, JPEG, WebP | | Store Page Asset | app-assets/[application_id](#DOCS_RESOURCES_APPLICATION/application-object)/store/asset_id | PNG, JPEG, WebP | | Sticker Pack Banner | app-assets/710982414301790216/store/[sticker_pack_banner_asset_id](#DOCS_RESOURCES_STICKER/sticker-pack-object).png | PNG, JPEG, WebP | diff --git a/docs/change_log/2017-07-19-breaking-change-version-6.md b/docs/change_log/2017-07-19-breaking-change-version-6.md index eed5ec9dbc..a22dd1f12f 100644 --- a/docs/change_log/2017-07-19-breaking-change-version-6.md +++ b/docs/change_log/2017-07-19-breaking-change-version-6.md @@ -10,5 +10,5 @@ breaking: true * `recipient` is now `recipients`, an array of [user](#DOCS_RESOURCES_USER/user-object) objects * [Message](#DOCS_RESOURCES_MESSAGE/message-object) Object * [`type`](#DOCS_RESOURCES_MESSAGE/message-object-message-types) added to support system messages -* [Status Update](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence-gateway-presence-update-structure) Object +* [Status Update](#DOCS_EVENTS_GATEWAY_EVENTS/update-presence-gateway-presence-update-structure) Object * `idle_since` renamed to `since` diff --git a/docs/change_log/2017-08-16-breaking-change-presence-activity-objects.md b/docs/change_log/2017-08-16-breaking-change-presence-activity-objects.md index 4610e64f6a..989225fab1 100644 --- a/docs/change_log/2017-08-16-breaking-change-presence-activity-objects.md +++ b/docs/change_log/2017-08-16-breaking-change-presence-activity-objects.md @@ -4,4 +4,4 @@ date: "2017-08-16" breaking: true --- -The `type` field in the [activity object](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object) for [Gateway Status Update](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence) and [Presence Update](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update) payloads is no longer optional when the activity object is not null. +The `type` field in the [activity object](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object) for [Gateway Status Update](#DOCS_EVENTS_GATEWAY_EVENTS/update-presence) and [Presence Update](#DOCS_EVENTS_GATEWAY_EVENTS/presence-update) payloads is no longer optional when the activity object is not null. diff --git a/docs/change_log/2018-01-03-semi-breaking-change-very-large-bot-sharding.md b/docs/change_log/2018-01-03-semi-breaking-change-very-large-bot-sharding.md index 5632db2354..d242ab6514 100644 --- a/docs/change_log/2018-01-03-semi-breaking-change-very-large-bot-sharding.md +++ b/docs/change_log/2018-01-03-semi-breaking-change-very-large-bot-sharding.md @@ -4,4 +4,4 @@ date: "2018-01-03" breaking: true --- -Additional sharding requirements and information for bots in over 100,000 guilds has been added. This requires a small change in numbers of shards for affected bots. See the [documentation](#DOCS_TOPICS_GATEWAY/sharding-for-large-bots) for more information. +Additional sharding requirements and information for bots in over 100,000 guilds has been added. This requires a small change in numbers of shards for affected bots. See the [documentation](#DOCS_EVENTS_GATEWAY/sharding-for-large-bots) for more information. diff --git a/docs/change_log/2018-06-19-documentation-fix-list-of-open-dms-in-certain-payloads.md b/docs/change_log/2018-06-19-documentation-fix-list-of-open-dms-in-certain-payloads.md index 9112e48e0b..07ed853836 100644 --- a/docs/change_log/2018-06-19-documentation-fix-list-of-open-dms-in-certain-payloads.md +++ b/docs/change_log/2018-06-19-documentation-fix-list-of-open-dms-in-certain-payloads.md @@ -3,4 +3,4 @@ title: "Documentation Fix: List of Open DMS in Certain Payloads" date: "2018-06-19" --- -The documentation has been updated to correctly note that the `private_channels` field in the [Ready](#DOCS_TOPICS_GATEWAY_EVENTS/ready) should be an empty array, as well as the response from `/users/@me/channels` for a bot user. This change has been in effect for a long time, but the documentation was not updated. +The documentation has been updated to correctly note that the `private_channels` field in the [Ready](#DOCS_EVENTS_GATEWAY_EVENTS/ready) should be an empty array, as well as the response from `/users/@me/channels` for a bot user. This change has been in effect for a long time, but the documentation was not updated. diff --git a/docs/change_log/2020-02-14-gateway-intents.md b/docs/change_log/2020-02-14-gateway-intents.md index 072a67c848..0e28b058e8 100644 --- a/docs/change_log/2020-02-14-gateway-intents.md +++ b/docs/change_log/2020-02-14-gateway-intents.md @@ -3,14 +3,14 @@ title: "Gateway Intents" date: "2020-02-14" --- -We've added documentation around a brand new feature: [Gateway Intents!](#DOCS_TOPICS_GATEWAY/gateway-intents) Gateway Intents are a great way to specify which events you want to receive from our gateway. Go on, save yourself some bandwidth and CPU usage. +We've added documentation around a brand new feature: [Gateway Intents!](#DOCS_EVENTS_GATEWAY/gateway-intents) Gateway Intents are a great way to specify which events you want to receive from our gateway. Go on, save yourself some bandwidth and CPU usage. Using Intents will change the behavior of some existing events and commands, so please refer to: -* [Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) -* [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) -* [Guild Member Add](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-add) -* [Guild Member Remove](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-remove) -* [Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update) -* [Presence Update](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update) +* [Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) +* [Request Guild Members](#DOCS_EVENTS_GATEWAY_EVENTS/request-guild-members) +* [Guild Member Add](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-add) +* [Guild Member Remove](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-remove) +* [Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update) +* [Presence Update](#DOCS_EVENTS_GATEWAY_EVENTS/presence-update) * [List Guild Members](#DOCS_RESOURCES_GUILD/list-guild-members) diff --git a/docs/change_log/2020-03-02-new-invite-events-and-reactions-endpoint.md b/docs/change_log/2020-03-02-new-invite-events-and-reactions-endpoint.md index 779d37601b..509772e0a6 100644 --- a/docs/change_log/2020-03-02-new-invite-events-and-reactions-endpoint.md +++ b/docs/change_log/2020-03-02-new-invite-events-and-reactions-endpoint.md @@ -6,6 +6,6 @@ date: "2020-03-02" We've added a new endpoint for deleting all reactions of a specific emoji from a message, as well as some new invite and reaction gateway events. Read more: * [Delete All Reactions for Emoji](#DOCS_RESOURCES_MESSAGE/delete-all-reactions-for-emoji) -* [Invite Create](#DOCS_TOPICS_GATEWAY_EVENTS/invite-create) -* [Invite Delete](#DOCS_TOPICS_GATEWAY_EVENTS/invite-delete) -* [Message Reaction Remove Emoji](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-remove-emoji) +* [Invite Create](#DOCS_EVENTS_GATEWAY_EVENTS/invite-create) +* [Invite Delete](#DOCS_EVENTS_GATEWAY_EVENTS/invite-delete) +* [Message Reaction Remove Emoji](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-remove-emoji) diff --git a/docs/change_log/2020-04-24-new-properties-on-guild-members-chunk-event.md b/docs/change_log/2020-04-24-new-properties-on-guild-members-chunk-event.md index d9c82f3116..52c9cb506e 100644 --- a/docs/change_log/2020-04-24-new-properties-on-guild-members-chunk-event.md +++ b/docs/change_log/2020-04-24-new-properties-on-guild-members-chunk-event.md @@ -3,4 +3,4 @@ title: "New Properties on Guild Members Chunk Event" date: "2020-04-24" --- -The [Guild Members Chunk](#DOCS_TOPICS_GATEWAY_EVENTS/guild-members-chunk) gateway event now contains two properties: `chunk_index` and `chunk_count`. These values can be used to keep track of how many events you have left to receive in response to a [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) command. +The [Guild Members Chunk](#DOCS_EVENTS_GATEWAY_EVENTS/guild-members-chunk) gateway event now contains two properties: `chunk_index` and `chunk_count`. These values can be used to keep track of how many events you have left to receive in response to a [Request Guild Members](#DOCS_EVENTS_GATEWAY_EVENTS/request-guild-members) command. diff --git a/docs/change_log/2020-09-24-api-and-gateway-v8.md b/docs/change_log/2020-09-24-api-and-gateway-v8.md index c24dcf7c1b..ff5788f33c 100644 --- a/docs/change_log/2020-09-24-api-and-gateway-v8.md +++ b/docs/change_log/2020-09-24-api-and-gateway-v8.md @@ -8,8 +8,8 @@ We've introduced API and Gateway v8! Changes are noted throughout the documentat The changes are: * API and Gateway v8 are now available. v6 is still the default for the time being. -* [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents) are now required -* Removed `guild_subscriptions` in identify in favor of [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents). +* [Gateway Intents](#DOCS_EVENTS_GATEWAY/gateway-intents) are now required +* Removed `guild_subscriptions` in identify in favor of [Gateway Intents](#DOCS_EVENTS_GATEWAY/gateway-intents). * All permissions have been converted to strings-serialized numbers. As such, `permissions_new`, `allow_new`, and `deny_new` have been removed * The `game` field has been removed. If you need a direct replacement, you can instead reference the first element of `activities` * Channel Permission Overwrite `type`s are now numbers (0 and 1) instead of strings ("role" and "member"). However due to a current technical constraint, they are string-serialized numbers in audit log `options`. @@ -17,9 +17,9 @@ The changes are: * Form body errors have been improved to include more helpful messaging on validation. [See more here](#DOCS_REFERENCE/error-messages) * The `Retry-After` header value and `retry_after` body value is now based in seconds instead of milliseconds (e.g. `123` means 123 seconds) * The `X-RateLimit-Precision` header is no longer respected. `X-RateLimit-Reset` and `X-RateLimit-Reset-After` are always returned at millisecond precision (e.g. `123.456` instead of `124`) -* Bots no longer receive [Channel Create Gateway Event](#DOCS_TOPICS_GATEWAY_EVENTS/channel-create) for DMs +* Bots no longer receive [Channel Create Gateway Event](#DOCS_EVENTS_GATEWAY_EVENTS/channel-create) for DMs * `delete-message-days` is no longer available. Use `delete_message_days`. -* Removed `roles`, `premium_since`, and `nick` from [Presence Update Gateway Event](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update) +* Removed `roles`, `premium_since`, and `nick` from [Presence Update Gateway Event](#DOCS_EVENTS_GATEWAY_EVENTS/presence-update) * Removed some [integration object](#DOCS_RESOURCES_GUILD/integration-object) fields for Discord application integrations * Removed `include_applications` from [Get Guild Integrations](#DOCS_RESOURCES_GUILD/get-guild-integrations). Application integrations are always included. * The following deprecated routes have been removed for better naming conventions: diff --git a/docs/change_log/2020-10-27-gateway-v6-intent-restrictions.md b/docs/change_log/2020-10-27-gateway-v6-intent-restrictions.md index 8c96e7758d..10b194cd73 100644 --- a/docs/change_log/2020-10-27-gateway-v6-intent-restrictions.md +++ b/docs/change_log/2020-10-27-gateway-v6-intent-restrictions.md @@ -3,7 +3,7 @@ title: "Gateway v6 Intent Restrictions" date: "2020-10-27" --- -The v6 gateway now applies the restrictions for gateway intents. This means the new chunking limitations are now in effect, regardless of intents being used. See [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) for further details. +The v6 gateway now applies the restrictions for gateway intents. This means the new chunking limitations are now in effect, regardless of intents being used. See [Request Guild Members](#DOCS_EVENTS_GATEWAY_EVENTS/request-guild-members) for further details. Additionally, if privileged intents are not enabled in the application dashboard the bot will not receive the events for those intents. All other intents are always enabled by default unless specified otherwise by the identify payload. We have made a support article to explain some of the changes and resulting issues with more details: [Gateway Update FAQ](https://dis.gd/gwupdate) diff --git a/docs/change_log/2020-11-16-inline-replies.md b/docs/change_log/2020-11-16-inline-replies.md index ab615fc6ee..86f6cd2017 100644 --- a/docs/change_log/2020-11-16-inline-replies.md +++ b/docs/change_log/2020-11-16-inline-replies.md @@ -9,4 +9,4 @@ Inline Replies have been added to our documentation. They behave differently in * You can now add a `message_reference` on message create to create a reply * A new field `referenced_message` has been added to the [Message Object](#DOCS_RESOURCES_MESSAGE/message-object) * A new field `replied_user` has been added to the [Allowed Mentions Object](#DOCS_RESOURCES_MESSAGE/allowed-mentions-object) -* [Message Create](#DOCS_TOPICS_GATEWAY_EVENTS/message-create) gateway event is guaranteed to have a `referenced_message` if the message created is a reply. Otherwise, that field is not guaranteed. +* [Message Create](#DOCS_EVENTS_GATEWAY_EVENTS/message-create) gateway event is guaranteed to have a `referenced_message` if the message created is a reply. Otherwise, that field is not guaranteed. diff --git a/docs/change_log/2022-02-14-api-v10.md b/docs/change_log/2022-02-14-api-v10.md index 030d63cda2..e38ae915b7 100644 --- a/docs/change_log/2022-02-14-api-v10.md +++ b/docs/change_log/2022-02-14-api-v10.md @@ -5,7 +5,7 @@ date: "2022-02-14" * API v8 is now deprecated. * `GET /channels/{channel.id}/threads/active` is decommissioned in favor of [`GET /guilds/{guild.id}/threads/active`](#DOCS_RESOURCES_GUILD/list-active-guild-threads). -* Starting in v10, you must specify the message content intent (`1 << 15`) to receive content-related fields in message dispatches. Read more in the [Gateway Intents documentation](#DOCS_TOPICS_GATEWAY/gateway-intents). +* Starting in v10, you must specify the message content intent (`1 << 15`) to receive content-related fields in message dispatches. Read more in the [Gateway Intents documentation](#DOCS_EVENTS_GATEWAY/gateway-intents). * To specify a reason for an administrative action in audit logs, apps must now pass the `X-Audit-Log-Reason` header rather than the `reason` parameter for all endpoints. Read more in the [Audit Logs documentation](#DOCS_RESOURCES_AUDIT_LOG). * Message routes (like [`POST /channels/{channel.id}/messages`](#DOCS_RESOURCES_MESSAGE/create-message)) now use the `embeds` field (an array of embed objects) instead of `embed`. * The `summary` field for [applications](#DOCS_RESOURCES_APPLICATION) now returns an empty string for all API versions. diff --git a/docs/change_log/2022-04-27-updated-command-permissions.md b/docs/change_log/2022-04-27-updated-command-permissions.md index aba41b0150..b15c3cc24b 100644 --- a/docs/change_log/2022-04-27-updated-command-permissions.md +++ b/docs/change_log/2022-04-27-updated-command-permissions.md @@ -19,4 +19,4 @@ Application command permissions have been updated to add more granular control a * [constant (`guild_id - 1`)](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-permissions-object-application-command-permissions-constants) to represent all channels in command permissions * Added `default_member_permissions` field, which is a bitwise OR-ed set of [permissions](#DOCS_TOPICS_PERMISSIONS/permissions-bitwise-permission-flags), expressed as a string. This replaces the `default_permission` field, which will soon be deprecated. * Added `dm_permission`, which is a boolean flag used to indicate whether a command is available in DMs (only for global application commands). If no value is passed, the global command will be visible in DMs. -* Added `APPLICATION_COMMAND_PERMISSIONS_UPDATE` [gateway](#DOCS_TOPICS_GATEWAY_EVENTS/application-command-permissions-update) event and `APPLICATION_COMMAND_PERMISSION_UPDATE` [audit log](#DOCS_RESOURCES_AUDIT_LOG) event. +* Added `APPLICATION_COMMAND_PERMISSIONS_UPDATE` [gateway](#DOCS_EVENTS_GATEWAY_EVENTS/application-command-permissions-update) event and `APPLICATION_COMMAND_PERMISSION_UPDATE` [audit log](#DOCS_RESOURCES_AUDIT_LOG) event. diff --git a/docs/change_log/2022-06-16-auto-moderation.md b/docs/change_log/2022-06-16-auto-moderation.md index e3ef8328b9..df959abb32 100644 --- a/docs/change_log/2022-06-16-auto-moderation.md +++ b/docs/change_log/2022-06-16-auto-moderation.md @@ -6,6 +6,6 @@ date: "2022-06-16" Add new [Auto Moderation feature](#DOCS_RESOURCES_AUTO_MODERATION) which enables guilds to moderate message content based on keywords, harmful links, and unwanted spam. This change includes: * New endpoints for [creating](#DOCS_RESOURCES_AUTO_MODERATION/create-auto-moderation-rule), [updating](#DOCS_RESOURCES_AUTO_MODERATION/modify-auto-moderation-rule), and [deleting](#DOCS_RESOURCES_AUTO_MODERATION/delete-auto-moderation-rule) Auto Moderation rules -* New gateway events emitted when Auto Moderation rules are [created](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-create) (`AUTO_MODERATION_RULE_CREATE`), [updated](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-update) (`AUTO_MODERATION_RULE_UPDATE `), and [deleted](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-delete) (`AUTO_MODERATION_RULE_DELETE `). Requires the `AUTO_MODERATION_CONFIGURATION` (`1 << 20`) intent -* New gateway event emitted when an [action is executed](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-action-execution) (`AUTO_MODERATION_ACTION_EXECUTION`). Requires the `AUTO_MODERATION_EXECUTION` (`1 << 21`) intent +* New gateway events emitted when Auto Moderation rules are [created](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-create) (`AUTO_MODERATION_RULE_CREATE`), [updated](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-update) (`AUTO_MODERATION_RULE_UPDATE `), and [deleted](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-delete) (`AUTO_MODERATION_RULE_DELETE `). Requires the `AUTO_MODERATION_CONFIGURATION` (`1 << 20`) intent +* New gateway event emitted when an [action is executed](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-action-execution) (`AUTO_MODERATION_ACTION_EXECUTION`). Requires the `AUTO_MODERATION_EXECUTION` (`1 << 21`) intent * New [audit log entries](#DOCS_RESOURCES_AUDIT_LOG/audit-log-entry-object-audit-log-events) when rules are created (`AUTO_MODERATION_RULE_CREATE`), updated (`AUTO_MODERATION_RULE_UPDATE`), or deleted (`AUTO_MODERATION_RULE_DELETE`), or when Auto Moderation performs an action (`AUTO_MODERATION_BLOCK_MESSAGE`) diff --git a/docs/change_log/2022-06-17-updated-connection-property-field-names.md b/docs/change_log/2022-06-17-updated-connection-property-field-names.md index b5070b069f..eaa45ad7cf 100644 --- a/docs/change_log/2022-06-17-updated-connection-property-field-names.md +++ b/docs/change_log/2022-06-17-updated-connection-property-field-names.md @@ -3,6 +3,6 @@ title: "Updated Connection Property Field Names" date: "2022-06-17" --- -The `$` prefix in [identify connection properties](#DOCS_TOPICS_GATEWAY_EVENTS/identify-identify-connection-properties) are deprecated. The new field names are `os`, `browser`, and `device`. When passed, the `$`-prefixed names will resolve to the new ones. +The `$` prefix in [identify connection properties](#DOCS_EVENTS_GATEWAY_EVENTS/identify-identify-connection-properties) are deprecated. The new field names are `os`, `browser`, and `device`. When passed, the `$`-prefixed names will resolve to the new ones. In API v11, support for the previous field names (`$os`, `$browser`, and `$device`) will be removed. diff --git a/docs/change_log/2022-06-21-message-content-in-auto-moderation-events.md b/docs/change_log/2022-06-21-message-content-in-auto-moderation-events.md index 5903541ec4..f7bb8f1099 100644 --- a/docs/change_log/2022-06-21-message-content-in-auto-moderation-events.md +++ b/docs/change_log/2022-06-21-message-content-in-auto-moderation-events.md @@ -4,4 +4,4 @@ date: "2022-06-21" breaking: true --- -In API v10, the `MESSAGE_CONTENT` (`1 << 15`) intent is now required to receive non-empty values for the `content` and `matched_content` fields in [`AUTO_MODERATION_ACTION_EXECUTION`](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-action-execution) gateway events. This matches the intended behavior for message content across the API. +In API v10, the `MESSAGE_CONTENT` (`1 << 15`) intent is now required to receive non-empty values for the `content` and `matched_content` fields in [`AUTO_MODERATION_ACTION_EXECUTION`](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-action-execution) gateway events. This matches the intended behavior for message content across the API. diff --git a/docs/change_log/2022-08-09-session-specific-gateway-resume-urls.md b/docs/change_log/2022-08-09-session-specific-gateway-resume-urls.md index 50bb86712b..6a33cf3afd 100644 --- a/docs/change_log/2022-08-09-session-specific-gateway-resume-urls.md +++ b/docs/change_log/2022-08-09-session-specific-gateway-resume-urls.md @@ -6,6 +6,6 @@ date: "2022-08-09" > warn > Starting on **September 12, 2022**, apps that aren’t using the new `resume_gateway_url` field to resume gateway sessions will be disconnected significantly faster than normal. -A new `resume_gateway_url` field has been added to the [Ready](#DOCS_TOPICS_GATEWAY_EVENTS/ready) gateway event to support session-specific gateway connections. The value of `resume_gateway_url` is a session-specific URL that should be used when resuming the gateway session after a disconnect. Previously, `wss://gateway.discord.gg` was used to connect *and* resume sessions, but should now only be used during the connection. +A new `resume_gateway_url` field has been added to the [Ready](#DOCS_EVENTS_GATEWAY_EVENTS/ready) gateway event to support session-specific gateway connections. The value of `resume_gateway_url` is a session-specific URL that should be used when resuming the gateway session after a disconnect. Previously, `wss://gateway.discord.gg` was used to connect *and* resume sessions, but should now only be used during the connection. At the moment, the value of `resume_gateway_url` will always be `wss://gateway.discord.gg` to give developers more time to adopt the new field. In the near future, the value will change to the session-specific URLs. diff --git a/docs/change_log/2022-09-01-message-content-is-a-privileged-intent.md b/docs/change_log/2022-09-01-message-content-is-a-privileged-intent.md index 28e8c15b1a..2c5d2f225b 100644 --- a/docs/change_log/2022-09-01-message-content-is-a-privileged-intent.md +++ b/docs/change_log/2022-09-01-message-content-is-a-privileged-intent.md @@ -4,7 +4,7 @@ date: "2022-09-01" breaking: true --- -As of today, [message content](#DOCS_TOPICS_GATEWAY/message-content-intent) is a privileged intent for all verified apps *and* apps eligible for verification. More details about why it's becoming a privileged intent and how to apply for it is in the [Help Center FAQ](https://support-dev.discord.com/hc/articles/4404772028055-Message-Content-Privileged-Intent-FAQ). +As of today, [message content](#DOCS_EVENTS_GATEWAY/message-content-intent) is a privileged intent for all verified apps *and* apps eligible for verification. More details about why it's becoming a privileged intent and how to apply for it is in the [Help Center FAQ](https://support-dev.discord.com/hc/articles/4404772028055-Message-Content-Privileged-Intent-FAQ). Any app that does not have the message content intent configured in its app's settings within the Developer Portal will receive empty values in fields that expose message content across Discord's APIs (including the `content`, `embeds`, `attachments`, and `components` fields). These restrictions do not apply for messages that a bot or app sends, in DMs that it receives, or in messages in which it is mentioned. diff --git a/docs/change_log/2023-01-18-guild-audit-log-events.md b/docs/change_log/2023-01-18-guild-audit-log-events.md index 71ec81fffd..dfb606cb55 100644 --- a/docs/change_log/2023-01-18-guild-audit-log-events.md +++ b/docs/change_log/2023-01-18-guild-audit-log-events.md @@ -3,4 +3,4 @@ title: "Guild Audit Log Events" date: "2023-01-18" --- -At long last, a new [`GUILD_AUDIT_LOG_ENTRY_CREATE`](#DOCS_TOPICS_GATEWAY_EVENTS/guild-audit-log-entry-create) event has been added to the gateway, allowing your application to react to moderation actions in guilds. The `VIEW_AUDIT_LOG` permission is required in order to receive these events, and the [`GUILD_MODERATION` intent](#DOCS_TOPICS_GATEWAY/gateway-intents) needs to be set when connecting to the gateway. +At long last, a new [`GUILD_AUDIT_LOG_ENTRY_CREATE`](#DOCS_EVENTS_GATEWAY_EVENTS/guild-audit-log-entry-create) event has been added to the gateway, allowing your application to react to moderation actions in guilds. The `VIEW_AUDIT_LOG` permission is required in order to receive these events, and the [`GUILD_MODERATION` intent](#DOCS_EVENTS_GATEWAY/gateway-intents) needs to be set when connecting to the gateway. diff --git a/docs/change_log/2023-08-08-activity-state-for-bot-users.md b/docs/change_log/2023-08-08-activity-state-for-bot-users.md index 9971187d6a..e47dcaf148 100644 --- a/docs/change_log/2023-08-08-activity-state-for-bot-users.md +++ b/docs/change_log/2023-08-08-activity-state-for-bot-users.md @@ -3,4 +3,4 @@ title: "Activity State for Bot Users" date: "2023-08-08" --- -The `state` field in [activity objects](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object) can now be set when [updating presence](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence) for a bot user. The value of `state` will appear as a custom status for the bot user when an [activity's `type`](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-types) is set to `4`, or as additional data under an activity's name for other activity types. +The `state` field in [activity objects](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object) can now be set when [updating presence](#DOCS_EVENTS_GATEWAY_EVENTS/update-presence) for a bot user. The value of `state` will appear as a custom status for the bot user when an [activity's `type`](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-types) is set to `4`, or as additional data under an activity's name for other activity types. diff --git a/docs/change_log/2023-09-26-premium-app-subscriptions-available-in-the-us.md b/docs/change_log/2023-09-26-premium-app-subscriptions-available-in-the-us.md index 851e1817c2..d6d6c1983d 100644 --- a/docs/change_log/2023-09-26-premium-app-subscriptions-available-in-the-us.md +++ b/docs/change_log/2023-09-26-premium-app-subscriptions-available-in-the-us.md @@ -15,7 +15,7 @@ Starting today, eligible US-based developers can monetize their verified apps wi * [List Entitlements](#DOCS_RESOURCES_ENTITLEMENT/list-entitlements) `GET /applications//entitlements` * [Create Test Entitlement](#DOCS_RESOURCES_ENTITLEMENT/create-test-entitlement) `POST /applications//entitlements` * [Delete Test Entitlement](#DOCS_RESOURCES_ENTITLEMENT/delete-test-entitlement) `DELETE /applications//entitlements/` -* [Gateway Events](#DOCS_TOPICS_GATEWAY_EVENTS/entitlements) for working with entitlements: `ENTITLEMENT_CREATE`, `ENTITLEMENT_UPDATE`, `ENTITLEMENT_DELETE` +* [Gateway Events](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements) for working with entitlements: `ENTITLEMENT_CREATE`, `ENTITLEMENT_UPDATE`, `ENTITLEMENT_DELETE` * New [`PREMIUM_REQUIRED (10)` interaction response type](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-response-object-interaction-callback-type) is available to prompt users to upgrade * New `entitlements` field, which is an array of [entitlement](#DOCS_RESOURCES_ENTITLEMENT/) objects, available in interaction data payloads when [receiving and responding to interactions](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object-interaction-structure) diff --git a/docs/change_log/2024-07-25-supported-activity-types-for-set-activity.md b/docs/change_log/2024-07-25-supported-activity-types-for-set-activity.md index 31fd8744be..58413a6b93 100644 --- a/docs/change_log/2024-07-25-supported-activity-types-for-set-activity.md +++ b/docs/change_log/2024-07-25-supported-activity-types-for-set-activity.md @@ -3,7 +3,7 @@ title: "Supported Activity Types for SET_ACTIVITY" date: "2024-07-25" --- -The [`SET_ACTIVITY` RPC command](#DOCS_TOPICS_RPC/setactivity) has been updated to support 3 additional [activity types](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-types): Listening (`2`), Watching (`3`), and Competing (`5`). Previously, it only accepted Playing (`0`). +The [`SET_ACTIVITY` RPC command](#DOCS_TOPICS_RPC/setactivity) has been updated to support 3 additional [activity types](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-types): Listening (`2`), Watching (`3`), and Competing (`5`). Previously, it only accepted Playing (`0`). > warn > The [Game SDK](#DOCS_DEVELOPER_TOOLS_GAME_SDK/activities) has not been updated to support setting [`ActivityType`](#DOCS_DEVELOPER_TOOLS_GAME_SDK/activitytype-enum), and is still limited to read-only (to handle events that you receive from Discord). diff --git a/docs/change_log/2024-08-28-subscription-api-and-entitlement-migration.md b/docs/change_log/2024-08-28-subscription-api-and-entitlement-migration.md index e257cf4c86..dbba96d3bf 100644 --- a/docs/change_log/2024-08-28-subscription-api-and-entitlement-migration.md +++ b/docs/change_log/2024-08-28-subscription-api-and-entitlement-migration.md @@ -9,7 +9,7 @@ breaking: true > info > Updates to this Change Log entry was published on **October 7, 2024** to reflect up-to-date information. See the [new Change Log entry](#DOCS_CHANGE_LOG/updates-to-entitlement-migration-guide) for details on updates. -We are migrating our entitlement system to a new behavior where entitlements will not end until explicitly canceled, representing a breaking change for subscription management. We are introducing a [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and [Subscription Events](#DOCS_TOPICS_GATEWAY_EVENTS/subscriptions) to allow handling subscription-related events. +We are migrating our entitlement system to a new behavior where entitlements will not end until explicitly canceled, representing a breaking change for subscription management. We are introducing a [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and [Subscription Events](#DOCS_EVENTS_GATEWAY_EVENTS/subscriptions) to allow handling subscription-related events. > warn > This change will be rolled out to all existing applications that have entitlements for user and guild subscription SKUs, starting on October 1, 2024. @@ -40,7 +40,7 @@ As part of these changes, we've updated the documentation for Premium Apps. Starting on **October 1, 2024**, we will be migrating our existing entitlement system to a new behavior where **entitlements do not expire until explicitly canceled**. This migration guide outlines the changes and impacts of this migration on developers and guides how to manage these changes effectively. > warn -> With this update, entitlements for subscription SKUs will no longer emit events when a new subscription billing period begins. If you need to know when a subscription has been renewed, use the new [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and related [Subscription Gateway Events](#DOCS_TOPICS_GATEWAY_EVENTS/subscriptions). +> With this update, entitlements for subscription SKUs will no longer emit events when a new subscription billing period begins. If you need to know when a subscription has been renewed, use the new [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and related [Subscription Gateway Events](#DOCS_EVENTS_GATEWAY_EVENTS/subscriptions). ### Current System @@ -84,7 +84,7 @@ Post-migration, entitlements for Subscription SKUs purchased through Discord wil - Adjust your system not to expect type `APPLICATION_SUBSCRIPTION` (type `8`) for Discord-managed subscription entitlements. - **Post-Migration:** - Monitor for `ENTITLEMENT_CREATE`, `ENTITLEMENT_UPDATE`, `SUBSCRIPTION_CREATE`, and `SUBSCRIPTION_UPDATE` events. - - Update any references to an entitlement `ends_at` timestamps, which now indicate the ending of an entitlement. If you need to know when a subscription's period ends, use the [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and related [Subscription Gateway Events](#DOCS_TOPICS_GATEWAY_EVENTS/subscriptions). + - Update any references to an entitlement `ends_at` timestamps, which now indicate the ending of an entitlement. If you need to know when a subscription's period ends, use the [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) and related [Subscription Gateway Events](#DOCS_EVENTS_GATEWAY_EVENTS/subscriptions). - The Entitlement Migration begins on October 1, 2024 diff --git a/docs/change_log/2024-10-25-event-webhooks.md b/docs/change_log/2024-10-25-event-webhooks.md new file mode 100644 index 0000000000..e46078b507 --- /dev/null +++ b/docs/change_log/2024-10-25-event-webhooks.md @@ -0,0 +1,16 @@ +--- +title: "Webhook Events" +date: "2024-10-25" +topics: +- "Events" +- "User Apps" + +--- + +You can now subscribe to a limited number of HTTP-based outgoing [webhook events](#DOCS_EVENTS_WEBHOOK_EVENTS/event-types) after [configuring a webhook events URL](#DOCS_EVENTS_WEBHOOK_EVENTS/configuring-a-webhook-events-url). Currently, 3 events are available: `APPLICATION_AUTHORIZED`, `ENTITLEMENT_CREATE`, and `QUEST_USER_ENROLLMENT`. Read the [webhook events](#DOCS_EVENTS_WEBHOOK_EVENTS) documentation for details on subscribing and using webhook events. + +> info +> When developing [user-installable apps](#DOCS_RESOURCES_APPLICATION/user-context), [Application Authorized](#DOCS_EVENTS_WEBHOOK_EVENTS/application-authorized) (which is not available via [the Gateway](#DOCS_EVENTS_GATEWAY)) is useful to receive events when your app was installed to a user or server. + +> warn +> `ENTITLEMENT_CREATE` is the only monetization-related event available using webhook events, so you should still use the Gateway for [entitlement-related events](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements). Other monetization-related events will be supported via webhook events soon. \ No newline at end of file diff --git a/docs/developer_tools/Community_Resources.mdx b/docs/developer_tools/Community_Resources.mdx index 4773bfef16..644ac3e0b4 100644 --- a/docs/developer_tools/Community_Resources.mdx +++ b/docs/developer_tools/Community_Resources.mdx @@ -80,7 +80,7 @@ The public preview of the [Discord HTTP API specification](https://github.com/di ## Intent Calculators -[Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents) are pretty confusing at first. If you're not sure what to send in your [Identify payload](#DOCS_TOPICS_GATEWAY_EVENTS/identify), then these tools may be of help: +[Gateway Intents](#DOCS_EVENTS_GATEWAY/gateway-intents) are pretty confusing at first. If you're not sure what to send in your [Identify payload](#DOCS_EVENTS_GATEWAY_EVENTS/identify), then these tools may be of help: - [ziad87's Intent Calculator](https://ziad87.net/intents/) - [Larko's Intent Calculator](https://discord-intents-calculator.vercel.app/) diff --git a/docs/developer_tools/Embedded_App_SDK.mdx b/docs/developer_tools/Embedded_App_SDK.mdx index cc8cbe8243..1c9eaaced5 100644 --- a/docs/developer_tools/Embedded_App_SDK.mdx +++ b/docs/developer_tools/Embedded_App_SDK.mdx @@ -595,7 +595,7 @@ await discordSdk.commands.openShareMomentDialog({ ### setActivity() -Modifies how your Activity's Rich Presence data is displayed in the Discord client. The inner `activity` field is a partial [Activity object](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-structure). +Modifies how your Activity's Rich Presence data is displayed in the Discord client. The inner `activity` field is a partial [Activity object](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-structure). Read the guide on [Using Rich Presence with the Embedded App SDK](#DOCS_RICH_PRESENCE_USING_WITH_THE_EMBEDDED_APP_SDK) for more usage details. diff --git a/docs/developer_tools/Game_SDK.mdx b/docs/developer_tools/Game_SDK.mdx index e3a955818f..8580f05295 100644 --- a/docs/developer_tools/Game_SDK.mdx +++ b/docs/developer_tools/Game_SDK.mdx @@ -604,9 +604,9 @@ For more detailed information and documentation around the Rich Presence feature | name | type | description | |------------|--------|----------------------------------------------------------------------------------------------| -| LargeImage | string | see [Activity Asset Image](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-asset-image) | +| LargeImage | string | see [Activity Asset Image](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-asset-image) | | LargeText | string | hover text for the large image | -| SmallImage | string | see [Activity Asset Image](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-asset-image) | +| SmallImage | string | see [Activity Asset Image](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-asset-image) | | SmallText | string | hover text for the small image | #### ActivityParty Struct @@ -642,7 +642,7 @@ For more detailed information and documentation around the Rich Presence feature | Custom | 4 | | Competing | 5 | -For more details about the activity types, [see Gateway documentation](#DOCS_TOPICS_GATEWAY_EVENTS//activity-object-activity-types). +For more details about the activity types, [see Gateway documentation](#DOCS_EVENTS_GATEWAY_EVENTS//activity-object-activity-types). `ActivityType` is strictly for the purpose of handling events that you receive from Discord; though the SDK will not reject a payload with an `ActivityType` sent, it will be discarded and will not change anything in the client. diff --git a/docs/topics/Gateway.md b/docs/events/Gateway.mdx similarity index 83% rename from docs/topics/Gateway.md rename to docs/events/Gateway.mdx index fba9f90023..99954db051 100644 --- a/docs/topics/Gateway.md +++ b/docs/events/Gateway.mdx @@ -1,3 +1,7 @@ +--- +sidebar_label: Using Gateway +--- + # Gateway The Gateway API lets apps open secure WebSocket connections with Discord to receive events about actions that take place in a server/guild, like when a channel is updated or a role is created. There are a few cases where apps will *also* use Gateway connections to update or request resources, like when updating voice state. @@ -9,11 +13,11 @@ The Gateway is Discord's form of real-time communication used by clients (includ ## Gateway Events -Gateway events are [payloads](#DOCS_TOPICS_GATEWAY_EVENTS/payload-structure) sent over a [Gateway connection](#DOCS_TOPICS_GATEWAY/connections)—either from an app to Discord, or from Discord to an app. An app typically [*sends* events](#DOCS_TOPICS_GATEWAY/sending-events) when connecting and managing its connection to the Gateway, and [*receives* events](#DOCS_TOPICS_GATEWAY/receiving-events) when listening to actions taking place in a server. +Gateway events are [payloads](#DOCS_EVENTS_GATEWAY_EVENTS/payload-structure) sent over a [Gateway connection](#DOCS_EVENTS_GATEWAY/connections)—either from an app to Discord, or from Discord to an app. An app typically [*sends* events](#DOCS_EVENTS_GATEWAY/sending-events) when connecting and managing its connection to the Gateway, and [*receives* events](#DOCS_EVENTS_GATEWAY/receiving-events) when listening to actions taking place in a server. -All Gateway events are encapsulated in a [Gateway event payload](#DOCS_TOPICS_GATEWAY_EVENTS/payload-structure). +All Gateway events are encapsulated in a [Gateway event payload](#DOCS_EVENTS_GATEWAY_EVENTS/payload-structure). -A full list of Gateway events and their details are in the [Gateway events documentation](#DOCS_TOPICS_GATEWAY_EVENTS). +A full list of Gateway events and their details are in the [Gateway events documentation](#DOCS_EVENTS_GATEWAY_EVENTS). ###### Example Gateway Event @@ -26,31 +30,31 @@ A full list of Gateway events and their details are in the [Gateway events docum } ``` -Details about Gateway event payloads are in the [Gateway events documentation](#DOCS_TOPICS_GATEWAY_EVENTS/payload-structure). +Details about Gateway event payloads are in the [Gateway events documentation](#DOCS_EVENTS_GATEWAY_EVENTS/payload-structure). ### Sending Events -When sending a Gateway event (like when [performing an initial handshake](#DOCS_TOPICS_GATEWAY_EVENTS/identify) or [updating presence](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence)), your app must send an [event payload object](#DOCS_TOPICS_GATEWAY_EVENTS/payload-structure) with a valid opcode (`op`) and inner data object (`d`). +When sending a Gateway event (like when [performing an initial handshake](#DOCS_EVENTS_GATEWAY_EVENTS/identify) or [updating presence](#DOCS_EVENTS_GATEWAY_EVENTS/update-presence)), your app must send an [event payload object](#DOCS_EVENTS_GATEWAY_EVENTS/payload-structure) with a valid opcode (`op`) and inner data object (`d`). > info -> Specific rate limits are applied when sending events, which you can read about in the [Rate Limiting](#DOCS_TOPICS_GATEWAY/rate-limiting) section. +> Specific rate limits are applied when sending events, which you can read about in the [Rate Limiting](#DOCS_EVENTS_GATEWAY/rate-limiting) section. Event payloads sent over a Gateway connection: -1. Must be serialized in [plain-text JSON or binary ETF](#DOCS_TOPICS_GATEWAY/encoding-and-compression). +1. Must be serialized in [plain-text JSON or binary ETF](#DOCS_EVENTS_GATEWAY/encoding-and-compression). 2. Must not exceed 4096 bytes. If an event payload *does* exceed 4096 bytes, the connection will be closed with a [`4002` close event code](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes). -All events that your app can send via a connection are in [Gateway event documentation](#DOCS_TOPICS_GATEWAY_EVENTS/send-events). +All events that your app can send via a connection are in [Gateway event documentation](#DOCS_EVENTS_GATEWAY_EVENTS/send-events). ### Receiving Events -Receiving a Gateway event from Discord (like when [a reaction is added to a message](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-add)) is much more common (and slightly more complex) than sending them. +Receiving a Gateway event from Discord (like when [a reaction is added to a message](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-add)) is much more common (and slightly more complex) than sending them. -While some events are sent to your app automatically, most events require your app to define intents when [Identifying](#DOCS_TOPICS_GATEWAY/identifying). Intents are bitwise values that can be ORed (`|`) to indicate which events (or groups of events) you want Discord to send your app. A list of intents and their corresponding events are listed in the [intents section](#DOCS_TOPICS_GATEWAY/gateway-intents). +While some events are sent to your app automatically, most events require your app to define intents when [Identifying](#DOCS_EVENTS_GATEWAY/identifying). Intents are bitwise values that can be ORed (`|`) to indicate which events (or groups of events) you want Discord to send your app. A list of intents and their corresponding events are listed in the [intents section](#DOCS_EVENTS_GATEWAY/gateway-intents). -When receiving events, you can also configure *how* events will be sent to your app, like the [encoding and compression](#DOCS_TOPICS_GATEWAY/encoding-and-compression), or whether [sharding should be enabled](#DOCS_TOPICS_GATEWAY/sharding)). +When receiving events, you can also configure *how* events will be sent to your app, like the [encoding and compression](#DOCS_EVENTS_GATEWAY/encoding-and-compression), or whether [sharding should be enabled](#DOCS_EVENTS_GATEWAY/sharding)). -All events that your app can receive via a connection are in the [Gateway event documentation](#DOCS_TOPICS_GATEWAY_EVENTS/receive-events). +All events that your app can receive via a connection are in the [Gateway event documentation](#DOCS_EVENTS_GATEWAY_EVENTS/receive-events). #### Dispatch Events @@ -58,8 +62,8 @@ All events that your app can receive via a connection are in the [Gateway event When your app is parsing a Dispatch event: -- The `t` field can be used to determine which [Gateway event](#DOCS_TOPICS_GATEWAY_EVENTS/receive-events) the payload represents the data you can expect in the `d` field. -- The `s` field represents the sequence number of the event, which is the relative order in which it occurred. You need to cache the most recent non-null `s` value for heartbeats, and to pass when [Resuming](#DOCS_TOPICS_GATEWAY/resuming) a connection. +- The `t` field can be used to determine which [Gateway event](#DOCS_EVENTS_GATEWAY_EVENTS/receive-events) the payload represents the data you can expect in the `d` field. +- The `s` field represents the sequence number of the event, which is the relative order in which it occurred. You need to cache the most recent non-null `s` value for heartbeats, and to pass when [Resuming](#DOCS_EVENTS_GATEWAY/resuming) a connection. ## Connections @@ -74,23 +78,23 @@ At a high-level, Gateway connections consist of the following cycle: ![Flowchart with an overview of Gateway connection lifecycle](gateway-lifecycle.svg) -1. App establishes a connection with the Gateway after fetching and caching a WSS URL using the [Get Gateway](#DOCS_TOPICS_GATEWAY/get-gateway) or [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot) endpoint. -2. Discord sends the app a [Hello (opcode `10`)](#DOCS_TOPICS_GATEWAY/hello-event) event containing a heartbeat interval in milliseconds. **Read the section on [Connecting](#DOCS_TOPICS_GATEWAY/connecting)** -3. Start the Heartbeat interval. App must send a [Heartbeat (opcode `1`)](#DOCS_TOPICS_GATEWAY_EVENTS/heartbeat) event, then continue to send them every heartbeat interval until the connection is closed. **Read the section on [Sending Heartbeats](#DOCS_TOPICS_GATEWAY/sending-heartbeats)** - - Discord will respond to each Heartbeat event with a [Heartbeat ACK (opcode `11`)](#DOCS_TOPICS_GATEWAY/sending-heartbeats) event to confirm it was received. If an app doesn't receive a Heartbeat ACK, it should close the connection and reconnect. - - Discord may send the app a [Heartbeat (opcode `1`)](#DOCS_TOPICS_GATEWAY_EVENTS/heartbeat) event, in which case the app should send a Heartbeat event immediately. -4. App sends an [Identify (opcode `2`)](#DOCS_TOPICS_GATEWAY_EVENTS/identify) event to perform the initial handshake with the Gateway. **Read the section on [Identifying](#DOCS_TOPICS_GATEWAY/identifying)** -5. Discord sends the app a [Ready (opcode `0`)](#DOCS_TOPICS_GATEWAY_EVENTS/ready) event which indicates the handshake was successful and the connection is established. The Ready event contains a `resume_gateway_url` that the app should keep track of to determine the WebSocket URL an app should use to Resume. **Read the section on [the Ready event](#DOCS_TOPICS_GATEWAY/ready-event)** -6. The connection may be dropped for a variety of reasons at any time. Whether the app can [Resume](#DOCS_TOPICS_GATEWAY/resuming) the connection or whether it must re-identify is determined by a variety of factors like the [opcode](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-opcodes) and [close code](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes) that it receives. **Read the section on [Disconnecting](#DOCS_TOPICS_GATEWAY/disconnecting)** -7. If an app **can** resume/reconnect, it should open a new connection using `resume_gateway_url` with the same version and encoding, then send a [Resume (opcode `6`)](#DOCS_TOPICS_GATEWAY_EVENTS/resume) event. If an app **cannot** resume/reconnect, it should open a new connection using the cached URL from step #1, then repeat the whole Gateway cycle. *Yipee!* **Read the section on [Resuming](#DOCS_TOPICS_GATEWAY/resuming)** +1. App establishes a connection with the Gateway after fetching and caching a WSS URL using the [Get Gateway](#DOCS_EVENTS_GATEWAY/get-gateway) or [Get Gateway Bot](#DOCS_EVENTS_GATEWAY/get-gateway-bot) endpoint. +2. Discord sends the app a [Hello (opcode `10`)](#DOCS_EVENTS_GATEWAY/hello-event) event containing a heartbeat interval in milliseconds. **Read the section on [Connecting](#DOCS_EVENTS_GATEWAY/connecting)** +3. Start the Heartbeat interval. App must send a [Heartbeat (opcode `1`)](#DOCS_EVENTS_GATEWAY_EVENTS/heartbeat) event, then continue to send them every heartbeat interval until the connection is closed. **Read the section on [Sending Heartbeats](#DOCS_EVENTS_GATEWAY/sending-heartbeats)** + - Discord will respond to each Heartbeat event with a [Heartbeat ACK (opcode `11`)](#DOCS_EVENTS_GATEWAY/sending-heartbeats) event to confirm it was received. If an app doesn't receive a Heartbeat ACK, it should close the connection and reconnect. + - Discord may send the app a [Heartbeat (opcode `1`)](#DOCS_EVENTS_GATEWAY_EVENTS/heartbeat) event, in which case the app should send a Heartbeat event immediately. +4. App sends an [Identify (opcode `2`)](#DOCS_EVENTS_GATEWAY_EVENTS/identify) event to perform the initial handshake with the Gateway. **Read the section on [Identifying](#DOCS_EVENTS_GATEWAY/identifying)** +5. Discord sends the app a [Ready (opcode `0`)](#DOCS_EVENTS_GATEWAY_EVENTS/ready) event which indicates the handshake was successful and the connection is established. The Ready event contains a `resume_gateway_url` that the app should keep track of to determine the WebSocket URL an app should use to Resume. **Read the section on [the Ready event](#DOCS_EVENTS_GATEWAY/ready-event)** +6. The connection may be dropped for a variety of reasons at any time. Whether the app can [Resume](#DOCS_EVENTS_GATEWAY/resuming) the connection or whether it must re-identify is determined by a variety of factors like the [opcode](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-opcodes) and [close code](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes) that it receives. **Read the section on [Disconnecting](#DOCS_EVENTS_GATEWAY/disconnecting)** +7. If an app **can** resume/reconnect, it should open a new connection using `resume_gateway_url` with the same version and encoding, then send a [Resume (opcode `6`)](#DOCS_EVENTS_GATEWAY_EVENTS/resume) event. If an app **cannot** resume/reconnect, it should open a new connection using the cached URL from step #1, then repeat the whole Gateway cycle. *Yipee!* **Read the section on [Resuming](#DOCS_EVENTS_GATEWAY/resuming)** ### Connecting -Before your app can establish a connection to the Gateway, it should call the [Get Gateway](#DOCS_TOPICS_GATEWAY/get-gateway) or the [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot) endpoint. Either endpoint will return a payload with a `url` field whose value is the WSS URL you can use to open a WebSocket connection. In addition to the URL, [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot) contains additional information about the recommended number of shards and the session start limits for your app. +Before your app can establish a connection to the Gateway, it should call the [Get Gateway](#DOCS_EVENTS_GATEWAY/get-gateway) or the [Get Gateway Bot](#DOCS_EVENTS_GATEWAY/get-gateway-bot) endpoint. Either endpoint will return a payload with a `url` field whose value is the WSS URL you can use to open a WebSocket connection. In addition to the URL, [Get Gateway Bot](#DOCS_EVENTS_GATEWAY/get-gateway-bot) contains additional information about the recommended number of shards and the session start limits for your app. -When initially calling either [Get Gateway](#DOCS_TOPICS_GATEWAY/get-gateway) or [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot), you should cache the value of the `url` field and use that when re-connecting to the Gateway. +When initially calling either [Get Gateway](#DOCS_EVENTS_GATEWAY/get-gateway) or [Get Gateway Bot](#DOCS_EVENTS_GATEWAY/get-gateway-bot), you should cache the value of the `url` field and use that when re-connecting to the Gateway. -When connecting to the URL, it's a good idea to explicitly pass the API version and [encoding](#DOCS_TOPICS_GATEWAY/encoding-and-compression) as query parameters. You can also optionally include whether Discord should [compress](#DOCS_TOPICS_GATEWAY/encoding-and-compression) data that it sends your app. +When connecting to the URL, it's a good idea to explicitly pass the API version and [encoding](#DOCS_EVENTS_GATEWAY/encoding-and-compression) as query parameters. You can also optionally include whether Discord should [compress](#DOCS_EVENTS_GATEWAY/encoding-and-compression) data that it sends your app. > info > `wss://gateway.discord.gg/?v=10&encoding=json` is an example of a WSS URL an app may use to connect to the Gateway. @@ -103,14 +107,14 @@ When connecting to the URL, it's a good idea to explicitly pass the API version | Field | Type | Description | Accepted Values | |-----------|---------|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------| | v | integer | [API Version](#DOCS_REFERENCE/api-versioning) to use | [API version](#DOCS_REFERENCE/api-versioning-api-versions) | -| encoding | string | The [encoding](#DOCS_TOPICS_GATEWAY/encoding-and-compression) of received gateway packets | `json` or `etf` | -| compress? | string | The optional [transport compression](#DOCS_TOPICS_GATEWAY/transport-compression) of gateway packets | `zlib-stream` or `zstd-stream` | +| encoding | string | The [encoding](#DOCS_EVENTS_GATEWAY/encoding-and-compression) of received gateway packets | `json` or `etf` | +| compress? | string | The optional [transport compression](#DOCS_EVENTS_GATEWAY/transport-compression) of gateway packets | `zlib-stream` or `zstd-stream` | #### Hello Event -Once connected to the Gateway, your app will receive a [Hello (opcode `10`)](#DOCS_TOPICS_GATEWAY/hello-event) event that contains your connection's heartbeat interval (`heartbeat_interval`). +Once connected to the Gateway, your app will receive a [Hello (opcode `10`)](#DOCS_EVENTS_GATEWAY/hello-event) event that contains your connection's heartbeat interval (`heartbeat_interval`). -The heartbeat interval indicates a length of time in milliseconds that you should use to determine how often your app needs to send a Heartbeat event in order to maintain the active connection. Heartbeating is detailed in the [Sending Heartbeats](#DOCS_TOPICS_GATEWAY/sending-heartbeats) section. +The heartbeat interval indicates a length of time in milliseconds that you should use to determine how often your app needs to send a Heartbeat event in order to maintain the active connection. Heartbeating is detailed in the [Sending Heartbeats](#DOCS_EVENTS_GATEWAY/sending-heartbeats) section. ###### Example Hello Event @@ -129,18 +133,18 @@ Heartbeats are pings used to let Discord know that your app is still actively us #### Heartbeat Interval -When your app opens a Gateway connection, it will receive a [Hello (opcode `10`)](#DOCS_TOPICS_GATEWAY/hello-event) event which includes a `heartbeat_interval` field that has a value representing a length of time in milliseconds. +When your app opens a Gateway connection, it will receive a [Hello (opcode `10`)](#DOCS_EVENTS_GATEWAY/hello-event) event which includes a `heartbeat_interval` field that has a value representing a length of time in milliseconds. -Upon receiving the Hello event, your app should wait `heartbeat_interval * jitter` where `jitter` is any random value between 0 and 1, then send its first [Heartbeat (opcode `1`)](#DOCS_TOPICS_GATEWAY_EVENTS/heartbeat) event. From that point until the connection is closed, your app must continually send Discord a heartbeat every `heartbeat_interval` milliseconds. If your app fails to send a heartbeat event in time, your connection will be closed and you will be forced to [Resume](#DOCS_TOPICS_GATEWAY/resuming). +Upon receiving the Hello event, your app should wait `heartbeat_interval * jitter` where `jitter` is any random value between 0 and 1, then send its first [Heartbeat (opcode `1`)](#DOCS_EVENTS_GATEWAY_EVENTS/heartbeat) event. From that point until the connection is closed, your app must continually send Discord a heartbeat every `heartbeat_interval` milliseconds. If your app fails to send a heartbeat event in time, your connection will be closed and you will be forced to [Resume](#DOCS_EVENTS_GATEWAY/resuming). -When sending a heartbeat, your app will need to include the last sequence number your app received in the `d` field. The sequence number is sent to your app in the [event payload](#DOCS_TOPICS_GATEWAY_EVENTS/payload-structure) in the `s` field. If your app hasn't received any events yet, you can just pass `null` in the `d` field. +When sending a heartbeat, your app will need to include the last sequence number your app received in the `d` field. The sequence number is sent to your app in the [event payload](#DOCS_EVENTS_GATEWAY_EVENTS/payload-structure) in the `s` field. If your app hasn't received any events yet, you can just pass `null` in the `d` field. > info > In the first heartbeat, `jitter` is an offset value between 0 and `heartbeat_interval` that is meant to prevent too many clients (both desktop and apps) from reconnecting their sessions at the exact same time (which could cause an influx of traffic). You *can* send heartbeats before the `heartbeat_interval` elapses, but you should avoid doing so unless necessary. There is already tolerance in the `heartbeat_interval` that will cover network latency, so you don't need to account for it in your implementation. -When you send a Heartbeat event, Discord will respond with a [Heartbeat ACK (opcode `11`)](#DOCS_TOPICS_GATEWAY/heartbeat-interval-example-heartbeat-ack) event, which is an acknowledgement that the heartbeat was received: +When you send a Heartbeat event, Discord will respond with a [Heartbeat ACK (opcode `11`)](#DOCS_EVENTS_GATEWAY/heartbeat-interval-example-heartbeat-ack) event, which is an acknowledgement that the heartbeat was received: ###### Example Heartbeat ACK @@ -153,21 +157,21 @@ When you send a Heartbeat event, Discord will respond with a [Heartbeat ACK (opc > info > In the event of a service outage where you stay connected to the Gateway, you should continue to send heartbeats and receive heartbeat ACKs. The Gateway will eventually respond and issue a session once it's able to. -If a client does not receive a heartbeat ACK between its attempts at sending heartbeats, this may be due to a failed or "zombied" connection. The client should immediately terminate the connection with any close code besides `1000` or `1001`, then reconnect and attempt to [Resume](#DOCS_TOPICS_GATEWAY/resuming). +If a client does not receive a heartbeat ACK between its attempts at sending heartbeats, this may be due to a failed or "zombied" connection. The client should immediately terminate the connection with any close code besides `1000` or `1001`, then reconnect and attempt to [Resume](#DOCS_EVENTS_GATEWAY/resuming). #### Heartbeat Requests -In addition to the Heartbeat interval, Discord may request additional heartbeats from your app by sending a [Heartbeat (opcode `1`)](#DOCS_TOPICS_GATEWAY_EVENTS/heartbeat) event. Upon receiving the event, your app should immediately send back another Heartbeat event without waiting the remainder of the current interval. +In addition to the Heartbeat interval, Discord may request additional heartbeats from your app by sending a [Heartbeat (opcode `1`)](#DOCS_EVENTS_GATEWAY_EVENTS/heartbeat) event. Upon receiving the event, your app should immediately send back another Heartbeat event without waiting the remainder of the current interval. -Just like with the interval, Discord will respond with an [Heartbeat ACK (opcode `11`)](#DOCS_TOPICS_GATEWAY/heartbeat-interval-example-heartbeat-ack) event. +Just like with the interval, Discord will respond with an [Heartbeat ACK (opcode `11`)](#DOCS_EVENTS_GATEWAY/heartbeat-interval-example-heartbeat-ack) event. ### Identifying -After the connection is open and your app is sending heartbeats, you should send an [Identify (opcode `2`)](#DOCS_TOPICS_GATEWAY_EVENTS/identify) event. The Identify event is an initial handshake with the Gateway that's required before your app can begin sending or receiving most Gateway events. +After the connection is open and your app is sending heartbeats, you should send an [Identify (opcode `2`)](#DOCS_EVENTS_GATEWAY_EVENTS/identify) event. The Identify event is an initial handshake with the Gateway that's required before your app can begin sending or receiving most Gateway events. -Apps are limited by maximum concurrency (`max_concurrency` in the [session start limit object](#DOCS_TOPICS_GATEWAY/session-start-limit-object)) when identifying. If your app exceeds this limit, Discord will respond with a [Invalid Session (opcode `9`)](#DOCS_TOPICS_GATEWAY_EVENTS/invalid-session) event. +Apps are limited by maximum concurrency (`max_concurrency` in the [session start limit object](#DOCS_EVENTS_GATEWAY/session-start-limit-object)) when identifying. If your app exceeds this limit, Discord will respond with a [Invalid Session (opcode `9`)](#DOCS_EVENTS_GATEWAY_EVENTS/invalid-session) event. -After your app sends a valid Identify payload, Discord will respond with a [Ready](#DOCS_TOPICS_GATEWAY_EVENTS/ready) event which indicates that your app is in a successfully-connected state with the Gateway. The Ready event is sent as a standard [Dispatch (opcode `0`)](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-opcodes). +After your app sends a valid Identify payload, Discord will respond with a [Ready](#DOCS_EVENTS_GATEWAY_EVENTS/ready) event which indicates that your app is in a successfully-connected state with the Gateway. The Ready event is sent as a standard [Dispatch (opcode `0`)](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-opcodes). > warn > Clients are limited to 1000 `IDENTIFY` calls to the websocket in a 24-hour period. This limit is global and across all shards, but does not include `RESUME` calls. Upon hitting this limit, all active sessions for the app will be terminated, the bot token will be reset, and the owner will receive an email notification. It's up to the owner to update their application with the new token. @@ -176,7 +180,7 @@ After your app sends a valid Identify payload, Discord will respond with a [Read Below is a minimal `IDENTIFY` payload. `IDENTIFY` supports additional fields for other session properties like payload compression and an initial presence state. -See the [Identify Structure](#DOCS_TOPICS_GATEWAY_EVENTS/identify-identify-structure) for details about the event. +See the [Identify Structure](#DOCS_EVENTS_GATEWAY_EVENTS/identify-identify-structure) for details about the event. ```json { @@ -195,13 +199,13 @@ See the [Identify Structure](#DOCS_TOPICS_GATEWAY_EVENTS/identify-identify-struc #### Ready event -As mentioned above, the [Ready](#DOCS_TOPICS_GATEWAY_EVENTS/ready) event is sent to your app after it sends a valid Identify payload. The Ready event includes state, like the guilds your app is in, that it needs to start interacting with the rest of the platform. +As mentioned above, the [Ready](#DOCS_EVENTS_GATEWAY_EVENTS/ready) event is sent to your app after it sends a valid Identify payload. The Ready event includes state, like the guilds your app is in, that it needs to start interacting with the rest of the platform. -The Ready event also includes fields that you'll need to cache in order to eventually [Resume](#DOCS_TOPICS_GATEWAY/resuming) your connection after disconnects. Two fields in particular are important to call out: -- `resume_gateway_url` is a WebSocket URL that your app should use when it Resumes after a disconnect. The `resume_gateway_url` should be used instead of the URL [used when connecting](#DOCS_TOPICS_GATEWAY/connecting). +The Ready event also includes fields that you'll need to cache in order to eventually [Resume](#DOCS_EVENTS_GATEWAY/resuming) your connection after disconnects. Two fields in particular are important to call out: +- `resume_gateway_url` is a WebSocket URL that your app should use when it Resumes after a disconnect. The `resume_gateway_url` should be used instead of the URL [used when connecting](#DOCS_EVENTS_GATEWAY/connecting). - `session_id` is the ID for the Gateway session for the new connection. It's required to know which stream of events were associated with your disconnection connection. -Full details about the Ready event is in the [Gateway events documentation](#DOCS_TOPICS_GATEWAY_EVENTS). +Full details about the Ready event is in the [Gateway events documentation](#DOCS_EVENTS_GATEWAY_EVENTS). ### Disconnecting @@ -209,12 +213,12 @@ Gateway disconnects happen for a variety of reasons, and may be initiated by Dis #### Handling a Disconnect -Due to Discord's architecture, disconnects are a semi-regular event and should be expected and handled. When your app encounters a disconnect, it will typically be sent a [close code](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes) which can be used to determine whether you can reconnect and [Resume](#DOCS_TOPICS_GATEWAY/resuming) the session, or whether you have to start over and re-Identify. +Due to Discord's architecture, disconnects are a semi-regular event and should be expected and handled. When your app encounters a disconnect, it will typically be sent a [close code](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes) which can be used to determine whether you can reconnect and [Resume](#DOCS_EVENTS_GATEWAY/resuming) the session, or whether you have to start over and re-Identify. After you determine whether or not your app can reconnect, you will do one of the following: -- If you determine that your app *can* reconnect and resume the previous session, then you should reconnect using the `resume_gateway_url` and `session_id` from the [Ready](#DOCS_TOPICS_GATEWAY_EVENTS/ready) event. Details about when and how to resume can be found in the [Resuming](#DOCS_TOPICS_GATEWAY/resuming) section. -- If you *cannot* reconnect **or the reconnect fails**, you should open a new connection using the URL from the initial call to [Get Gateway](#DOCS_TOPICS_GATEWAY/get-gateway) or [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot). In the case you cannot reconnect, you'll have to re-identify after opening a new connection. +- If you determine that your app *can* reconnect and resume the previous session, then you should reconnect using the `resume_gateway_url` and `session_id` from the [Ready](#DOCS_EVENTS_GATEWAY_EVENTS/ready) event. Details about when and how to resume can be found in the [Resuming](#DOCS_EVENTS_GATEWAY/resuming) section. +- If you *cannot* reconnect **or the reconnect fails**, you should open a new connection using the URL from the initial call to [Get Gateway](#DOCS_EVENTS_GATEWAY/get-gateway) or [Get Gateway Bot](#DOCS_EVENTS_GATEWAY/get-gateway-bot). In the case you cannot reconnect, you'll have to re-identify after opening a new connection. A full list of the close codes can be found in the [Response Codes](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes) documentation. @@ -222,7 +226,7 @@ A full list of the close codes can be found in the [Response Codes](#DOCS_TOPICS When you close the connection to the gateway with close code `1000` or `1001`, your session will be invalidated and your bot will appear offline. -If you simply close the TCP connection or use a different close code, the session will remain active and timeout after a few minutes. This can be useful when you're [Resuming](#DOCS_TOPICS_GATEWAY/resuming) the previous session. +If you simply close the TCP connection or use a different close code, the session will remain active and timeout after a few minutes. This can be useful when you're [Resuming](#DOCS_EVENTS_GATEWAY/resuming) the previous session. ### Resuming @@ -230,27 +234,27 @@ When your app is disconnected, Discord has a process for reconnecting and resumi There are a handful of scenarios when your app should attempt to resume: -1. It receives a [Reconnect (opcode `7`)](#DOCS_TOPICS_GATEWAY_EVENTS/reconnect) event +1. It receives a [Reconnect (opcode `7`)](#DOCS_EVENTS_GATEWAY_EVENTS/reconnect) event 2. It's disconnected with a close code that indicates it can reconnect. A list of close codes is in the [Opcodes and Status Codes](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes) documentation. 3. It's disconnected but doesn't receive *any* close code. -4. It receives an [Invalid Session (opcode `9`)](#DOCS_TOPICS_GATEWAY_EVENTS/invalid-session) event with the `d` field set to `true`. This is an unlikely scenario, but it is possible. +4. It receives an [Invalid Session (opcode `9`)](#DOCS_EVENTS_GATEWAY_EVENTS/invalid-session) event with the `d` field set to `true`. This is an unlikely scenario, but it is possible. #### Preparing to Resume -Before your app can send a [Resume (opcode `6`)](#DOCS_TOPICS_GATEWAY_EVENTS/resume) event, it will need three values: the `session_id` and the `resume_gateway_url` from the [Ready](#DOCS_TOPICS_GATEWAY/ready-event) event, and the sequence number (`s`) from the last Dispatch (opcode `0`) event it received before the disconnect. +Before your app can send a [Resume (opcode `6`)](#DOCS_EVENTS_GATEWAY_EVENTS/resume) event, it will need three values: the `session_id` and the `resume_gateway_url` from the [Ready](#DOCS_EVENTS_GATEWAY/ready-event) event, and the sequence number (`s`) from the last Dispatch (opcode `0`) event it received before the disconnect. -After the connection is closed, your app should open a new connection using `resume_gateway_url` rather than the URL used to initially connect, with the same query parameters from the initial [Connection](#DOCS_TOPICS_GATEWAY/connecting). If your app doesn't use the `resume_gateway_url` when reconnecting, it will experience disconnects at a higher rate than normal. +After the connection is closed, your app should open a new connection using `resume_gateway_url` rather than the URL used to initially connect, with the same query parameters from the initial [Connection](#DOCS_EVENTS_GATEWAY/connecting). If your app doesn't use the `resume_gateway_url` when reconnecting, it will experience disconnects at a higher rate than normal. -Once the new connection is opened, your app should send a [Gateway Resume](#DOCS_TOPICS_GATEWAY_EVENTS/resume) event using the `session_id` and sequence number mentioned above. When sending the event, `session_id` will have the same field name, but the last sequence number will be passed as `seq` in the data object (`d`). +Once the new connection is opened, your app should send a [Gateway Resume](#DOCS_EVENTS_GATEWAY_EVENTS/resume) event using the `session_id` and sequence number mentioned above. When sending the event, `session_id` will have the same field name, but the last sequence number will be passed as `seq` in the data object (`d`). When Resuming, you do not need to send an Identify event after opening the connection. -If successful, the Gateway will send the missed events in order, finishing with a [Resumed](#DOCS_TOPICS_GATEWAY_EVENTS/resumed) event to signal event replay has finished and that all subsequent events will be new. +If successful, the Gateway will send the missed events in order, finishing with a [Resumed](#DOCS_EVENTS_GATEWAY_EVENTS/resumed) event to signal event replay has finished and that all subsequent events will be new. > info > When resuming with the `resume_gateway_url` you need to provide the same version and encoding as the initial connection. -It's possible your app won't reconnect in time to Resume, in which case it will receive an [Invalid Session (opcode `9`)](#DOCS_TOPICS_GATEWAY_EVENTS/invalid-session) event. If the `d` field is set to `false` (which is most of the time), your app should disconnect. After disconnect, your app should create a new connection with your cached URL from the [Get Gateway](#DOCS_TOPICS_GATEWAY/get-gateway) or the [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot) endpoint, then send an [Identify (opcode `2`)](#DOCS_TOPICS_GATEWAY_EVENTS/identify) event. +It's possible your app won't reconnect in time to Resume, in which case it will receive an [Invalid Session (opcode `9`)](#DOCS_EVENTS_GATEWAY_EVENTS/invalid-session) event. If the `d` field is set to `false` (which is most of the time), your app should disconnect. After disconnect, your app should create a new connection with your cached URL from the [Get Gateway](#DOCS_EVENTS_GATEWAY/get-gateway) or the [Get Gateway Bot](#DOCS_EVENTS_GATEWAY/get-gateway-bot) endpoint, then send an [Identify (opcode `2`)](#DOCS_EVENTS_GATEWAY_EVENTS/identify) event. ###### Example Gateway Resume Event @@ -269,7 +273,7 @@ It's possible your app won't reconnect in time to Resume, in which case it will Maintaining a stateful application can be difficult when it comes to the amount of data your app is expected to process over a Gateway connection, especially at scale. Gateway intents are a system to help you lower the computational burden. -Intents are bitwise values passed in the `intents` parameter when [Identifying](#DOCS_TOPICS_GATEWAY/identifying) which correlate to a set of related events. For example, the event sent when a guild is created (`GUILD_CREATE`) and when a channel is updated (`CHANNEL_UPDATE`) both require the same `GUILDS (1 << 0)` intent (as listed in the table below). If you do not specify an intent when identifying, you will not receive *any* of the Gateway events associated with that intent. +Intents are bitwise values passed in the `intents` parameter when [Identifying](#DOCS_EVENTS_GATEWAY/identifying) which correlate to a set of related events. For example, the event sent when a guild is created (`GUILD_CREATE`) and when a channel is updated (`CHANNEL_UPDATE`) both require the same `GUILDS (1 << 0)` intent (as listed in the table below). If you do not specify an intent when identifying, you will not receive *any* of the Gateway events associated with that intent. > info > Intents are optionally supported on the v6 gateway but required as of v8 @@ -277,7 +281,7 @@ Intents are bitwise values passed in the `intents` parameter when [Identifying]( Two types of intents exist: - **Standard intents** can be passed by default. You don't need any additional permissions or configurations. -- [**Privileged intents**](#DOCS_TOPICS_GATEWAY/privileged-intents) require you to toggle the intent for your app in your app's settings within the Developer Portal before passing said intent. For verified apps (required for apps in 100+ guilds), the intent must also be approved after the verification process to use the intent. More information about privileged intents can be found [in the section below](#DOCS_TOPICS_GATEWAY/privileged-intents). +- [**Privileged intents**](#DOCS_EVENTS_GATEWAY/privileged-intents) require you to toggle the intent for your app in your app's settings within the Developer Portal before passing said intent. For verified apps (required for apps in 100+ guilds), the intent must also be approved after the verification process to use the intent. More information about privileged intents can be found [in the section below](#DOCS_EVENTS_GATEWAY/privileged-intents). The connection with your app will be closed if it passes invalid intents ([`4013` close code](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes)), or a privileged intent that hasn't been configured or approved for your app ([`4014` close code](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-close-event-codes)). @@ -285,7 +289,7 @@ The connection with your app will be closed if it passes invalid intents ([`4013 Below is a list of all intents and the Gateway events associated with them. Any events *not* listed means it's not associated with an intent and will always be sent to your app. -All events, including those that aren't associated with an intent, are in the [Gateway events](#DOCS_TOPICS_GATEWAY_EVENTS) documentation. +All events, including those that aren't associated with an intent, are in the [Gateway events](#DOCS_EVENTS_GATEWAY_EVENTS) documentation. ``` GUILDS (1 << 0) @@ -404,19 +408,19 @@ DIRECT_MESSAGE_POLLS (1 << 25) - MESSAGE_POLL_VOTE_REMOVE ``` -\* [Thread Members Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-members-update) contains different data depending on which intents are used. +\* [Thread Members Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-members-update) contains different data depending on which intents are used. \*\* Events under the `GUILD_PRESENCES` and `GUILD_MEMBERS` intents are turned **off by default on all API versions**. If you are using **API v6**, you will receive those events if you are authorized to receive them and have enabled the intents in the Developer Portal. You do not need to use intents on API v6 to receive these events; you just need to enable the flags. If you are using **API v8** or above, intents are mandatory and must be specified when identifying. -\*\*\* `MESSAGE_CONTENT` does not represent individual events, but rather affects what data is present for events that could contain message content fields. More information is in the [message content intent](#DOCS_TOPICS_GATEWAY/message-content-intent) section. +\*\*\* `MESSAGE_CONTENT` does not represent individual events, but rather affects what data is present for events that could contain message content fields. More information is in the [message content intent](#DOCS_EVENTS_GATEWAY/message-content-intent) section. ### Caveats -[Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update) is sent for current-user updates regardless of whether the `GUILD_MEMBERS` intent is set. +[Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update) is sent for current-user updates regardless of whether the `GUILD_MEMBERS` intent is set. -[Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) and [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) are uniquely affected by intents. See these sections for more information. +[Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) and [Request Guild Members](#DOCS_EVENTS_GATEWAY_EVENTS/request-guild-members) are uniquely affected by intents. See these sections for more information. -[Thread Members Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-members-update) by default only includes if the current user was added to or removed from a thread. To receive these updates for other users, request the `GUILD_MEMBERS` [Gateway Intent](#DOCS_TOPICS_GATEWAY/gateway-intents). +[Thread Members Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-members-update) by default only includes if the current user was added to or removed from a thread. To receive these updates for other users, request the `GUILD_MEMBERS` [Gateway Intent](#DOCS_EVENTS_GATEWAY/gateway-intents). ### Privileged Intents @@ -424,7 +428,7 @@ Some intents are defined as "privileged" due to the sensitive nature of the data - `GUILD_PRESENCES` - `GUILD_MEMBERS` -- [`MESSAGE_CONTENT`](#DOCS_TOPICS_GATEWAY/message-content-intent) +- [`MESSAGE_CONTENT`](#DOCS_EVENTS_GATEWAY/message-content-intent) Apps that qualify for verification **must** be approved for the privileged intent(s) before they can use them. After your app is verified, you can request privileged intents within the app's settings within the Developer Portal. @@ -476,32 +480,32 @@ Apps **without** the intent will receive empty values in fields that contain use > info > This section refers to Gateway rate limits, not [HTTP API rate limits](#DOCS_TOPICS_RATE_LIMITS) -Apps can send 120 [gateway events](#DOCS_TOPICS_GATEWAY_EVENTS) per [connection](#DOCS_TOPICS_GATEWAY/connections) every 60 seconds, meaning an average of 2 commands per second. Apps that surpass the limit are immediately disconnected from the Gateway. Similar to other rate limits, repeat offenders will have their API access revoked. +Apps can send 120 [gateway events](#DOCS_EVENTS_GATEWAY_EVENTS) per [connection](#DOCS_EVENTS_GATEWAY/connections) every 60 seconds, meaning an average of 2 commands per second. Apps that surpass the limit are immediately disconnected from the Gateway. Similar to other rate limits, repeat offenders will have their API access revoked. -Apps also have a limit for [concurrent](#DOCS_TOPICS_GATEWAY/session-start-limit-object) [Identify](#DOCS_TOPICS_GATEWAY/identifying) requests allowed per 5 seconds. If you hit this limit, the Gateway will respond with an [Invalid Session (opcode `9`)](#DOCS_TOPICS_GATEWAY_EVENTS/invalid-session). +Apps also have a limit for [concurrent](#DOCS_EVENTS_GATEWAY/session-start-limit-object) [Identify](#DOCS_EVENTS_GATEWAY/identifying) requests allowed per 5 seconds. If you hit this limit, the Gateway will respond with an [Invalid Session (opcode `9`)](#DOCS_EVENTS_GATEWAY_EVENTS/invalid-session). ## Encoding and Compression -When [establishing a connection](#DOCS_TOPICS_GATEWAY/connecting) to the Gateway, apps can use the `encoding` parameter to choose whether to communicate with Discord using a plain-text JSON or binary [ETF](https://erlang.org/doc/apps/erts/erl_ext_dist.html) encoding. You can pick whichever encoding type you're more comfortable with, but both have their own quirks. If you aren't sure which encoding to use, JSON is generally recommended. +When [establishing a connection](#DOCS_EVENTS_GATEWAY/connecting) to the Gateway, apps can use the `encoding` parameter to choose whether to communicate with Discord using a plain-text JSON or binary [ETF](https://erlang.org/doc/apps/erts/erl_ext_dist.html) encoding. You can pick whichever encoding type you're more comfortable with, but both have their own quirks. If you aren't sure which encoding to use, JSON is generally recommended. -Apps can also optionally enable compression to receive zlib-compressed or zstd-compressed packets. [Payload compression](#DOCS_TOPICS_GATEWAY/payload-compression) can only be enabled when using a JSON encoding, but [transport compression](#DOCS_TOPICS_GATEWAY/transport-compression) can be used regardless of encoding type. +Apps can also optionally enable compression to receive zlib-compressed or zstd-compressed packets. [Payload compression](#DOCS_EVENTS_GATEWAY/payload-compression) can only be enabled when using a JSON encoding, but [transport compression](#DOCS_EVENTS_GATEWAY/transport-compression) can be used regardless of encoding type. ### Using JSON Encoding -When using the plain-text JSON encoding, apps have the option to enable [payload compression](#DOCS_TOPICS_GATEWAY/payload-compression). +When using the plain-text JSON encoding, apps have the option to enable [payload compression](#DOCS_EVENTS_GATEWAY/payload-compression). #### Payload Compression > warn -> If an app is using payload compression, it cannot use [transport compression](#DOCS_TOPICS_GATEWAY/transport-compression). +> If an app is using payload compression, it cannot use [transport compression](#DOCS_EVENTS_GATEWAY/transport-compression). Payload compression enables optional per-packet compression for *some* events when Discord is sending events over the connection. -Payload compression uses the zlib format (see [RFC1950 2.2](https://tools.ietf.org/html/rfc1950#section-2.2)) when sending payloads. To enable payload compression, your app can set `compress` to `true` when sending an [Identify (opcode `2`)](#DOCS_TOPICS_GATEWAY_EVENTS/identify) event. Note that even when payload compression is enabled, not all payloads will be compressed. +Payload compression uses the zlib format (see [RFC1950 2.2](https://tools.ietf.org/html/rfc1950#section-2.2)) when sending payloads. To enable payload compression, your app can set `compress` to `true` when sending an [Identify (opcode `2`)](#DOCS_EVENTS_GATEWAY_EVENTS/identify) event. Note that even when payload compression is enabled, not all payloads will be compressed. When payload compression is enabled, your app (or library) _must_ detect and decompress these payloads to plain-text JSON before attempting to parse them. If you are using payload compression, the gateway does not implement a shared compression context between events sent. -Payload compression will be disabled if you use [transport compression](#DOCS_TOPICS_GATEWAY/transport-compression). +Payload compression will be disabled if you use [transport compression](#DOCS_EVENTS_GATEWAY/transport-compression). ### Using ETF Encoding @@ -560,18 +564,18 @@ When processing data, each websocket message corresponds to a single gateway mes ## Tracking State -Most of a client's state is provided during the initial [Ready](#DOCS_TOPICS_GATEWAY/ready-event) event and in the [Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) events that follow. +Most of a client's state is provided during the initial [Ready](#DOCS_EVENTS_GATEWAY/ready-event) event and in the [Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) events that follow. As resources continue to be created, updated, and deleted, Gateway events are sent to notify the app of these changes and to provide associated data. To avoid excessive API calls, apps should cache as many relevant resource states as possible, and update them as new events are received. > info -> For larger apps, client state can grow to be very large. Therefore, we recommend only storing data in memory that are *needed* for the app to operate. In some cases, there isn't a need to cache member information (like roles or permissions) since some events like [MESSAGE_CREATE](#DOCS_TOPICS_GATEWAY_EVENTS/message-create) have the full member object included. +> For larger apps, client state can grow to be very large. Therefore, we recommend only storing data in memory that are *needed* for the app to operate. In some cases, there isn't a need to cache member information (like roles or permissions) since some events like [MESSAGE_CREATE](#DOCS_EVENTS_GATEWAY_EVENTS/message-create) have the full member object included. -An example of state tracking can be considered in the case of an app that wants to track member status: when initially connecting to the Gateway, the app will receive information about the online status of guild members (whether they're online, idle, dnd, or offline). To keep the state updated, the app will track and parse [Presence Update](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update) events as they're received, then update the cached member objects accordingly. +An example of state tracking can be considered in the case of an app that wants to track member status: when initially connecting to the Gateway, the app will receive information about the online status of guild members (whether they're online, idle, dnd, or offline). To keep the state updated, the app will track and parse [Presence Update](#DOCS_EVENTS_GATEWAY_EVENTS/presence-update) events as they're received, then update the cached member objects accordingly. ## Guild Availability -When connecting to the gateway as a bot user, guilds that the bot is a part of will start out as unavailable. Don't fret! The gateway will automatically attempt to reconnect on your behalf. As guilds become available to you, you will receive [Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) events. +When connecting to the gateway as a bot user, guilds that the bot is a part of will start out as unavailable. Don't fret! The gateway will automatically attempt to reconnect on your behalf. As guilds become available to you, you will receive [Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) events. ## Sharding @@ -580,10 +584,10 @@ As apps grow and are added to an increasing number of guilds, some developers ma > warn > Each shard can only support a maximum of 2500 guilds, and apps that are in 2500+ guilds *must* enable sharding. -To enable sharding on a connection, the app should send the `shard` array in the [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) payload. The first item in this array should be the zero-based integer value of the current shard, while the second represents the total number of shards. DMs will only be sent to shard 0. +To enable sharding on a connection, the app should send the `shard` array in the [Identify](#DOCS_EVENTS_GATEWAY_EVENTS/identify) payload. The first item in this array should be the zero-based integer value of the current shard, while the second represents the total number of shards. DMs will only be sent to shard 0. > info -> The [Get Gateway Bot](#DOCS_TOPICS_GATEWAY/get-gateway-bot) endpoint provides a recommended number of shards for your app in the `shards` field +> The [Get Gateway Bot](#DOCS_EVENTS_GATEWAY/get-gateway-bot) endpoint provides a recommended number of shards for your app in the `shards` field To calculate which events will be sent to which shard, the following formula can be used: @@ -599,7 +603,7 @@ Note that `num_shards` does not relate to (or limit) the total number of potenti ###### Max Concurrency -If you have multiple shards, you may start them concurrently based on the [`max_concurrency`](#DOCS_TOPICS_GATEWAY/session-start-limit-object) value returned to you on session start. Which shards you can start concurrently are assigned based on a key for each shard. The rate limit key for a given shard can be computed with +If you have multiple shards, you may start them concurrently based on the [`max_concurrency`](#DOCS_EVENTS_GATEWAY/session-start-limit-object) value returned to you on session start. Which shards you can start concurrently are assigned based on a key for each shard. The rate limit key for a given shard can be computed with ``` rate_limit_key = shard_id % max_concurrency @@ -671,16 +675,16 @@ If your bot is in more than 150,000 guilds, there are some additional considerat The number of shards you run must be a multiple of the shard number provided when reaching out to you. If you attempt to start your bot with an invalid number of shards, your Gateway connection will close with a `4010` Invalid Shard close code. -The [Get Gateway Bot endpoint](#DOCS_TOPICS_GATEWAY/get-gateway-bot) will always return the correct amount of shards, so if you're already using this endpoint to determine your number of shards, you shouldn't require any changes. +The [Get Gateway Bot endpoint](#DOCS_EVENTS_GATEWAY/get-gateway-bot) will always return the correct amount of shards, so if you're already using this endpoint to determine your number of shards, you shouldn't require any changes. -The session start limit for these bots will also be increased from 1000 to `max(2000, (guild_count / 1000) * 5)` per day. You also receive an increased `max_concurrency`, the number of [shards you can concurrently start](#DOCS_TOPICS_GATEWAY/session-start-limit-object). +The session start limit for these bots will also be increased from 1000 to `max(2000, (guild_count / 1000) * 5)` per day. You also receive an increased `max_concurrency`, the number of [shards you can concurrently start](#DOCS_EVENTS_GATEWAY/session-start-limit-object). ## Get Gateway % GET /gateway > info > This endpoint does not require authentication. -Returns an object with a valid WSS URL which the app can use when [Connecting](#DOCS_TOPICS_GATEWAY/connecting) to the Gateway. Apps should cache this value and only call this endpoint to retrieve a new URL when they are unable to properly establish a connection using the cached one. +Returns an object with a valid WSS URL which the app can use when [Connecting](#DOCS_EVENTS_GATEWAY/connecting) to the Gateway. Apps should cache this value and only call this endpoint to retrieve a new URL when they are unable to properly establish a connection using the cached one. ###### Example Response @@ -695,15 +699,15 @@ Returns an object with a valid WSS URL which the app can use when [Connecting](# > warn > This endpoint requires authentication using a valid bot token. -Returns an object based on the information in [Get Gateway](#DOCS_TOPICS_GATEWAY/get-gateway), plus additional metadata that can help during the operation of large or [sharded](#DOCS_TOPICS_GATEWAY/sharding) bots. Unlike the [Get Gateway](#DOCS_TOPICS_GATEWAY/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 bot joins/leaves guilds. +Returns an object based on the information in [Get Gateway](#DOCS_EVENTS_GATEWAY/get-gateway), plus additional metadata that can help during the operation of large or [sharded](#DOCS_EVENTS_GATEWAY/sharding) bots. Unlike the [Get Gateway](#DOCS_EVENTS_GATEWAY/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 bot joins/leaves guilds. ###### JSON Response | Field | Type | Description | |---------------------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | url | string | WSS URL that can be used for connecting to the Gateway | -| shards | integer | Recommended number of [shards](#DOCS_TOPICS_GATEWAY/sharding) to use when connecting | -| session_start_limit | [session_start_limit](#DOCS_TOPICS_GATEWAY/session-start-limit-object) object | Information on the current session start limit | +| shards | integer | Recommended number of [shards](#DOCS_EVENTS_GATEWAY/sharding) to use when connecting | +| session_start_limit | [session_start_limit](#DOCS_EVENTS_GATEWAY/session-start-limit-object) object | Information on the current session start limit | ###### Example Response diff --git a/docs/topics/Gateway_Events.md b/docs/events/Gateway_Events.mdx similarity index 90% rename from docs/topics/Gateway_Events.md rename to docs/events/Gateway_Events.mdx index 6f13cb36af..b693ee34eb 100644 --- a/docs/topics/Gateway_Events.md +++ b/docs/events/Gateway_Events.mdx @@ -1,3 +1,7 @@ +--- +sidebar_label: Gateway Events +--- + # 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: @@ -5,16 +9,16 @@ Gateway connections are WebSockets, meaning they're bidirectional and either sid - **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](#DOCS_TOPICS_GATEWAY_EVENTS/payload-structure). +All Gateway events are encapsulated in a [Gateway event payload](#DOCS_EVENTS_GATEWAY_EVENTS/payload-structure). -For more information about interacting with the Gateway, you can reference the [Gateway documentation](#DOCS_TOPICS_GATEWAY). +For more information about interacting with the Gateway, you can reference the [Gateway documentation](#DOCS_EVENTS_GATEWAY). > warn > 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](#DOCS_TOPICS_GATEWAY_EVENTS/channel-create) would be `CHANNEL_CREATE` and [Voice State Update](#DOCS_TOPICS_GATEWAY_EVENTS/voice-state-update) would be `VOICE_STATE_UPDATE`. +In practice, event names are UPPER-CASED with under_scores joining each word in the name. For instance, [Channel Create](#DOCS_EVENTS_GATEWAY_EVENTS/channel-create) would be `CHANNEL_CREATE` and [Voice State Update](#DOCS_EVENTS_GATEWAY_EVENTS/voice-state-update) would be `VOICE_STATE_UPDATE`. For readability, event names in the following documentation are typically left in Title Case. @@ -26,7 +30,7 @@ Gateway event payloads have a common structure, but the contents of the associat |-------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | op | integer | [Gateway opcode](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-opcodes), which indicates the payload type | | d | ?mixed (any JSON value) | Event data | -| s | ?integer \* | Sequence number of event used for [resuming sessions](#DOCS_TOPICS_GATEWAY/resuming) and [heartbeating](#DOCS_TOPICS_GATEWAY/sending-heartbeats) | +| s | ?integer \* | Sequence number of event used for [resuming sessions](#DOCS_EVENTS_GATEWAY/resuming) and [heartbeating](#DOCS_EVENTS_GATEWAY/sending-heartbeats) | | t | ?string \* | Event name | \* `s` and `t` are `null` when `op` is not `0` ([Gateway Dispatch opcode](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-opcodes)). @@ -44,38 +48,38 @@ Gateway event payloads have a common structure, but the contents of the associat ## Send Events -Send events are Gateway events encapsulated in an [event payload](#DOCS_TOPICS_GATEWAY_EVENTS/payload-structure), and are sent by an app to Discord through a Gateway connection. +Send events are Gateway events encapsulated in an [event payload](#DOCS_EVENTS_GATEWAY_EVENTS/payload-structure), and are sent by an app to Discord through a Gateway connection. > info > Previously, Gateway send events were labeled as commands | Name | Description | |------------------------------------------------------------------------------------|-----------------------------------------------------------| -| [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) | Triggers the initial handshake with the gateway | -| [Resume](#DOCS_TOPICS_GATEWAY_EVENTS/resume) | Resumes a dropped gateway connection | -| [Heartbeat](#DOCS_TOPICS_GATEWAY_EVENTS/heartbeat) | Maintains an active gateway connection | -| [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) | Requests members for a guild | -| [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds) | Requests soundboard sounds in a set of guilds | -| [Update Voice State](#DOCS_TOPICS_GATEWAY_EVENTS/update-voice-state) | Joins, moves, or disconnects the app from a voice channel | -| [Update Presence](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence) | Updates an app's presence | +| [Identify](#DOCS_EVENTS_GATEWAY_EVENTS/identify) | Triggers the initial handshake with the gateway | +| [Resume](#DOCS_EVENTS_GATEWAY_EVENTS/resume) | Resumes a dropped gateway connection | +| [Heartbeat](#DOCS_EVENTS_GATEWAY_EVENTS/heartbeat) | Maintains an active gateway connection | +| [Request Guild Members](#DOCS_EVENTS_GATEWAY_EVENTS/request-guild-members) | Requests members for a guild | +| [Request Soundboard Sounds](#DOCS_EVENTS_GATEWAY_EVENTS/request-soundboard-sounds) | Requests soundboard sounds in a set of guilds | +| [Update Voice State](#DOCS_EVENTS_GATEWAY_EVENTS/update-voice-state) | Joins, moves, or disconnects the app from a voice channel | +| [Update Presence](#DOCS_EVENTS_GATEWAY_EVENTS/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](#DOCS_TOPICS_GATEWAY/identifying). +Details about identifying is in the [Gateway documentation](#DOCS_EVENTS_GATEWAY/identifying). ###### Identify Structure | Field | Type | Description | Default | |------------------|-----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|---------| | token | string | Authentication token | - | -| properties | object | [Connection properties](#DOCS_TOPICS_GATEWAY_EVENTS/identify-identify-connection-properties) | - | +| properties | object | [Connection properties](#DOCS_EVENTS_GATEWAY_EVENTS/identify-identify-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](#DOCS_TOPICS_GATEWAY/sharding) | - | -| presence? | [update presence](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence) object | Presence structure for initial presence information | - | -| intents | integer | [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents) you wish to receive | - | +| shard? | array of two integers (shard_id, num_shards) | Used for [Guild Sharding](#DOCS_EVENTS_GATEWAY/sharding) | - | +| presence? | [update presence](#DOCS_EVENTS_GATEWAY_EVENTS/update-presence) object | Presence structure for initial presence information | - | +| intents | integer | [Gateway Intents](#DOCS_EVENTS_GATEWAY/gateway-intents) you wish to receive | - | ###### Identify Connection Properties @@ -123,7 +127,7 @@ Details about identifying is in the [Gateway documentation](#DOCS_TOPICS_GATEWAY Used to replay missed events when a disconnected client resumes. -Details about resuming are in the [Gateway documentation](#DOCS_TOPICS_GATEWAY/resuming). +Details about resuming are in the [Gateway documentation](#DOCS_EVENTS_GATEWAY/resuming). ###### Resume Structure @@ -148,9 +152,9 @@ Details about resuming are in the [Gateway documentation](#DOCS_TOPICS_GATEWAY/r #### Heartbeat -Used to maintain an active gateway connection. Must be sent every `heartbeat_interval` milliseconds after the [Opcode 10 Hello](#DOCS_TOPICS_GATEWAY_EVENTS/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`. +Used to maintain an active gateway connection. Must be sent every `heartbeat_interval` milliseconds after the [Opcode 10 Hello](#DOCS_EVENTS_GATEWAY_EVENTS/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](#DOCS_TOPICS_GATEWAY/sending-heartbeats). +Details about heartbeats are in the [Gateway documentation](#DOCS_EVENTS_GATEWAY/sending-heartbeats). ###### Example Heartbeat @@ -163,7 +167,7 @@ Details about heartbeats are in the [Gateway documentation](#DOCS_TOPICS_GATEWAY #### 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](#DOCS_TOPICS_GATEWAY/gateway-intents), 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](#DOCS_TOPICS_GATEWAY_EVENTS/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](#DOCS_TOPICS_GATEWAY_EVENTS/guild-members-chunk) events in response with up to 1000 members per chunk until all members that match the request have been sent. +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](#DOCS_EVENTS_GATEWAY/gateway-intents), 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](#DOCS_EVENTS_GATEWAY_EVENTS/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](#DOCS_EVENTS_GATEWAY_EVENTS/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: @@ -182,7 +186,7 @@ Due to our privacy and infrastructural concerns with this feature, there are som | 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](#DOCS_TOPICS_GATEWAY_EVENTS/guild-members-chunk) response | false | +| nonce? | string | nonce to identify the [Guild Members Chunk](#DOCS_EVENTS_GATEWAY_EVENTS/guild-members-chunk) response | false | > info > 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. @@ -202,7 +206,7 @@ Due to our privacy and infrastructural concerns with this feature, there are som #### Request Soundboard Sounds -Used to request soundboard sounds for a list of guilds. The server will send [Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/soundboard-sounds) events for each guild in response. +Used to request soundboard sounds for a list of guilds. The server will send [Soundboard Sounds](#DOCS_EVENTS_GATEWAY_EVENTS/soundboard-sounds) events for each guild in response. ###### Request Soundboard Sounds Structure @@ -257,8 +261,8 @@ Sent by the client to indicate a presence or status update. | 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](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object) objects | User's activities | -| status | string | User's new [status](#DOCS_TOPICS_GATEWAY_EVENTS/update-presence-status-types) | +| activities | array of [activity](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object) objects | User's activities | +| status | string | User's new [status](#DOCS_EVENTS_GATEWAY_EVENTS/update-presence-status-types) | | afk | boolean | Whether or not the client is afk | ###### Status Types @@ -290,88 +294,88 @@ Sent by the client to indicate a presence or status update. ## Receive Events -Receive events are Gateway events encapsulated in an [event payload](#DOCS_TOPICS_GATEWAY_EVENTS/payload-structure), 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. +Receive events are Gateway events encapsulated in an [event payload](#DOCS_EVENTS_GATEWAY_EVENTS/payload-structure), 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](#DOCS_TOPICS_GATEWAY_EVENTS/hello) | Defines the heartbeat interval | -| [Ready](#DOCS_TOPICS_GATEWAY_EVENTS/ready) | Contains the initial state information | -| [Resumed](#DOCS_TOPICS_GATEWAY_EVENTS/resumed) | Response to [Resume](#DOCS_TOPICS_GATEWAY_EVENTS/resume) | -| [Reconnect](#DOCS_TOPICS_GATEWAY_EVENTS/reconnect) | Server is going away, client should reconnect to gateway and resume | -| [Invalid Session](#DOCS_TOPICS_GATEWAY_EVENTS/invalid-session) | Failure response to [Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) or [Resume](#DOCS_TOPICS_GATEWAY_EVENTS/resume) or invalid active session | -| [Application Command Permissions Update](#DOCS_TOPICS_GATEWAY_EVENTS/application-command-permissions-update) | Application command permission was updated | -| [Auto Moderation Rule Create](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-create) | Auto Moderation rule was created | -| [Auto Moderation Rule Update](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-update) | Auto Moderation rule was updated | -| [Auto Moderation Rule Delete](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-delete) | Auto Moderation rule was deleted | -| [Auto Moderation Action Execution](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-action-execution) | Auto Moderation rule was triggered and an action was executed (e.g. a message was blocked) | -| [Channel Create](#DOCS_TOPICS_GATEWAY_EVENTS/channel-create) | New guild channel created | -| [Channel Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-update) | Channel was updated | -| [Channel Delete](#DOCS_TOPICS_GATEWAY_EVENTS/channel-delete) | Channel was deleted | -| [Channel Pins Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-pins-update) | Message was pinned or unpinned | -| [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) | Thread created, also sent when being added to a private thread | -| [Thread Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-update) | Thread was updated | -| [Thread Delete](#DOCS_TOPICS_GATEWAY_EVENTS/thread-delete) | Thread was deleted | -| [Thread List Sync](#DOCS_TOPICS_GATEWAY_EVENTS/thread-list-sync) | Sent when gaining access to a channel, contains all active threads in that channel | -| [Thread Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-member-update) | [Thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) for the current user was updated | -| [Thread Members Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-members-update) | Some user(s) were added to or removed from a thread | -| [Entitlement Create](#DOCS_TOPICS_GATEWAY_EVENTS/entitlement-create) | Entitlement was created | -| [Entitlement Update](#DOCS_TOPICS_GATEWAY_EVENTS/entitlement-update) | Entitlement was updated or renewed | -| [Entitlement Delete](#DOCS_TOPICS_GATEWAY_EVENTS/entitlement-delete) | Entitlement was deleted | -| [Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) | Lazy-load for unavailable guild, guild became available, or user joined a new guild | -| [Guild Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-update) | Guild was updated | -| [Guild Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-delete) | Guild became unavailable, or user left/was removed from a guild | -| [Guild Audit Log Entry Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-audit-log-entry-create) | A guild audit log entry was created | -| [Guild Ban Add](#DOCS_TOPICS_GATEWAY_EVENTS/guild-ban-add) | User was banned from a guild | -| [Guild Ban Remove](#DOCS_TOPICS_GATEWAY_EVENTS/guild-ban-remove) | User was unbanned from a guild | -| [Guild Emojis Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-emojis-update) | Guild emojis were updated | -| [Guild Stickers Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-stickers-update) | Guild stickers were updated | -| [Guild Integrations Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-integrations-update) | Guild integration was updated | -| [Guild Member Add](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-add) | New user joined a guild | -| [Guild Member Remove](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-remove) | User was removed from a guild | -| [Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update) | Guild member was updated | -| [Guild Members Chunk](#DOCS_TOPICS_GATEWAY_EVENTS/guild-members-chunk) | Response to [Request Guild Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) | -| [Guild Role Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-role-create) | Guild role was created | -| [Guild Role Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-role-update) | Guild role was updated | -| [Guild Role Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-role-delete) | Guild role was deleted | -| [Guild Scheduled Event Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-create) | Guild scheduled event was created | -| [Guild Scheduled Event Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-update) | Guild scheduled event was updated | -| [Guild Scheduled Event Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-delete) | Guild scheduled event was deleted | -| [Guild Scheduled Event User Add](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-user-add) | User subscribed to a guild scheduled event | -| [Guild Scheduled Event User Remove](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-user-remove) | User unsubscribed from a guild scheduled event | -| [Guild Soundboard Sound Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-create) | Guild soundboard sound was created | -| [Guild Soundboard Sound Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-update) | Guild soundboard sound was updated | -| [Guild Soundboard Sound Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-delete) | Guild soundboard sound was deleted | -| [Guild Soundboard Sounds Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sounds-update) | Guild soundboard sounds were updated | -| [Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/soundboard-sounds) | Response to [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds) | -| [Integration Create](#DOCS_TOPICS_GATEWAY_EVENTS/integration-create) | Guild integration was created | -| [Integration Update](#DOCS_TOPICS_GATEWAY_EVENTS/integration-update) | Guild integration was updated | -| [Integration Delete](#DOCS_TOPICS_GATEWAY_EVENTS/integration-delete) | Guild integration was deleted | -| [Interaction Create](#DOCS_TOPICS_GATEWAY_EVENTS/interaction-create) | User used an interaction, such as an [Application Command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/) | -| [Invite Create](#DOCS_TOPICS_GATEWAY_EVENTS/invite-create) | Invite to a channel was created | -| [Invite Delete](#DOCS_TOPICS_GATEWAY_EVENTS/invite-delete) | Invite to a channel was deleted | -| [Message Create](#DOCS_TOPICS_GATEWAY_EVENTS/message-create) | Message was created | -| [Message Update](#DOCS_TOPICS_GATEWAY_EVENTS/message-update) | Message was edited | -| [Message Delete](#DOCS_TOPICS_GATEWAY_EVENTS/message-delete) | Message was deleted | -| [Message Delete Bulk](#DOCS_TOPICS_GATEWAY_EVENTS/message-delete-bulk) | Multiple messages were deleted at once | -| [Message Reaction Add](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-add) | User reacted to a message | -| [Message Reaction Remove](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-remove) | User removed a reaction from a message | -| [Message Reaction Remove All](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-remove-all) | All reactions were explicitly removed from a message | -| [Message Reaction Remove Emoji](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-remove-emoji) | All reactions for a given emoji were explicitly removed from a message | -| [Presence Update](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update) | User was updated | -| [Stage Instance Create](#DOCS_TOPICS_GATEWAY_EVENTS/stage-instance-create) | Stage instance was created | -| [Stage Instance Update](#DOCS_TOPICS_GATEWAY_EVENTS/stage-instance-update) | Stage instance was updated | -| [Stage Instance Delete](#DOCS_TOPICS_GATEWAY_EVENTS/stage-instance-delete) | Stage instance was deleted or closed | -| [Subscription Create](#DOCS_TOPICS_GATEWAY_EVENTS/subscription-create) | Premium App Subscription was created | -| [Subscription Update](#DOCS_TOPICS_GATEWAY_EVENTS/subscription-update) | Premium App Subscription was updated | -| [Subscription Delete](#DOCS_TOPICS_GATEWAY_EVENTS/subscription-delete) | Premium App Subscription was deleted | -| [Typing Start](#DOCS_TOPICS_GATEWAY_EVENTS/typing-start) | User started typing in a channel | -| [User Update](#DOCS_TOPICS_GATEWAY_EVENTS/user-update) | Properties about the user changed | -| [Voice Channel Effect Send](#DOCS_TOPICS_GATEWAY_EVENTS/voice-channel-effect-send) | Someone sent an effect in a voice channel the current user is connected to | -| [Voice State Update](#DOCS_TOPICS_GATEWAY_EVENTS/voice-state-update) | Someone joined, left, or moved a voice channel | -| [Voice Server Update](#DOCS_TOPICS_GATEWAY_EVENTS/voice-server-update) | Guild's voice server was updated | -| [Webhooks Update](#DOCS_TOPICS_GATEWAY_EVENTS/webhooks-update) | Guild channel webhook was created, update, or deleted | -| [Message Poll Vote Add](#DOCS_TOPICS_GATEWAY_EVENTS/message-poll-vote-add) | User voted on a poll | -| [Message Poll Vote Remove](#DOCS_TOPICS_GATEWAY_EVENTS/message-poll-vote-remove) | User removed a vote on a poll | +| [Hello](#DOCS_EVENTS_GATEWAY_EVENTS/hello) | Defines the heartbeat interval | +| [Ready](#DOCS_EVENTS_GATEWAY_EVENTS/ready) | Contains the initial state information | +| [Resumed](#DOCS_EVENTS_GATEWAY_EVENTS/resumed) | Response to [Resume](#DOCS_EVENTS_GATEWAY_EVENTS/resume) | +| [Reconnect](#DOCS_EVENTS_GATEWAY_EVENTS/reconnect) | Server is going away, client should reconnect to gateway and resume | +| [Invalid Session](#DOCS_EVENTS_GATEWAY_EVENTS/invalid-session) | Failure response to [Identify](#DOCS_EVENTS_GATEWAY_EVENTS/identify) or [Resume](#DOCS_EVENTS_GATEWAY_EVENTS/resume) or invalid active session | +| [Application Command Permissions Update](#DOCS_EVENTS_GATEWAY_EVENTS/application-command-permissions-update) | Application command permission was updated | +| [Auto Moderation Rule Create](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-create) | Auto Moderation rule was created | +| [Auto Moderation Rule Update](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-update) | Auto Moderation rule was updated | +| [Auto Moderation Rule Delete](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-delete) | Auto Moderation rule was deleted | +| [Auto Moderation Action Execution](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-action-execution) | Auto Moderation rule was triggered and an action was executed (e.g. a message was blocked) | +| [Channel Create](#DOCS_EVENTS_GATEWAY_EVENTS/channel-create) | New guild channel created | +| [Channel Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-update) | Channel was updated | +| [Channel Delete](#DOCS_EVENTS_GATEWAY_EVENTS/channel-delete) | Channel was deleted | +| [Channel Pins Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-pins-update) | Message was pinned or unpinned | +| [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create) | Thread created, also sent when being added to a private thread | +| [Thread Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-update) | Thread was updated | +| [Thread Delete](#DOCS_EVENTS_GATEWAY_EVENTS/thread-delete) | Thread was deleted | +| [Thread List Sync](#DOCS_EVENTS_GATEWAY_EVENTS/thread-list-sync) | Sent when gaining access to a channel, contains all active threads in that channel | +| [Thread Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-member-update) | [Thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) for the current user was updated | +| [Thread Members Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-members-update) | Some user(s) were added to or removed from a thread | +| [Entitlement Create](#DOCS_EVENTS_GATEWAY_EVENTS/entitlement-create) | Entitlement was created | +| [Entitlement Update](#DOCS_EVENTS_GATEWAY_EVENTS/entitlement-update) | Entitlement was updated or renewed | +| [Entitlement Delete](#DOCS_EVENTS_GATEWAY_EVENTS/entitlement-delete) | Entitlement was deleted | +| [Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) | Lazy-load for unavailable guild, guild became available, or user joined a new guild | +| [Guild Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-update) | Guild was updated | +| [Guild Delete](#DOCS_EVENTS_GATEWAY_EVENTS/guild-delete) | Guild became unavailable, or user left/was removed from a guild | +| [Guild Audit Log Entry Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-audit-log-entry-create) | A guild audit log entry was created | +| [Guild Ban Add](#DOCS_EVENTS_GATEWAY_EVENTS/guild-ban-add) | User was banned from a guild | +| [Guild Ban Remove](#DOCS_EVENTS_GATEWAY_EVENTS/guild-ban-remove) | User was unbanned from a guild | +| [Guild Emojis Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-emojis-update) | Guild emojis were updated | +| [Guild Stickers Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-stickers-update) | Guild stickers were updated | +| [Guild Integrations Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-integrations-update) | Guild integration was updated | +| [Guild Member Add](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-add) | New user joined a guild | +| [Guild Member Remove](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-remove) | User was removed from a guild | +| [Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update) | Guild member was updated | +| [Guild Members Chunk](#DOCS_EVENTS_GATEWAY_EVENTS/guild-members-chunk) | Response to [Request Guild Members](#DOCS_EVENTS_GATEWAY_EVENTS/request-guild-members) | +| [Guild Role Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-role-create) | Guild role was created | +| [Guild Role Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-role-update) | Guild role was updated | +| [Guild Role Delete](#DOCS_EVENTS_GATEWAY_EVENTS/guild-role-delete) | Guild role was deleted | +| [Guild Scheduled Event Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-scheduled-event-create) | Guild scheduled event was created | +| [Guild Scheduled Event Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-scheduled-event-update) | Guild scheduled event was updated | +| [Guild Scheduled Event Delete](#DOCS_EVENTS_GATEWAY_EVENTS/guild-scheduled-event-delete) | Guild scheduled event was deleted | +| [Guild Scheduled Event User Add](#DOCS_EVENTS_GATEWAY_EVENTS/guild-scheduled-event-user-add) | User subscribed to a guild scheduled event | +| [Guild Scheduled Event User Remove](#DOCS_EVENTS_GATEWAY_EVENTS/guild-scheduled-event-user-remove) | User unsubscribed from a guild scheduled event | +| [Guild Soundboard Sound Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-soundboard-sound-create) | Guild soundboard sound was created | +| [Guild Soundboard Sound Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-soundboard-sound-update) | Guild soundboard sound was updated | +| [Guild Soundboard Sound Delete](#DOCS_EVENTS_GATEWAY_EVENTS/guild-soundboard-sound-delete) | Guild soundboard sound was deleted | +| [Guild Soundboard Sounds Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-soundboard-sounds-update) | Guild soundboard sounds were updated | +| [Soundboard Sounds](#DOCS_EVENTS_GATEWAY_EVENTS/soundboard-sounds) | Response to [Request Soundboard Sounds](#DOCS_EVENTS_GATEWAY_EVENTS/request-soundboard-sounds) | +| [Integration Create](#DOCS_EVENTS_GATEWAY_EVENTS/integration-create) | Guild integration was created | +| [Integration Update](#DOCS_EVENTS_GATEWAY_EVENTS/integration-update) | Guild integration was updated | +| [Integration Delete](#DOCS_EVENTS_GATEWAY_EVENTS/integration-delete) | Guild integration was deleted | +| [Interaction Create](#DOCS_EVENTS_GATEWAY_EVENTS/interaction-create) | User used an interaction, such as an [Application Command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/) | +| [Invite Create](#DOCS_EVENTS_GATEWAY_EVENTS/invite-create) | Invite to a channel was created | +| [Invite Delete](#DOCS_EVENTS_GATEWAY_EVENTS/invite-delete) | Invite to a channel was deleted | +| [Message Create](#DOCS_EVENTS_GATEWAY_EVENTS/message-create) | Message was created | +| [Message Update](#DOCS_EVENTS_GATEWAY_EVENTS/message-update) | Message was edited | +| [Message Delete](#DOCS_EVENTS_GATEWAY_EVENTS/message-delete) | Message was deleted | +| [Message Delete Bulk](#DOCS_EVENTS_GATEWAY_EVENTS/message-delete-bulk) | Multiple messages were deleted at once | +| [Message Reaction Add](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-add) | User reacted to a message | +| [Message Reaction Remove](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-remove) | User removed a reaction from a message | +| [Message Reaction Remove All](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-remove-all) | All reactions were explicitly removed from a message | +| [Message Reaction Remove Emoji](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-remove-emoji) | All reactions for a given emoji were explicitly removed from a message | +| [Presence Update](#DOCS_EVENTS_GATEWAY_EVENTS/presence-update) | User was updated | +| [Stage Instance Create](#DOCS_EVENTS_GATEWAY_EVENTS/stage-instance-create) | Stage instance was created | +| [Stage Instance Update](#DOCS_EVENTS_GATEWAY_EVENTS/stage-instance-update) | Stage instance was updated | +| [Stage Instance Delete](#DOCS_EVENTS_GATEWAY_EVENTS/stage-instance-delete) | Stage instance was deleted or closed | +| [Subscription Create](#DOCS_EVENTS_GATEWAY_EVENTS/subscription-create) | Premium App Subscription was created | +| [Subscription Update](#DOCS_EVENTS_GATEWAY_EVENTS/subscription-update) | Premium App Subscription was updated | +| [Subscription Delete](#DOCS_EVENTS_GATEWAY_EVENTS/subscription-delete) | Premium App Subscription was deleted | +| [Typing Start](#DOCS_EVENTS_GATEWAY_EVENTS/typing-start) | User started typing in a channel | +| [User Update](#DOCS_EVENTS_GATEWAY_EVENTS/user-update) | Properties about the user changed | +| [Voice Channel Effect Send](#DOCS_EVENTS_GATEWAY_EVENTS/voice-channel-effect-send) | Someone sent an effect in a voice channel the current user is connected to | +| [Voice State Update](#DOCS_EVENTS_GATEWAY_EVENTS/voice-state-update) | Someone joined, left, or moved a voice channel | +| [Voice Server Update](#DOCS_EVENTS_GATEWAY_EVENTS/voice-server-update) | Guild's voice server was updated | +| [Webhooks Update](#DOCS_EVENTS_GATEWAY_EVENTS/webhooks-update) | Guild channel webhook was created, update, or deleted | +| [Message Poll Vote Add](#DOCS_EVENTS_GATEWAY_EVENTS/message-poll-vote-add) | User voted on a poll | +| [Message Poll Vote Remove](#DOCS_EVENTS_GATEWAY_EVENTS/message-poll-vote-remove) | User removed a vote on a poll | #### Hello @@ -398,7 +402,7 @@ Sent on connection to the websocket. Defines the heartbeat interval that an app 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](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) events. +`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](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) events. ###### Ready Event Fields @@ -409,16 +413,16 @@ The ready event is dispatched when a client has completed the initial handshake | guilds | array of [Unavailable Guild](#DOCS_RESOURCES_GUILD/unavailable-guild-object) 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](#DOCS_TOPICS_GATEWAY/sharding) associated with this session, if sent when identifying | +| shard? | array of two integers (shard_id, num_shards) | [Shard information](#DOCS_EVENTS_GATEWAY/sharding) associated with this session, if sent when identifying | | application | partial [application object](#DOCS_RESOURCES_APPLICATION/application-object) | Contains `id` and `flags` | #### Resumed -The resumed event is dispatched when a client has sent a [resume payload](#DOCS_TOPICS_GATEWAY_EVENTS/resume) to the gateway (for resuming existing sessions). +The resumed event is dispatched when a client has sent a [resume payload](#DOCS_EVENTS_GATEWAY_EVENTS/resume) 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](#DOCS_TOPICS_GATEWAY_EVENTS/hello) event. A few seconds after the reconnect event is dispatched, the connection may be closed by the server. +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](#DOCS_EVENTS_GATEWAY_EVENTS/hello) event. A few seconds after the reconnect event is dispatched, the connection may be closed by the server. ###### Example Gateway Reconnect @@ -433,11 +437,11 @@ The reconnect event is dispatched when a client should reconnect to the gateway Sent to indicate one of at least three different situations: -- the gateway could not initialize a session after receiving an [Opcode 2 Identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) -- the gateway could not resume a previous session after receiving an [Opcode 6 Resume](#DOCS_TOPICS_GATEWAY_EVENTS/resume) +- the gateway could not initialize a session after receiving an [Opcode 2 Identify](#DOCS_EVENTS_GATEWAY_EVENTS/identify) +- the gateway could not resume a previous session after receiving an [Opcode 6 Resume](#DOCS_EVENTS_GATEWAY_EVENTS/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](#DOCS_TOPICS_GATEWAY/connecting) and [Resuming](#DOCS_TOPICS_GATEWAY/resuming) for more information. +The inner `d` key is a boolean that indicates whether the session may be resumable. See [Connecting](#DOCS_EVENTS_GATEWAY/connecting) and [Resuming](#DOCS_EVENTS_GATEWAY/resuming) for more information. ###### Example Gateway Invalid Session @@ -494,7 +498,7 @@ Sent when a rule is triggered and an action is executed (e.g. when a message is \*\* `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](#DOCS_TOPICS_GATEWAY/gateway-intents) is required to receive the `content` and `matched_content` fields +\*\*\* `MESSAGE_CONTENT` (`1 << 15`) [gateway intent](#DOCS_EVENTS_GATEWAY/gateway-intents) is required to receive the `content` and `matched_content` fields ### Channels @@ -504,7 +508,7 @@ Sent when a new guild channel is created, relevant to the current user. The inne #### Channel Update -Sent when a channel is updated. The inner payload is a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) 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](#DOCS_TOPICS_GATEWAY_EVENTS/message-create) events (or [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) events for `GUILD_FORUM` and `GUILD_MEDIA` channels). +Sent when a channel is updated. The inner payload is a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) 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](#DOCS_EVENTS_GATEWAY_EVENTS/message-create) events (or [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/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. @@ -521,7 +525,7 @@ Sent when a thread is created, relevant to the current user, or when the current #### Thread Update -Sent when a thread is updated. The inner payload is a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) 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](#DOCS_TOPICS_GATEWAY_EVENTS/message-create) events. +Sent when a thread is updated. The inner payload is a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) 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](#DOCS_EVENTS_GATEWAY_EVENTS/message-create) events. #### Thread Delete @@ -553,7 +557,7 @@ Sent when the [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) obje #### 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](#DOCS_TOPICS_GATEWAY/gateway-intents), then this event will only be sent if the current user was added to or removed from the thread. +Sent when anyone is added to or removed from a thread. If the current user does not have the `GUILD_MEMBERS` [Gateway Intent](#DOCS_EVENTS_GATEWAY/gateway-intents), then this event will only be sent if the current user was added to or removed from the thread. ###### Thread Members Update Event Fields @@ -565,7 +569,7 @@ Sent when anyone is added to or removed from a thread. If the current user does | added_members?\* | array of [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) 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](#DOCS_RESOURCES_GUILD/guild-member-object) and nullable [presence](#DOCS_TOPICS_GATEWAY_EVENTS/presence) objects for each added thread member. +\* In this gateway event, the thread member objects will also include the [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) and nullable [presence](#DOCS_EVENTS_GATEWAY_EVENTS/presence) objects for each added thread member. #### Channel Pins Update @@ -583,9 +587,6 @@ Sent when a message is pinned or unpinned in a text channel. This is not sent wh #### Entitlement Create -> danger -> Starting on October 1st, 2024, the `ENTITLEMENT_CREATE` event will have an `ends_at` value of null. Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/subscription-api-and-entitlement-migration) for more information. - Sent when an entitlement is created. The inner payload is an [entitlement](#DOCS_RESOURCES_ENTITLEMENT/entitlement-object) object. #### Entitlement Update @@ -617,7 +618,7 @@ 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](#DOCS_TOPICS_GATEWAY_EVENTS/ready) event. Guilds that are unavailable due to an outage will send a [Guild Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-delete) event. +1. When a user is initially connecting, to lazily load and backfill information for all unavailable guilds sent in the [Ready](#DOCS_EVENTS_GATEWAY_EVENTS/ready) event. Guilds that are unavailable due to an outage will send a [Guild Delete](#DOCS_EVENTS_GATEWAY_EVENTS/guild-delete) event. 2. When a Guild becomes available again to the client. 3. When the current user joins a new Guild. @@ -641,13 +642,13 @@ The inner payload can be: | members | array of [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) objects | Users in the guild | | channels | array of [channel](#DOCS_RESOURCES_CHANNEL/channel-object) objects | Channels in the guild | | threads | array of [channel](#DOCS_RESOURCES_CHANNEL/channel-object) objects | All active threads in the guild that current user has permission to view | -| presences | array of partial [presence update](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update) objects | Presences of the members in the guild, will only include non-offline members if the size is greater than `large threshold` | +| presences | array of partial [presence update](#DOCS_EVENTS_GATEWAY_EVENTS/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](#DOCS_RESOURCES_STAGE_INSTANCE/stage-instance-object) objects | Stage instances in the guild | | guild_scheduled_events | array of [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) objects | Scheduled events in the guild | | soundboard_sounds | array of [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) objects | Soundboard sounds in the guild | > warn -> If your bot does not have the `GUILD_PRESENCES` [Gateway Intent](#DOCS_TOPICS_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. +> If your bot does not have the `GUILD_PRESENCES` [Gateway Intent](#DOCS_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 @@ -724,7 +725,7 @@ Sent when a guild integration is updated. #### Guild Member Add > warn -> If using [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event. +> If using [Gateway Intents](#DOCS_EVENTS_GATEWAY/gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event. Sent when a new user joins a guild. The inner payload is a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object with an extra `guild_id` key: @@ -737,7 +738,7 @@ Sent when a new user joins a guild. The inner payload is a [guild member](#DOCS_ #### Guild Member Remove > warn -> If using [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event. +> If using [Gateway Intents](#DOCS_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). @@ -751,7 +752,7 @@ Sent when a user is removed from a guild (leave/kick/ban). #### Guild Member Update > warn -> If using [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents), the `GUILD_MEMBERS` intent will be required to receive this event. +> If using [Gateway Intents](#DOCS_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. @@ -776,7 +777,7 @@ Sent when a guild member is updated. This will also fire when the user object of #### Guild Members Chunk -Sent in response to [Guild Request Members](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members). +Sent in response to [Guild Request Members](#DOCS_EVENTS_GATEWAY_EVENTS/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 Event Fields @@ -785,11 +786,11 @@ You can use the `chunk_index` and `chunk_count` to calculate how many chunks are |-------------|----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| | guild_id | snowflake | ID of the guild | | members | array of [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) objects | Set of guild members | -| chunk_index | integer | Chunk index in the expected chunks for this response (0 <= chunk\_index < chunk\_count) | +| 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](#DOCS_TOPICS_GATEWAY_EVENTS/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](#DOCS_TOPICS_GATEWAY_EVENTS/request-guild-members) | +| presences? | array of [presence](#DOCS_EVENTS_GATEWAY_EVENTS/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](#DOCS_EVENTS_GATEWAY_EVENTS/request-guild-members) | #### Guild Role Create @@ -892,7 +893,7 @@ Sent when multiple guild soundboard sounds are updated. #### Soundboard Sounds -Includes a guild's list of soundboard sounds. Sent in response to [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds). +Includes a guild's list of soundboard sounds. Sent in response to [Request Soundboard Sounds](#DOCS_EVENTS_GATEWAY_EVENTS/request-soundboard-sounds). ###### Soundboard Sounds Event Fields @@ -975,7 +976,7 @@ Sent when an invite is deleted. ### Messages > warn -> 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](#DOCS_TOPICS_GATEWAY/list-of-intents), and the message object won't include `guild_id` or `member`. +> 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](#DOCS_EVENTS_GATEWAY/list-of-intents), and the message object won't include `guild_id` or `member`. #### Message Create @@ -991,7 +992,7 @@ Sent when a message is created. The inner payload is a [message](#DOCS_RESOURCES #### Message Update -Sent when a message is updated. The inner payload is a [message](#DOCS_RESOURCES_MESSAGE/message-object) object with the same extra fields as [MESSAGE_CREATE](#DOCS_TOPICS_GATEWAY_EVENTS/message-create). +Sent when a message is updated. The inner payload is a [message](#DOCS_RESOURCES_MESSAGE/message-object) object with the same extra fields as [MESSAGE_CREATE](#DOCS_EVENTS_GATEWAY_EVENTS/message-create). > warn > The value for `tts` will always be false in message updates. @@ -1085,7 +1086,7 @@ Sent when a bot removes all instances of a given emoji from the reactions of a m #### Presence Update > warn -> If you are using [Gateway Intents](#DOCS_TOPICS_GATEWAY/gateway-intents), you _must_ specify the `GUILD_PRESENCES` intent in order to receive Presence Update events +> If you are using [Gateway Intents](#DOCS_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. @@ -1099,8 +1100,8 @@ A user's presence is their current state on a guild. This event is sent when a u | user | [user](#DOCS_RESOURCES_USER/user-object) 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](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object) objects | User's current activities | -| client_status | [client_status](#DOCS_TOPICS_GATEWAY_EVENTS/client-status-object) object | User's platform-dependent status | +| activities | array of [activity](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object) objects | User's current activities | +| client_status | [client_status](#DOCS_EVENTS_GATEWAY_EVENTS/client-status-object) object | User's platform-dependent status | #### Client Status Object @@ -1119,34 +1120,34 @@ Active sessions are indicated with an "online", "idle", or "dnd" string per plat | Field | Type | Description | |-----------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| | name | string | Activity's name | -| type | integer | [Activity type](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-types) | +| type | integer | [Activity type](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-types) | | 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](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-timestamps) object | Unix timestamps for start and/or end of the game | +| timestamps? | [timestamps](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-timestamps) object | Unix timestamps for start and/or end of the game | | application_id? | snowflake | Application ID for the game | | details? | ?string | What the player is currently doing | | state? | ?string | User's current party status, or text used for a custom status | -| emoji? | ?[emoji](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-emoji) object | Emoji used for a custom status | -| party? | [party](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-party) object | Information for the current party of the player | -| assets? | [assets](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-assets) object | Images for the presence and their hover texts | -| secrets? | [secrets](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-secrets) object | Secrets for Rich Presence joining and spectating | +| emoji? | ?[emoji](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-emoji) object | Emoji used for a custom status | +| party? | [party](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-party) object | Information for the current party of the player | +| assets? | [assets](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-assets) object | Images for the presence and their hover texts | +| secrets? | [secrets](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-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](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-flags) `OR`d together, describes what the payload includes | -| buttons? | array of [buttons](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-buttons) | Custom buttons shown in the Rich Presence (max 2) | +| flags? | integer | [Activity flags](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-flags) `OR`d together, describes what the payload includes | +| buttons? | array of [buttons](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-buttons) | Custom buttons shown in the Rich Presence (max 2) | > info > 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" | +| 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" | > info > The streaming type currently only supports Twitch and YouTube. Only `https://twitch.tv/` and `https://youtube.com/` urls will work. @@ -1180,9 +1181,9 @@ Active sessions are indicated with an "online", "idle", or "dnd" string per plat | Field | Type | Description | |--------------|--------|----------------------------------------------------------------------------------------------| -| large_image? | string | See [Activity Asset Image](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-asset-image) | +| large_image? | string | See [Activity Asset Image](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-asset-image) | | large_text? | string | Text displayed when hovering over the large image of the activity | -| small_image? | string | See [Activity Asset Image](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-asset-image) | +| small_image? | string | See [Activity Asset Image](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-asset-image) | | small_text? | string | Text displayed when hovering over the small image of the activity | ###### Activity Asset Image @@ -1304,7 +1305,7 @@ Sent when someone sends an effect, such as an emoji reaction or a soundboard sou | 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](#DOCS_RESOURCES_EMOJI/emoji-object) object | The emoji sent, for emoji reaction and soundboard effects | -| animation_type? | ?integer | The [type of emoji animation](#DOCS_TOPICS_GATEWAY_EVENTS/voice-channel-effect-send-animation-types), for emoji reaction and soundboard effects | +| animation_type? | ?integer | The [type of emoji animation](#DOCS_EVENTS_GATEWAY_EVENTS/voice-channel-effect-send-animation-types), 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 | diff --git a/docs/events/Overview.mdx b/docs/events/Overview.mdx new file mode 100644 index 0000000000..7ea46e3a95 --- /dev/null +++ b/docs/events/Overview.mdx @@ -0,0 +1,53 @@ +--- +sidebar_label: Overview +--- + +# Overview of Events + +Apps can listen to events happening in Discord to stay up-to-date with changes and updates to servers, users, and even your app. The following sections cover basic information about the different transport methods that can be used to receive events, and link out to relevant documentation. + +## Receiving Events + +There are many event types that can be accessed using different transport methods: +- **[Gateway events](#DOCS_EVENTS_OVERVIEW/using-gateway)** are sent over a WebSocket connection between your app and Discord, and is the primary way to receive and send events. **Most events are only available via Gateway connections.** +- **[Webhook events](#DOCS_EVENTS_OVERVIEW/using-webhooks)** are sent to your app's Webhook Event URL over HTTP. +- **[SDK events](#DOCS_EVENTS_OVERVIEW/using-the-embedded-app-sdk)** are sent to your app when using the Embedded App SDK. + +Read details about each way to receive events in the sections below. + +### Using Gateway + +Gateway events are the primary way apps can listen and send events. Most events related to resources in Discord, like updates to channels, guilds, roles, and messages, are only available over [Gateway](#DOCS_EVENTS_GATEWAY). + +Gateway events are sent over a WebSocket-based [Gateway connection](#DOCS_EVENTS_GATEWAY/connections) between Discord and your app. To receive Gateway events, your app must open and maintain a persistent Gateway connection which you can read details about in the [Gateway documentation](#DOCS_EVENTS_GATEWAY/connections). To make receiving Gateway events simpler, we suggest using a [developer library](#DOCS_DEVELOPER_TOOLS_COMMUNITY_RESOURCES/libraries) which helps setup, maintain, and handle common pitfalls with Gateway connections (like [rate limits](#DOCS_EVENTS_GATEWAY/rate-limiting)). + +Details about receiving events using the Gateway API is in the [Gateway documentation](#DOCS_EVENTS_GATEWAY/receiving-events), and the full list of available Gateway events is in the [Gateway Events documentation](#DOCS_EVENTS_GATEWAY_EVENTS). + +### Using Webhooks + +Webhook events let you receive a small number of events over HTTP. While many events aren't supported over HTTP, some events like [Application Authorized](#DOCS_EVENTS_WEBHOOK_EVENTS/application-authorized) (sent when your app is installed to a user or server) aren't available using other transport methods like Gateway. + +Find the [list of webhook events](#DOCS_EVENTS_WEBHOOK_EVENTS/event-types) and details about subscribing and handling them in the [Webhook Events documentation](#DOCS_EVENTS_WEBHOOK_EVENTS). + + +### Using the Embedded App SDK + +When developing [Activities](#DOCS_ACTIVITIES_OVERVIEW), you can listen to a collection of [SDK events](#DOCS_DEVELOPER_TOOLS_EMBEDDED_APP_SDK/sdk-events), like updates to a user's voice status or screen orientation. To listen to SDK events, you can call [`subscribe()`](#DOCS_DEVELOPER_TOOLS_EMBEDDED_APP_SDK/subscribe) with the SDK event name. + +Details about listening to events using the Embedded App SDK is in the [Embedded App SDK documentation](#DOCS_DEVELOPER_TOOLS_EMBEDDED_APP_SDK). + +## Next Steps + + + + Gateway is the primary apps receive events on Discord. Read details about using the Gateway and receiving Gateway Events. + + + Read details about receiving and responding a small number of HTTP-based Webhook Events. + + + Read details about subscribing and receiving events specific to your Activity using the Embedded App SDK. + + + + diff --git a/docs/events/Webhook_Events.mdx b/docs/events/Webhook_Events.mdx new file mode 100644 index 0000000000..86f6986a2b --- /dev/null +++ b/docs/events/Webhook_Events.mdx @@ -0,0 +1,211 @@ +--- +sidebar_label: Webhook Events +--- + +# Webhook Events + +Webhook events are one-way events sent to your app over HTTP to notify you when an event occured. Unlike events that are [sent over Gateway connections](#DOCS_EVENTS_GATEWAY), events sent over webhooks are not realtime or guaranteed to be in order. + +While [incoming webhooks](#DOCS_RESOURCES_WEBHOOK) are triggered by an external service, webhook events (i.e. outgoing webhooks) are triggered by events happening in Discord. This means your app will need to set up a public URL where you can receive HTTP events, which is detailed in the [preparing for events](#DOCS_EVENTS_WEBHOOK_EVENTS/preparing-for-events) section. + +## Subscribing to Events + +To configure webhook events, you'll need to configure your URL and select the events you want your app to receive. + +> info +> The steps below walk through subscribing using the developer portal. If you prefer to use the API, you can call [Edit Current Application](#DOCS_RESOURCES_APPLICATION/edit-current-application). + +In your [app's settings](https://discord.com/developers/applications), navigate to the **Webhooks** page from the left-hand sidebar then complete the following: + +1. Under **Endpoint**, add a public URL that is set up to receive and acknowledge webhook events. Details about setting up a Webhook Events URL is in the [preparing for events](#DOCS_EVENTS_WEBHOOK_EVENTS/preparing-for-events) section. +2. Enable Events by clicking the toggle in the **Events** section. +3. Select the [webhook events](#DOCS_EVENTS_WEBHOOK_EVENTS/event-types) you want your app to receive. +4. Click **Save Changes**. + +If your URL is successfully verified, your app should begin receiving the events you selected. + +## Preparing for Events + +To receive webhook events, you'll need to configure your app's **Webhook Event URL** in your app's settings. + +### Configuring a Webhook Events URL + +A **Webhook Events URL** is a public endpoint for your app where Discord can send your app HTTP-based events. If your app is using [Gateway events](#DOCS_EVENTS_GATEWAY), you don't need to configure a Webhook Events URL. + +#### Setting Up an Endpoint + +Before you can add a Webhook Events URL to your app, your endpoint must be prepared for two things ahead of time: + +1. Acknowledging `PING` events from Discord +2. Validate security-related request headers (`X-Signature-Ed25519` and `X-Signature-Timestamp`) + +If either of these are not complete, your Webhook Events URL will not be validated. Details on acknowledging PING events and validating security-related headers are below. + +###### Acknowledging PING requests + +When adding your Webhook Events URL, Discord will send a `POST` request with a `PING` payload with a `type: 0` to your endpoint. Your app is expected to acknowledge the request by returning a `204` response with an empty body. + + +To properly acknowledge a `PING` payload, return a `204` response with no body: + +```py +@app.route('/', methods=['POST']) +def my_command(): + if request.json["type"] == 'PING': + return Response(status=204) +``` + + +###### Validating Security Request Headers + +To receive events via HTTP, there are some security steps you **must** take before your app is eligible to receive requests. + +Each webhook is sent with the following headers: + +- `X-Signature-Ed25519` as a signature +- `X-Signature-Timestamp` as a timestamp + +Using your favorite security library, you **must validate the request each time you receive an event**. If the signature fails validation, your app should respond with a `401` error code. Code examples of validating security headers is in the [Interactions documentation](#DOCS_INTERACTIONS_OVERVIEW/setting-up-an-endpoint-validating-security-request-headers). + +In addition to ensuring your app validates security-related request headers at the time of saving your endpoint, Discord will also perform automated, routine security checks against your endpoint, including purposefully sending you invalid signatures. If you fail the validation, we will remove your Webhook Events URL and alert you via email and System DM. + +We recommend checking out our [Community Resources](#DOCS_DEVELOPER_TOOLS_COMMUNITY_RESOURCES) and the libraries found there. + +#### Adding an Webhook Events Endpoint URL + +After you have a public endpoint to use as your app's Event Webhooks URL, you can add it to your app by going to your [app's settings](https://discord.com/developers/applications). + +On the **Webhooks** page, look for the **Endpoint URL** field. Paste your public URL that is set up to acknowledge `PING` messages and correctly handles security-related signature headers. + +After you configure your Webhook Events URL, you can [enable and subscribe to events](#DOCS_EVENTS_WEBHOOK_EVENTS/subscribing-to-events) on the same page. + + +## Responding to Events + +When your Webhook Event URL receives a webhook event, your app should respond with a `204` status code with no body **within 3 seconds** to acknowledge that your app successfully received it. If your app doesn't respond to the webhook event, Discord will retry sending it several times using exponential backoff for up to 10 minutes. + +If your app fails to respond too often, Discord will stop sending you webhook events and notify you via email. + +## Webhook Event Payloads + +Webhook events are wrapped in an outer payload, with an inner `event` object. + +### Payload Structure + +Structure of the outer webhook payload + +| Field | Type | Description | +|----------------|--------------------------------------------------------------------|----------------------------------------------------------------| +| version | integer | Version scheme for the webhook event. Currently always `1` | +| application_id | snowflake | ID of your app | +| type | [webhook type](#DOCS_EVENTS_WEBHOOK_EVENTS/webhook-types) | Type of webhook, either `0` for PING or `1` for webhook events | +| event? | [event body](#DOCS_EVENTS_WEBHOOK_EVENTS/event-body-object) object | Event data payload | + +#### Webhook Types + +| Type | Value | Description | +|-------|-------|---------------------------------------------------------------------------------------------------------| +| PING | `0` | PING event sent to verify your Webhook Event URL is active | +| Event | `1` | Webhook event (details for event in [event body](#DOCS_EVENTS_WEBHOOK_EVENTS/event-body-object) object) | + +#### Event Body Object + +The event body contains high-level data about the event, like the type and time it was triggered. + +The inner `data` object contains information specific to the [event type](#DOCS_EVENTS_WEBHOOK_EVENTS/event-types). + +| Field | Type | Description | +|-----------|--------|----------------------------------------------------------------------------------------------------| +| type | string | [Event type](#DOCS_EVENTS_WEBHOOK_EVENTS/event-types) | +| timestamp | string | Timestamp of when the event occurred in [ISO8601 format](#DOCS_REFERENCE/iso8601-datetime) | +| data? | object | Data for the event. The shape depends on the [event type](#DOCS_EVENTS_WEBHOOK_EVENTS/event-types) | + + +## Event Types + +The table below includes the different webhook event types your app can subscribe to. + +The "Value" column corresponds to the event's `type` field value in the [event body object](#DOCS_EVENTS_WEBHOOK_EVENTS/event-body-object). + +| Name | Value | Description | +|------------------------------------------------------------------------------|--------------------------|------------------------------------------------------------------------| +| [Application Authorized](#DOCS_EVENTS_WEBHOOK_EVENTS/application-authorized) | `APPLICATION_AUTHORIZED` | Sent when an app was authorized by a user to a server or their account | +| [Entitlement Create](#DOCS_EVENTS_WEBHOOK_EVENTS/entitlement-create) | `ENTITLEMENT_CREATE` | Entitlement was created | +| [Quest User Enrollment](#DOCS_EVENTS_WEBHOOK_EVENTS/quest-user-enrollment) | `QUEST_USER_ENROLLMENT` | User was added to a Quest (currently unavailable) | + +#### Application Authorized + +`APPLICATION_AUTHORIZED` is sent when the app is added to a server or user account. + +###### Application Authorized Structure + +| Field | Type | Description | +|-------------------|--------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| integration_type? | integer | [Installation context](#DOCS_RESOURCES_APPLICATION/application-object-application-integration-types) for the authorization. Either guild (`0`) if installed to a server or user (`1`) if installed to a user's account | +| user | [user object](#DOCS_RESOURCES_USER/user-object-user-structure) | User who authorized the app | +| scopes | array of strings | List of [scopes](#DOCS_TOPICS_OAUTH2/shared-resources-oauth2-scopes) the user authorized | +| guild? | [guild object](#DOCS_RESOURCES_GUILD/guild-object-guild-structure) | Server which app was authorized for (when integration type is `0`) | + + +###### Application Authorized Example + +```json +{ + "version": 1, + "application_id": "1234560123453231555", + "type": 1, + "event": { + "type": "APPLICATION_AUTHORIZED", + "timestamp": "2024-10-18T14:42:53.064834", + "data": { + "integration_type": 1, + "scopes": [ + "applications.commands" + ], + "user": { + // user data + } + } + } +} +``` + +#### Entitlement Create + +`ENTITLEMENT_CREATE` is sent when an [entitlement](#DOCS_RESOURCES_ENTITLEMENT) is created when a user purchases or is otherwise granted one of your app's SKUs. Refer to the [Monetization documentation](#DOCS_MONETIZATION_OVERVIEW) for details. + +###### Entitlement Create Structure + +The inner payload is an [entitlement](#DOCS_RESOURCES_ENTITLEMENT/entitlement-object) object. + +###### Entitlement Create Example + +```json +{ + "version": 1, + "application_id": "1234560123453231555", + "type": 1, + "event": { + "type": "ENTITLEMENT_CREATE", + "timestamp": "2024-10-18T18:41:21.109604", + "data": { + "application_id": "1234560123453231555", + "consumed": false, + "deleted": false, + "gift_code_flags": 0, + "id": "1234505980407808808", + "promotion_id": null, + "sku_id": "123489045643835123", + "type": 4, + "user_id": "111178765189277770" + } + } +} +``` + +#### Quest User Enrollment + +> warn +> This event cannot be received by apps at this time. It's documented because it appears on the Webhooks settings page. + +`QUEST_USER_ENROLLMENT` is sent when a user is added to a Quest on Discord. diff --git a/docs/interactions/Application_Commands.mdx b/docs/interactions/Application_Commands.mdx index 97caebb76f..6aca4a22c2 100644 --- a/docs/interactions/Application_Commands.mdx +++ b/docs/interactions/Application_Commands.mdx @@ -1299,7 +1299,7 @@ Fetches permissions for a specific command for your application in a guild. Retu > warn > This endpoint will overwrite existing permissions for the command in that guild -Edits command permissions for a specific command for your application in a guild and returns a [guild application command permissions](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-permissions-object-guild-application-command-permissions-structure) object. Fires an [Application Command Permissions Update](#DOCS_TOPICS_GATEWAY_EVENTS/application-command-permissions-update) Gateway event. +Edits command permissions for a specific command for your application in a guild and returns a [guild application command permissions](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/application-command-permissions-object-guild-application-command-permissions-structure) object. Fires an [Application Command Permissions Update](#DOCS_EVENTS_GATEWAY_EVENTS/application-command-permissions-update) Gateway event. You can add up to 100 permission overwrites for a command. diff --git a/docs/interactions/Overview.mdx b/docs/interactions/Overview.mdx index 3e03ef132e..2894df0d6e 100644 --- a/docs/interactions/Overview.mdx +++ b/docs/interactions/Overview.mdx @@ -65,7 +65,7 @@ By default your app will receive interactions via a Gateway connection, but you ### Configuring an Interactions Endpoint URL -A **Interactions Endpoint URL** is a public endpoint for your app where Discord can send your app HTTP-based interactions. If your app is using [Gateway](#DOCS_TOPICS_GATEWAY)-based interactions, you don't need to configure an Interactions Endpoint URL. +A **Interactions Endpoint URL** is a public endpoint for your app where Discord can send your app HTTP-based interactions. If your app is using [Gateway](#DOCS_EVENTS_GATEWAY)-based interactions, you don't need to configure an Interactions Endpoint URL. #### Setting Up an Endpoint diff --git a/docs/interactions/Receiving_and_Responding.mdx b/docs/interactions/Receiving_and_Responding.mdx index 50dec5a423..0e37f26632 100644 --- a/docs/interactions/Receiving_and_Responding.mdx +++ b/docs/interactions/Receiving_and_Responding.mdx @@ -174,10 +174,10 @@ This is sent on the [message object](#DOCS_RESOURCES_MESSAGE/message-object) whe When a user interacts with your app, your app will receive an **[Interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object)**. Your app can receive an interaction in one of two ways: -- Via [Interaction Create](#DOCS_TOPICS_GATEWAY_EVENTS/interaction-create) gateway event +- Via [Interaction Create](#DOCS_EVENTS_GATEWAY_EVENTS/interaction-create) gateway event - Via outgoing webhook -These two methods are **mutually exclusive**; you can _only_ receive Interactions one of the two ways. The `INTERACTION_CREATE` [Gateway Event](#DOCS_TOPICS_GATEWAY_EVENTS/interaction-create) may be handled by connected clients, while the webhook method detailed below does not require a connected client. +These two methods are **mutually exclusive**; you can _only_ receive Interactions one of the two ways. The `INTERACTION_CREATE` [Gateway Event](#DOCS_EVENTS_GATEWAY_EVENTS/interaction-create) may be handled by connected clients, while the webhook method detailed below does not require a connected client. If you want to receive interactions via HTTP-based outgoing webhooks, you must configure an Interactions Endpoint URL for your app. You can read about preparing and adding an Interactions Endpoint URL to your app in the [Preparing for Interactions](#DOCS_INTERACTIONS_OVERVIEW/preparing-for-interactions) section in Interactions Overview. diff --git a/docs/monetization/Implementing_App_Subscriptions.mdx b/docs/monetization/Implementing_App_Subscriptions.mdx index bedd1e4e87..d588e96b61 100644 --- a/docs/monetization/Implementing_App_Subscriptions.mdx +++ b/docs/monetization/Implementing_App_Subscriptions.mdx @@ -68,14 +68,14 @@ Because entitlements are granted indefinitely and don't update on renewal or can When a user purchases a subscription, an entitlement is created. [Entitlements](#DOCS_RESOURCES_ENTITLEMENT) represent the user's access to your consumable or durable item. -Depending on your app's features, you can use a combination of [Gateway events](#DOCS_TOPICS_GATEWAY_EVENTS/entitlements), the [Entitlement HTTP API](#DOCS_RESOURCES_ENTITLEMENT), and [interaction payloads](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING) to keep track of user and guild entitlements and grant perks to users who have subscribed to your app. +Depending on your app's features, you can use a combination of [Gateway events](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements), the [Entitlement HTTP API](#DOCS_RESOURCES_ENTITLEMENT), and [interaction payloads](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING) to keep track of user and guild entitlements and grant perks to users who have subscribed to your app. ### Accessing Entitlements with Gateway Events > danger > **Starting on October 1, 2024**, the `ENTITLEMENT_CREATE` and `ENTITLEMENT_UPDATE` event behavior described below is changing. Please see the [Change Log and Entitlement Migration Guide](#DOCS_CHANGE_LOG/subscription-api-and-entitlement-migration) for more information on what is changing and how to prepare. The docs will be updated on November 1, 2024 to reflect the new behavior. -When users subscribe or renew a subscription with your app, Discord will emit [Entitlement Gateway events](#DOCS_TOPICS_GATEWAY_EVENTS/entitlements). +When users subscribe or renew a subscription with your app, Discord will emit [Entitlement Gateway events](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements). For subscription SKUs, you will receive the following entitlement events: @@ -124,7 +124,7 @@ You can use the [Subscription API](#DOCS_RESOURCES_SUBSCRIPTION) to check on the - [List SKU Subscriptions](#DOCS_RESOURCES_SUBSCRIPTION/list-sku-subscriptions): List all subscriptions for a specific SKU in your app. - [Get SKU Subscription](#DOCS_RESOURCES_SUBSCRIPTION/get-sku-subscription): Get a specific subscription in your app. -- [Subscription Gateway events](#DOCS_TOPICS_GATEWAY_EVENTS/subscriptions): Discord will emit gateway events when a subscription is created, updated, and very rarely, deleted. +- [Subscription Gateway events](#DOCS_EVENTS_GATEWAY_EVENTS/subscriptions): Discord will emit gateway events when a subscription is created, updated, and very rarely, deleted. --- diff --git a/docs/monetization/Implementing_IAP_for_Activities.mdx b/docs/monetization/Implementing_IAP_for_Activities.mdx index 448b21d832..f4846e0654 100644 --- a/docs/monetization/Implementing_IAP_for_Activities.mdx +++ b/docs/monetization/Implementing_IAP_for_Activities.mdx @@ -83,7 +83,7 @@ console.log(`The price is ${displayPrice}!`); When a user purchases a SKU, an entitlement is created. [Entitlements](#DOCS_RESOURCES_ENTITLEMENT) represent the user's access to your premium product. -Depending on your app's features, you can use a combination of the [Embedded App SDK events](#DOCS_DEVELOPER_TOOLS_EMBEDDED_APP_SDK/getentitlements), [Gateway events](#DOCS_TOPICS_GATEWAY_EVENTS/entitlements), the [Entitlement HTTP API](#DOCS_RESOURCES_ENTITLEMENT), and [interaction payloads](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING) to keep track of entitlements to users who have purchased items in your app. +Depending on your app's features, you can use a combination of the [Embedded App SDK events](#DOCS_DEVELOPER_TOOLS_EMBEDDED_APP_SDK/getentitlements), [Gateway events](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements), the [Entitlement HTTP API](#DOCS_RESOURCES_ENTITLEMENT), and [interaction payloads](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING) to keep track of entitlements to users who have purchased items in your app. ### Fetching Entitlements with the Embedded App SDK @@ -138,7 +138,7 @@ const handleEntitlementCreate = () => { discordSdk.subscribe('ENTITLEMENT_CREATE', handleEntitlementCreate); ``` -You can also subscribe to the `ENTITLEMENT_CREATE` event using the [Gateway API](#DOCS_TOPICS_GATEWAY_EVENTS/entitlements) to receive the event in your app's backend or use the [List Entitlements](#DOCS_RESOURCES_ENTITLEMENT/list-entitlements) HTTP API endpoint to fetch a user's entitlements. +You can also subscribe to the `ENTITLEMENT_CREATE` event using the [Gateway API](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements) to receive the event in your app's backend or use the [List Entitlements](#DOCS_RESOURCES_ENTITLEMENT/list-entitlements) HTTP API endpoint to fetch a user's entitlements. --- diff --git a/docs/monetization/Implementing_One-Time_Purchases.md b/docs/monetization/Implementing_One-Time_Purchases.md index a422387a59..3b7e40d769 100644 --- a/docs/monetization/Implementing_One-Time_Purchases.md +++ b/docs/monetization/Implementing_One-Time_Purchases.md @@ -38,11 +38,11 @@ When creating items for one-time purchase, you can choose between durable and co When a user purchases a one-time purchase SKU, an entitlement is created. [Entitlements](#DOCS_RESOURCES_ENTITLEMENT) represent the user's access to your consumable or durable item. -Depending on your app's features, you can use a combination of [Gateway events](#DOCS_TOPICS_GATEWAY_EVENTS/entitlements), the [Entitlement HTTP API](#DOCS_RESOURCES_ENTITLEMENT), and [interaction payloads](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING) to keep track of entitlements to users who have purchased items in your app. +Depending on your app's features, you can use a combination of [Gateway events](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements), the [Entitlement HTTP API](#DOCS_RESOURCES_ENTITLEMENT), and [interaction payloads](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING) to keep track of entitlements to users who have purchased items in your app. ### Accessing Entitlements with Gateway Events -When a user purchases a SKU, Discord will emit an [`ENTITLEMENT_CREATE`](#DOCS_TOPICS_GATEWAY_EVENTS/entitlements) event. This event will contain the entitlement object that represents the user's access to the SKU. You can use this event to keep track of the user's entitlements in near-time. For One-Time Purchases, you may also receive an `ENTITLEMENT_DELETE` event if the user's entitlement is revoked. +When a user purchases a SKU, Discord will emit an [`ENTITLEMENT_CREATE`](#DOCS_EVENTS_GATEWAY_EVENTS/entitlements) event. This event will contain the entitlement object that represents the user's access to the SKU. You can use this event to keep track of the user's entitlements in near-time. For One-Time Purchases, you may also receive an `ENTITLEMENT_DELETE` event if the user's entitlement is revoked. ### Accessing Entitlements with the HTTP API diff --git a/docs/quick_start/Getting_Started.mdx b/docs/quick_start/Getting_Started.mdx index 8e88867aad..8dd006d7ba 100644 --- a/docs/quick_start/Getting_Started.mdx +++ b/docs/quick_start/Getting_Started.mdx @@ -115,14 +115,14 @@ Now that you have the credentials you need, lets configure your bot user and ins Newly-created apps have a bot user enabled by default. Bot users allow your app to appear and behave similarly to other server members when it's [installed to a server](#DOCS_QUICK_START_OVERVIEW_OF_APPS/where-are-apps-installed). -On the left hand sidebar in your app's settings, there's a **Bot** page (where we fetched the token from). On this page, you can also configure settings like its [privileged intents](#DOCS_TOPICS_GATEWAY/privileged-intents) or whether it can be installed by other users. +On the left hand sidebar in your app's settings, there's a **Bot** page (where we fetched the token from). On this page, you can also configure settings like its [privileged intents](#DOCS_EVENTS_GATEWAY/privileged-intents) or whether it can be installed by other users. -Intents determine which events Discord will send your app when you're creating a [Gateway API connection](#DOCS_TOPICS_GATEWAY). For example, if you want your app to perform an action when users add a reaction to a message, you can pass the `GUILD_MESSAGE_REACTIONS` (`1 << 10`) intent. +Intents determine which events Discord will send your app when you're creating a [Gateway API connection](#DOCS_EVENTS_GATEWAY). For example, if you want your app to perform an action when users add a reaction to a message, you can pass the `GUILD_MESSAGE_REACTIONS` (`1 << 10`) intent. -Some intents are [privileged](#DOCS_TOPICS_GATEWAY/privileged-intents), meaning they allow your app to access data that may be considered sensitive (like the contents of messages). Privileged intents can be toggled on the **Bot** page in your app's settings, but they must be approved before you [verify your app](https://support-dev.discord.com/hc/en-us/articles/23926564536471-How-Do-I-Get-My-App-Verified). Standard, non-privileged intents don't require any additional permissions or configurations. +Some intents are [privileged](#DOCS_EVENTS_GATEWAY/privileged-intents), meaning they allow your app to access data that may be considered sensitive (like the contents of messages). Privileged intents can be toggled on the **Bot** page in your app's settings, but they must be approved before you [verify your app](https://support-dev.discord.com/hc/en-us/articles/23926564536471-How-Do-I-Get-My-App-Verified). Standard, non-privileged intents don't require any additional permissions or configurations. -More information about intents and a full list of available intents (along with their associated events) is in the [Gateway documentation](#DOCS_TOPICS_GATEWAY/gateway-intents). +More information about intents and a full list of available intents (along with their associated events) is in the [Gateway documentation](#DOCS_EVENTS_GATEWAY/gateway-intents). For now, we don't need to configure anything additional here, but you may need to in the future depending on your app's use case. Let's go ahead and get our app ready for installation. @@ -221,7 +221,7 @@ If you navigate back to your server, you should see the slash commands appear. B Apps have access to [APIs](#DOCS_QUICK_START_OVERVIEW_OF_APPS/what-apis-can-apps-use) that you can mix-and-match to build apps: - **[HTTP API](#DOCS_REFERENCE/http-api)** is a REST-like API for general operations like sending and updating data in Discord, or fetching data about a resource. -- **[Gateway API](#DOCS_REFERENCE/gateway-websocket-api)** is a WebSocket-based API that is helpful for maintaining state or listening to events happening in a Discord server. We won't be using it in this guide, but more information about how to create a Gateway connection and the different events you can listen to are in the [Gateway documentation](#DOCS_TOPICS_GATEWAY). +- **[Gateway API](#DOCS_REFERENCE/gateway-websocket-api)** is a WebSocket-based API that is helpful for maintaining state or listening to events happening in a Discord server. We won't be using it in this guide, but more information about how to create a Gateway connection and the different events you can listen to are in the [Gateway documentation](#DOCS_EVENTS_GATEWAY). --- diff --git a/docs/quick_start/Overview_of_Apps.mdx b/docs/quick_start/Overview_of_Apps.mdx index 6380965d79..e07337e393 100644 --- a/docs/quick_start/Overview_of_Apps.mdx +++ b/docs/quick_start/Overview_of_Apps.mdx @@ -77,7 +77,7 @@ Read details about using the HTTP API in the [API reference](#DOCS_REFERENCE/htt ### Gateway API -The **Gateway API** lets you receive event data over a WebSocket anytime an [event](#DOCS_TOPICS_GATEWAY_EVENTS) occurs in a server where your app is installed. +The **Gateway API** lets you receive event data over a WebSocket anytime an [event](#DOCS_EVENTS_GATEWAY_EVENTS) occurs in a server where your app is installed. Use the Gateway API to: - Receive events happening in Discord diff --git a/docs/resources/Application.md b/docs/resources/Application.md index fc3117ab53..483d3f6716 100644 --- a/docs/resources/Application.md +++ b/docs/resources/Application.md @@ -36,6 +36,9 @@ sidebar_label: Application | redirect_uris? | array of strings | Array of redirect URIs for the app | | interactions_endpoint_url? | ?string | [Interactions endpoint URL](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/receiving-an-interaction) for the app | | role_connections_verification_url? | ?string | Role connection verification URL for the app | +| event_webhooks_url? | ?string | [Event webhooks URL](#DOCS_EVENTS_WEBHOOK_EVENTS/preparing-for-events) for the app to receive webhook events | +| event_webhooks_status | [application event webhook status](#DOCS_RESOURCES_APPLICATION/application-object-application-event-webhook-status) | If [webhook events](#DOCS_EVENTS_WEBHOOK_EVENTS) are enabled for the app. `1` (default) means disabled, `2` means enabled, and `3` means disabled by Discord | +| event_webhooks_types? | array of strings | List of [Webhook event types](#DOCS_EVENTS_WEBHOOK_EVENTS/event-types) the app subscribes to | | tags? | array of strings | List of tags describing the content and functionality of the app. Max of 5 tags. | | install_params? | [install params](#DOCS_RESOURCES_APPLICATION/install-params-object) object | Settings for the app's default in-app authorization link, if enabled | | integration_types_config? | dictionary with keys of [application integration types](#DOCS_RESOURCES_APPLICATION/application-object-application-integration-types) | Default scopes and permissions for each supported installation context. Value for each key is an [integration type configuration object](#DOCS_RESOURCES_APPLICATION/application-object-application-integration-type-configuration-object) | @@ -74,6 +77,8 @@ sidebar_label: Application "name": "Baba O-Riley", "interactions_endpoint_url": null, "role_connections_verification_url": null, + "event_webhooks_url": null, + "event_webhooks_status": 1, "owner": { "avatar": null, "discriminator": "1738", @@ -119,15 +124,25 @@ Where an app can be installed, also called its supported [installation contexts] |------------------------|----------------------------------------------------------------------------|----------------------------------------------------------------------------------| | oauth2_install_params? | [install params object](#DOCS_RESOURCES_APPLICATION/install-params-object) | Install params for each installation context's default in-app authorization link | +###### Application Event Webhook Status + +Status indicating whether event webhooks are enabled or disabled for an application. + +| Name | Value | Description | +|-----------------------|-------|------------------------------------------------------------------| +| `DISABLED` | `1` | Webhook events are disabled by developer | +| `ENABLED` | `2` | Webhook events are enabled by developer | +| `DISABLED_BY_DISCORD` | `3` | Webhook events are disabled by Discord, usually do to inactivity | + ###### Application Flags | Value | Name | Description | |-----------|-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `1 << 6` | APPLICATION_AUTO_MODERATION_RULE_CREATE_BADGE | Indicates if an app uses the [Auto Moderation API](#DOCS_RESOURCES_AUTO_MODERATION) | -| `1 << 12` | GATEWAY_PRESENCE | Intent required for bots in **100 or more servers** to receive [`presence_update` events](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update) | -| `1 << 13` | GATEWAY_PRESENCE_LIMITED | Intent required for bots in under 100 servers to receive [`presence_update` events](#DOCS_TOPICS_GATEWAY_EVENTS/presence-update), found on the **Bot** page in your app's settings | -| `1 << 14` | GATEWAY_GUILD_MEMBERS | Intent required for bots in **100 or more servers** to receive member-related events like `guild_member_add`. See the list of member-related events [under `GUILD_MEMBERS`](#DOCS_TOPICS_GATEWAY/list-of-intents) | -| `1 << 15` | GATEWAY_GUILD_MEMBERS_LIMITED | Intent required for bots in under 100 servers to receive member-related events like `guild_member_add`, found on the **Bot** page in your app's settings. See the list of member-related events [under `GUILD_MEMBERS`](#DOCS_TOPICS_GATEWAY/list-of-intents) | +| `1 << 12` | GATEWAY_PRESENCE | Intent required for bots in **100 or more servers** to receive [`presence_update` events](#DOCS_EVENTS_GATEWAY_EVENTS/presence-update) | +| `1 << 13` | GATEWAY_PRESENCE_LIMITED | Intent required for bots in under 100 servers to receive [`presence_update` events](#DOCS_EVENTS_GATEWAY_EVENTS/presence-update), found on the **Bot** page in your app's settings | +| `1 << 14` | GATEWAY_GUILD_MEMBERS | Intent required for bots in **100 or more servers** to receive member-related events like `guild_member_add`. See the list of member-related events [under `GUILD_MEMBERS`](#DOCS_EVENTS_GATEWAY/list-of-intents) | +| `1 << 15` | GATEWAY_GUILD_MEMBERS_LIMITED | Intent required for bots in under 100 servers to receive member-related events like `guild_member_add`, found on the **Bot** page in your app's settings. See the list of member-related events [under `GUILD_MEMBERS`](#DOCS_EVENTS_GATEWAY/list-of-intents) | | `1 << 16` | VERIFICATION_PENDING_GUILD_LIMIT | Indicates unusual growth of an app that prevents verification | | `1 << 17` | EMBEDDED | Indicates if an app is embedded within the Discord client (currently unavailable publicly) | | `1 << 18` | GATEWAY_MESSAGE_CONTENT | Intent required for bots in **100 or more servers** to receive [message content](https://support-dev.discord.com/hc/en-us/articles/4404772028055) | @@ -233,6 +248,9 @@ Edit properties of the app associated with the requesting bot user. Only propert | cover_image | ?[image data](#DOCS_REFERENCE/image-data) | Default rich presence invite cover image for the app | | interactions_endpoint_url \*\* | string | [Interactions endpoint URL](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/receiving-an-interaction) for the app | | tags | array of strings | List of tags describing the content and functionality of the app (max of 20 characters per tag). Max of 5 tags. | +| event_webhooks_url | string | [Event webhooks URL](#DOCS_EVENTS_WEBHOOK_EVENTS/preparing-for-events) for the app to receive webhook events | +| event_webhooks_status | [application event webhook status](#DOCS_RESOURCES_APPLICATION/application-object-application-event-webhook-status) | If [webhook events](#DOCS_EVENTS_WEBHOOK_EVENTS) are enabled for the app. `1` to disable, and `2` to enable | +| event_webhooks_types | array of strings | List of [Webhook event types](#DOCS_EVENTS_WEBHOOK_EVENTS/event-types) to subscribe to | \* Only limited intent flags (`GATEWAY_PRESENCE_LIMITED`, `GATEWAY_GUILD_MEMBERS_LIMITED`, and `GATEWAY_MESSAGE_CONTENT_LIMITED`) can be updated via the API. @@ -267,8 +285,8 @@ Returns a serialized activity instance, if it exists. Useful for [preventing unw | application_id | snowflake | [Application](#DOCS_RESOURCES_APPLICATION/application-object) ID | | instance_id | string | Activity [Instance](#DOCS_ACTIVITIES_DEVELOPMENT_GUIDES/activity-instance-management) ID | | launch_id | snowflake | Unique identifier for the launch | -| location | [Activity Location](#DOCS_RESOURCES_APPLICATION/get-application-activity-instance-activity-location-object) | The Location the instance is runnning in | -| users | array of snowflakes, [user](#DOCS_RESOURCES_USER/user-object) ids | The IDs of the Users currently connected to the instance | +| location | [Activity Location](#DOCS_RESOURCES_APPLICATION/get-application-activity-instance-activity-location-object) | Location the instance is runnning in | +| users | array of snowflakes, [user](#DOCS_RESOURCES_USER/user-object) IDs | IDs of the Users currently connected to the instance | @@ -276,16 +294,16 @@ Returns a serialized activity instance, if it exists. Useful for [preventing unw The Activity Location is an object that describes the location in which an activity instance is running. -| Field | Type | Description | -|------------|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| -| id | string | The unique identifier for the location | -| kind | [Activity Location Kind Enum](#DOCS_RESOURCES_APPLICATION/get-application-activity-instance-activity-location-kind-enum) | Enum describing kind of location | -| channel_id | snowflake | The id of the [Channel](#DOCS_RESOURCES_CHANNEL/channel-object) | -| guild_id? | ?snowflake | The id of the [Guild](#DOCS_RESOURCES_GUILD/guild-object) | +| Field | Type | Description | +|------------|--------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------| +| id | string | Unique identifier for the location | +| kind | [Activity Location Kind Enum](#DOCS_RESOURCES_APPLICATION/get-application-activity-instance-activity-location-kind-enum) | Enum describing kind of location | +| channel_id | snowflake | ID of the [Channel](#DOCS_RESOURCES_CHANNEL/channel-object) | +| guild_id? | ?snowflake | ID of the [Guild](#DOCS_RESOURCES_GUILD/guild-object) | ###### Activity Location Kind Enum -| Enum | Description | -|------|--------------------------------------------------------| -| 'gc' | The Location is a Guild Channel | -| 'pc' | The Location is a Private Channel, such as a DM or GDM | \ No newline at end of file +| Enum | Description | +|------|----------------------------------------------------| +| 'gc' | Location is a Guild Channel | +| 'pc' | Location is a Private Channel, such as a DM or GDM | \ No newline at end of file diff --git a/docs/resources/Auto_Moderation.md b/docs/resources/Auto_Moderation.md index 1eb525fb40..35352cc54c 100644 --- a/docs/resources/Auto_Moderation.md +++ b/docs/resources/Auto_Moderation.md @@ -214,7 +214,7 @@ Get a single rule. Returns an [auto moderation rule](#DOCS_RESOURCES_AUTO_MODERA ## Create Auto Moderation Rule % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/auto-moderation/rules -Create a new rule. Returns an [auto moderation rule](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object) on success. Fires an [Auto Moderation Rule Create](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-create) Gateway event. +Create a new rule. Returns an [auto moderation rule](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object) on success. Fires an [Auto Moderation Rule Create](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-create) Gateway event. > info > This endpoint requires the `MANAGE_GUILD` [permission](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-permission-requirements). @@ -243,7 +243,7 @@ Create a new rule. Returns an [auto moderation rule](#DOCS_RESOURCES_AUTO_MODERA ## Modify Auto Moderation Rule % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/auto-moderation/rules/{auto_moderation_rule.id#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object} -Modify an existing rule. Returns an [auto moderation rule](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object) on success. Fires an [Auto Moderation Rule Update](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-update) Gateway event. +Modify an existing rule. Returns an [auto moderation rule](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object) on success. Fires an [Auto Moderation Rule Update](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-update) Gateway event. > info > Requires `MANAGE_GUILD` [permissions](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-permission-requirements). @@ -270,7 +270,7 @@ Modify an existing rule. Returns an [auto moderation rule](#DOCS_RESOURCES_AUTO_ ## Delete Auto Moderation Rule % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/auto-moderation/rules/{auto_moderation_rule.id#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-rule-object} -Delete a rule. Returns a `204` on success. Fires an [Auto Moderation Rule Delete](#DOCS_TOPICS_GATEWAY_EVENTS/auto-moderation-rule-delete) Gateway event. +Delete a rule. Returns a `204` on success. Fires an [Auto Moderation Rule Delete](#DOCS_EVENTS_GATEWAY_EVENTS/auto-moderation-rule-delete) Gateway event. > info > This endpoint requires the `MANAGE_GUILD` [permission](#DOCS_RESOURCES_AUTO_MODERATION/auto-moderation-permission-requirements). diff --git a/docs/resources/Channel.md b/docs/resources/Channel.md index 0112eeb529..fd0ae71f7b 100644 --- a/docs/resources/Channel.md +++ b/docs/resources/Channel.md @@ -228,7 +228,7 @@ Bots can post or publish messages in this type of channel if they have the prope [Threads](#DOCS_TOPICS_THREADS) can be either `archived` or `active`. Archived threads are generally immutable. To send a message or add a reaction, a thread must first be unarchived. The API will helpfully automatically unarchive a thread when sending a message in that thread. -Unlike with channels, the API will only sync updates to users about threads the current user can view. When receiving a [guild create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) payload, the API will only include active threads the current user can view. Threads inside of private channels are completely private to the members of that private channel. As such, when _gaining_ access to a channel the API sends a [thread list sync](#DOCS_TOPICS_GATEWAY_EVENTS/thread-list-sync), which includes all active threads in that channel. +Unlike with channels, the API will only sync updates to users about threads the current user can view. When receiving a [guild create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) payload, the API will only include active threads the current user can view. Threads inside of private channels are completely private to the members of that private channel. As such, when _gaining_ access to a channel the API sends a [thread list sync](#DOCS_EVENTS_GATEWAY_EVENTS/thread-list-sync), which includes all active threads in that channel. Threads also track membership. Users must be added to a thread before sending messages in them. The API will helpfully automatically add users to a thread when sending a message in that thread. @@ -309,7 +309,7 @@ A thread member object contains information about a user that has joined a threa | flags | integer | Any user-thread settings, currently only used for notifications | | member? \* \*\* | [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object | Additional information about the user | -\* These fields are omitted on the member sent within each thread in the [GUILD_CREATE](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) event. +\* These fields are omitted on the member sent within each thread in the [GUILD_CREATE](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) event. \*\* The `member` field is only present when `with_member` is set to `true` when calling [List Thread Members](#DOCS_RESOURCES_CHANNEL/list-thread-members) or [Get Thread Member](#DOCS_RESOURCES_CHANNEL/get-thread-member). @@ -356,7 +356,7 @@ Update a channel's settings. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel ###### JSON Params (Group DM) -Fires a [Channel Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-update) Gateway event. +Fires a [Channel Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-update) Gateway event. | Field | Type | Description | |-------|--------|------------------------------| @@ -365,7 +365,7 @@ Fires a [Channel Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-update) Gateway eve ###### JSON Params (Guild channel) -Requires the `MANAGE_CHANNELS` permission for the guild. Fires a [Channel Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-update) Gateway event. If modifying a category, individual [Channel Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-update) events will fire for each child channel that also changes. If modifying permission overwrites, the `MANAGE_ROLES` permission is required. Only permissions your bot has in the guild or parent channel (if applicable) can be allowed/denied (unless your bot has a `MANAGE_ROLES` overwrite in the channel). +Requires the `MANAGE_CHANNELS` permission for the guild. Fires a [Channel Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-update) Gateway event. If modifying a category, individual [Channel Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-update) events will fire for each child channel that also changes. If modifying permission overwrites, the `MANAGE_ROLES` permission is required. Only permissions your bot has in the guild or parent channel (if applicable) can be allowed/denied (unless your bot has a `MANAGE_ROLES` overwrite in the channel). | Field | Type | Description | Channel Type | |-------------------------------------|---------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------| @@ -397,7 +397,7 @@ Requires the `MANAGE_CHANNELS` permission for the guild. Fires a [Channel Update When setting `archived` to `false`, when `locked` is also `false`, only the `SEND_MESSAGES` permission is required. -Otherwise, requires the `MANAGE_THREADS` permission. Fires a [Thread Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-update) Gateway event. Requires the thread to have `archived` set to `false` or be set to `false` in the request. +Otherwise, requires the `MANAGE_THREADS` permission. Fires a [Thread Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-update) Gateway event. Requires the thread to have `archived` set to `false` or be set to `false` in the request. | Field | Type | Description | |-----------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -412,7 +412,7 @@ Otherwise, requires the `MANAGE_THREADS` permission. Fires a [Thread Update](#DO ## Delete/Close Channel % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object} -Delete a channel, or close a private message. Requires the `MANAGE_CHANNELS` permission for the guild, or `MANAGE_THREADS` if the channel is a thread. Deleting a category does not delete its child channels; they will have their `parent_id` removed and a [Channel Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-update) Gateway event will fire for each of them. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) object on success. Fires a [Channel Delete](#DOCS_TOPICS_GATEWAY_EVENTS/channel-delete) Gateway event (or [Thread Delete](#DOCS_TOPICS_GATEWAY_EVENTS/thread-delete) if the channel was a thread). +Delete a channel, or close a private message. Requires the `MANAGE_CHANNELS` permission for the guild, or `MANAGE_THREADS` if the channel is a thread. Deleting a category does not delete its child channels; they will have their `parent_id` removed and a [Channel Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-update) Gateway event will fire for each of them. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) object on success. Fires a [Channel Delete](#DOCS_EVENTS_GATEWAY_EVENTS/channel-delete) Gateway event (or [Thread Delete](#DOCS_EVENTS_GATEWAY_EVENTS/thread-delete) if the channel was a thread). > warn > Deleting a guild channel cannot be undone. Use this with caution, as it is impossible to undo this action when performed on a guild channel. In contrast, when used with a private message, it is possible to undo the action by opening a private message with the recipient again. @@ -425,7 +425,7 @@ Delete a channel, or close a private message. Requires the `MANAGE_CHANNELS` per ## Edit Channel Permissions % PUT /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/permissions/{overwrite.id#DOCS_RESOURCES_CHANNEL/overwrite-object} -Edit the channel permission overwrites for a user or role in a channel. Only usable for guild channels. Requires the `MANAGE_ROLES` permission. Only permissions your bot has in the guild or parent channel (if applicable) can be allowed/denied (unless your bot has a `MANAGE_ROLES` overwrite in the channel). Returns a 204 empty response on success. Fires a [Channel Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-update) Gateway event. For more information about permissions, see [permissions](#DOCS_TOPICS_PERMISSIONS/permissions). +Edit the channel permission overwrites for a user or role in a channel. Only usable for guild channels. Requires the `MANAGE_ROLES` permission. Only permissions your bot has in the guild or parent channel (if applicable) can be allowed/denied (unless your bot has a `MANAGE_ROLES` overwrite in the channel). Returns a 204 empty response on success. Fires a [Channel Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-update) Gateway event. For more information about permissions, see [permissions](#DOCS_TOPICS_PERMISSIONS/permissions). > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -444,7 +444,7 @@ Returns a list of [invite](#DOCS_RESOURCES_INVITE/invite-object) objects (with [ ## Create Channel Invite % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/invites -Create a new [invite](#DOCS_RESOURCES_INVITE/invite-object) object for the channel. Only usable for guild channels. Requires the `CREATE_INSTANT_INVITE` permission. All JSON parameters for this route are optional, however the request body is not. If you are not sending any fields, you still have to send an empty JSON object (`{}`). Returns an [invite](#DOCS_RESOURCES_INVITE/invite-object) object. Fires an [Invite Create](#DOCS_TOPICS_GATEWAY_EVENTS/invite-create) Gateway event. +Create a new [invite](#DOCS_RESOURCES_INVITE/invite-object) object for the channel. Only usable for guild channels. Requires the `CREATE_INSTANT_INVITE` permission. All JSON parameters for this route are optional, however the request body is not. If you are not sending any fields, you still have to send an empty JSON object (`{}`). Returns an [invite](#DOCS_RESOURCES_INVITE/invite-object) object. Fires an [Invite Create](#DOCS_EVENTS_GATEWAY_EVENTS/invite-create) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -463,14 +463,14 @@ Create a new [invite](#DOCS_RESOURCES_INVITE/invite-object) object for the chann ## Delete Channel Permission % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/permissions/{overwrite.id#DOCS_RESOURCES_CHANNEL/overwrite-object} -Delete a channel permission overwrite for a user or role in a channel. Only usable for guild channels. Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Channel Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-update) Gateway event. For more information about permissions, see [permissions](#DOCS_TOPICS_PERMISSIONS/permissions) +Delete a channel permission overwrite for a user or role in a channel. Only usable for guild channels. Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Channel Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-update) Gateway event. For more information about permissions, see [permissions](#DOCS_TOPICS_PERMISSIONS/permissions) > info > This endpoint supports the `X-Audit-Log-Reason` header. ## Follow Announcement Channel % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/followers -Follow an Announcement Channel to send messages to a target channel. Requires the `MANAGE_WEBHOOKS` permission in the target channel. Returns a [followed channel](#DOCS_RESOURCES_CHANNEL/followed-channel-object) object. Fires a [Webhooks Update](#DOCS_TOPICS_GATEWAY_EVENTS/webhooks-update) Gateway event for the target channel. +Follow an Announcement Channel to send messages to a target channel. Requires the `MANAGE_WEBHOOKS` permission in the target channel. Returns a [followed channel](#DOCS_RESOURCES_CHANNEL/followed-channel-object) object. Fires a [Webhooks Update](#DOCS_EVENTS_GATEWAY_EVENTS/webhooks-update) Gateway event for the target channel. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -483,7 +483,7 @@ Follow an Announcement Channel to send messages to a target channel. Requires th ## Trigger Typing Indicator % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/typing -Post a typing indicator for the specified channel, which expires after 10 seconds. Returns a 204 empty response on success. Fires a [Typing Start](#DOCS_TOPICS_GATEWAY_EVENTS/typing-start) Gateway event. +Post a typing indicator for the specified channel, which expires after 10 seconds. Returns a 204 empty response on success. Fires a [Typing Start](#DOCS_EVENTS_GATEWAY_EVENTS/typing-start) Gateway event. Generally bots should **not** use this route. However, if a bot is responding to a command and expects the computation to take a few seconds, this endpoint may be called to let the user know that the bot is processing their message. @@ -493,7 +493,7 @@ Returns all pinned messages in the channel as an array of [message](#DOCS_RESOUR ## Pin Message % PUT /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/pins/{message.id#DOCS_RESOURCES_MESSAGE/message-object} -Pin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-pins-update) Gateway event. +Pin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-pins-update) Gateway event. > warn > The max pinned messages is 50. @@ -503,7 +503,7 @@ Pin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a ## Unpin Message % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/pins/{message.id#DOCS_RESOURCES_MESSAGE/message-object} -Unpin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-pins-update) Gateway event. +Unpin a message in a channel. Requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Channel Pins Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-pins-update) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -525,7 +525,7 @@ Removes a recipient from a Group DM. ## Start Thread from Message % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_MESSAGE/message-object}/threads -Creates a new thread from an existing message. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) and a [Message Update](#DOCS_TOPICS_GATEWAY_EVENTS/message-update) Gateway event. +Creates a new thread from an existing message. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create) and a [Message Update](#DOCS_EVENTS_GATEWAY_EVENTS/message-update) Gateway event. When called on a `GUILD_TEXT` channel, creates a `PUBLIC_THREAD`. When called on a `GUILD_ANNOUNCEMENT` channel, creates a `ANNOUNCEMENT_THREAD`. Does not work on a [`GUILD_FORUM`](#DOCS_RESOURCES_CHANNEL/start-thread-in-forum-or-media-channel) or a `GUILD_MEDIA` channel. The id of the created thread will be the same as the id of the source message, and as such a message can only have a single thread created from it. @@ -542,7 +542,7 @@ When called on a `GUILD_TEXT` channel, creates a `PUBLIC_THREAD`. When called on ## Start Thread without Message % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/threads -Creates a new thread that is not connected to an existing message. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) Gateway event. +Creates a new thread that is not connected to an existing message. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object) on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -561,7 +561,7 @@ Creates a new thread that is not connected to an existing message. Returns a [ch ## Start Thread in Forum or Media Channel % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/threads -Creates a new thread in a forum or a media channel, and sends a message within the created thread. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object), with a nested [message](#DOCS_RESOURCES_MESSAGE/message-object) object, on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) and [Message Create](#DOCS_TOPICS_GATEWAY_EVENTS/message-create) Gateway event. +Creates a new thread in a forum or a media channel, and sends a message within the created thread. Returns a [channel](#DOCS_RESOURCES_CHANNEL/channel-object), with a nested [message](#DOCS_RESOURCES_MESSAGE/message-object) object, on success, and a 400 BAD REQUEST on invalid parameters. Fires a [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create) and [Message Create](#DOCS_EVENTS_GATEWAY_EVENTS/message-create) Gateway event. - The type of the created thread is `PUBLIC_THREAD`. - See [message formatting](#DOCS_REFERENCE/message-formatting) for more information on how to properly format messages. @@ -610,19 +610,19 @@ Creates a new thread in a forum or a media channel, and sends a message within t ## Join Thread % PUT /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/thread-members/@me -Adds the current user to a thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a [Thread Members Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-members-update) and a [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) Gateway event. +Adds the current user to a thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a [Thread Members Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-members-update) and a [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create) Gateway event. ## Add Thread Member % PUT /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/thread-members/{user.id#DOCS_RESOURCES_USER/user-object} -Adds another member to a thread. Requires the ability to send messages in the thread. Also requires the thread is not archived. Returns a 204 empty response if the member is successfully added or was already a member of the thread. Fires a [Thread Members Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-members-update) Gateway event. +Adds another member to a thread. Requires the ability to send messages in the thread. Also requires the thread is not archived. Returns a 204 empty response if the member is successfully added or was already a member of the thread. Fires a [Thread Members Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-members-update) Gateway event. ## Leave Thread % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/thread-members/@me -Removes the current user from a thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a [Thread Members Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-members-update) Gateway event. +Removes the current user from a thread. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a [Thread Members Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-members-update) Gateway event. ## Remove Thread Member % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/thread-members/{user.id#DOCS_RESOURCES_USER/user-object} -Removes another member from a thread. Requires the `MANAGE_THREADS` permission, or the creator of the thread if it is a `PRIVATE_THREAD`. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a [Thread Members Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-members-update) Gateway event. +Removes another member from a thread. Requires the `MANAGE_THREADS` permission, or the creator of the thread if it is a `PRIVATE_THREAD`. Also requires the thread is not archived. Returns a 204 empty response on success. Fires a [Thread Members Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-members-update) Gateway event. ## Get Thread Member % GET /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/thread-members/{user.id#DOCS_RESOURCES_USER/user-object} @@ -646,7 +646,7 @@ Returns array of [thread members](#DOCS_RESOURCES_CHANNEL/thread-member-object) When `with_member` is set to `true`, the results will be paginated and each thread member object will include a `member` field containing a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object. > warn -> This endpoint is restricted according to whether the `GUILD_MEMBERS` [Privileged Intent](#DOCS_TOPICS_GATEWAY/privileged-intents) is enabled for your application. +> This endpoint is restricted according to whether the `GUILD_MEMBERS` [Privileged Intent](#DOCS_EVENTS_GATEWAY/privileged-intents) is enabled for your application. ###### Query String Params diff --git a/docs/resources/Emoji.md b/docs/resources/Emoji.md index 80f3a22dda..94f50d4d94 100644 --- a/docs/resources/Emoji.md +++ b/docs/resources/Emoji.md @@ -98,7 +98,7 @@ Returns an [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object for the given guil ## Create Guild Emoji % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis -Create a new emoji for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-emojis-update) Gateway event. +Create a new emoji for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-emojis-update) Gateway event. > warn > Emojis and animated emojis have a maximum file size of 256 KiB. Attempting to upload an emoji larger than this limit will fail and return 400 Bad Request and an error message, but not a [JSON status code](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/json). @@ -116,7 +116,7 @@ Create a new emoji for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permis ## Modify Guild Emoji % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis/{emoji.id#DOCS_RESOURCES_EMOJI/emoji-object} -Modify the given emoji. For emojis created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other emojis, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-emojis-update) Gateway event. +Modify the given emoji. For emojis created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other emojis, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) object on success. Fires a [Guild Emojis Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-emojis-update) Gateway event. > info > All parameters to this endpoint are optional. @@ -133,7 +133,7 @@ Modify the given emoji. For emojis created by the current user, requires either ## Delete Guild Emoji % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/emojis/{emoji.id#DOCS_RESOURCES_EMOJI/emoji-object} -Delete the given emoji. For emojis created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other emojis, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Emojis Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-emojis-update) Gateway event. +Delete the given emoji. For emojis created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other emojis, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Emojis Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-emojis-update) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. diff --git a/docs/resources/Guild.md b/docs/resources/Guild.md index f96c717e98..49d92a57c9 100644 --- a/docs/resources/Guild.md +++ b/docs/resources/Guild.md @@ -11,7 +11,7 @@ Guilds in Discord represent an isolated collection of users and channels, and ar ###### Guild Structure > info -> Fields specific to the `GUILD_CREATE` event are listed in the [Gateway Events documentation](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create). +> Fields specific to the `GUILD_CREATE` event are listed in the [Gateway Events documentation](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create). | Field | Type | Description | |--------------------------------|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -220,7 +220,7 @@ Guilds in Discord represent an isolated collection of users and channels, and ar ### Unavailable Guild Object -A partial [guild](#DOCS_RESOURCES_GUILD/guild-object) object. Represents an Offline Guild, or a Guild whose information has not been provided through [Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) events during the Gateway connect. +A partial [guild](#DOCS_RESOURCES_GUILD/guild-object) object. Represents an Offline Guild, or a Guild whose information has not been provided through [Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) events during the Gateway connect. ###### Example Unavailable Guild @@ -659,14 +659,14 @@ Defines the criteria used to satisfy Onboarding constraints that are required fo ### Membership Screening Object -In guilds with [Membership Screening](https://support.discord.com/hc/en-us/articles/1500000466882) enabled, when a member joins, [Guild Member Add](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-add) will be emitted but they will initially be restricted from doing any actions in the guild, and `pending` will be true in the [member object](#DOCS_RESOURCES_GUILD/guild-member-object). When the member completes the screening, [Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update) will be emitted and `pending` will be false. +In guilds with [Membership Screening](https://support.discord.com/hc/en-us/articles/1500000466882) enabled, when a member joins, [Guild Member Add](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-add) will be emitted but they will initially be restricted from doing any actions in the guild, and `pending` will be true in the [member object](#DOCS_RESOURCES_GUILD/guild-member-object). When the member completes the screening, [Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update) will be emitted and `pending` will be false. > warn > We are making significant changes to the Membership Screening API specifically related to getting and editing the Membership Screening object. Long story short is that it can be improved. As such, we have removed those documentation. There will **not be** any changes to how pending members work, as outlined above. That behavior will stay the same. ## Create Guild % POST /guilds -Create a new guild. Returns a [guild](#DOCS_RESOURCES_GUILD/guild-object) object on success. Fires a [Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) Gateway event. +Create a new guild. Returns a [guild](#DOCS_RESOURCES_GUILD/guild-object) object on success. Fires a [Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) Gateway event. > warn > This endpoint can be used only by bots in less than 10 guilds. @@ -816,7 +816,7 @@ If the user is not in the guild, then the guild must be [discoverable](#DOCS_RES ## Modify Guild % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object} -Modify a guild's settings. Requires the `MANAGE_GUILD` permission. Returns the updated [guild](#DOCS_RESOURCES_GUILD/guild-object) object on success. Fires a [Guild Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-update) Gateway event. +Modify a guild's settings. Requires the `MANAGE_GUILD` permission. Returns the updated [guild](#DOCS_RESOURCES_GUILD/guild-object) object on success. Fires a [Guild Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-update) Gateway event. > info > All parameters to this endpoint are optional @@ -855,7 +855,7 @@ Modify a guild's settings. Requires the `MANAGE_GUILD` permission. Returns the u ## Delete Guild % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object} -Delete a guild permanently. User must be owner. Returns `204 No Content` on success. Fires a [Guild Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-delete) Gateway event. +Delete a guild permanently. User must be owner. Returns `204 No Content` on success. Fires a [Guild Delete](#DOCS_EVENTS_GATEWAY_EVENTS/guild-delete) Gateway event. ## Get Guild Channels % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/channels @@ -863,7 +863,7 @@ Returns a list of guild [channel](#DOCS_RESOURCES_CHANNEL/channel-object) object ## Create Guild Channel % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/channels -Create a new [channel](#DOCS_RESOURCES_CHANNEL/channel-object) object for the guild. Requires the `MANAGE_CHANNELS` permission. If setting permission overwrites, only permissions your bot has in the guild can be allowed/denied. Setting `MANAGE_ROLES` permission in channels is only possible for guild administrators. Returns the new [channel](#DOCS_RESOURCES_CHANNEL/channel-object) object on success. Fires a [Channel Create](#DOCS_TOPICS_GATEWAY_EVENTS/channel-create) Gateway event. +Create a new [channel](#DOCS_RESOURCES_CHANNEL/channel-object) object for the guild. Requires the `MANAGE_CHANNELS` permission. If setting permission overwrites, only permissions your bot has in the guild can be allowed/denied. Setting `MANAGE_ROLES` permission in channels is only possible for guild administrators. Returns the new [channel](#DOCS_RESOURCES_CHANNEL/channel-object) object on success. Fires a [Channel Create](#DOCS_EVENTS_GATEWAY_EVENTS/channel-create) Gateway event. > info > All parameters to this endpoint are optional and nullable excluding `name` @@ -900,7 +900,7 @@ Create a new [channel](#DOCS_RESOURCES_CHANNEL/channel-object) object for the gu ## Modify Guild Channel Positions % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/channels -Modify the positions of a set of [channel](#DOCS_RESOURCES_CHANNEL/channel-object) objects for the guild. Requires `MANAGE_CHANNELS` permission. Returns a 204 empty response on success. Fires multiple [Channel Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-update) Gateway events. +Modify the positions of a set of [channel](#DOCS_RESOURCES_CHANNEL/channel-object) objects for the guild. Requires `MANAGE_CHANNELS` permission. Returns a 204 empty response on success. Fires multiple [Channel Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-update) Gateway events. > info > Only channels to be modified are required. @@ -936,7 +936,7 @@ Returns a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object for t Returns a list of [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) objects that are members of the guild. > warn -> This endpoint is restricted according to whether the `GUILD_MEMBERS` [Privileged Intent](#DOCS_TOPICS_GATEWAY/privileged-intents) is enabled for your application. +> This endpoint is restricted according to whether the `GUILD_MEMBERS` [Privileged Intent](#DOCS_EVENTS_GATEWAY/privileged-intents) is enabled for your application. > info > All parameters to this endpoint are optional @@ -964,7 +964,7 @@ Returns a list of [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) obje ## Add Guild Member % PUT /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/members/{user.id#DOCS_RESOURCES_USER/user-object} -Adds a user to the guild, provided you have a valid oauth2 access token for the user with the `guilds.join` scope. Returns a 201 Created with the [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) as the body, or 204 No Content if the user is already a member of the guild. Fires a [Guild Member Add](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-add) Gateway event. +Adds a user to the guild, provided you have a valid oauth2 access token for the user with the `guilds.join` scope. Returns a 201 Created with the [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) as the body, or 204 No Content if the user is already a member of the guild. Fires a [Guild Member Add](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-add) Gateway event. For guilds with [Membership Screening](#DOCS_RESOURCES_GUILD/membership-screening-object) enabled, this endpoint will default to adding new members as `pending` in the [guild member object](#DOCS_RESOURCES_GUILD/guild-member-object). Members that are `pending` will have to complete membership screening before they become full members that can talk. @@ -987,7 +987,7 @@ For guilds with [Membership Screening](#DOCS_RESOURCES_GUILD/membership-screenin ## Modify Guild Member % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/members/{user.id#DOCS_RESOURCES_USER/user-object} -Modify attributes of a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object). Returns a 200 OK with the [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) as the body. Fires a [Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update) Gateway event. If the `channel_id` is set to null, this will force the target user to be disconnected from voice. +Modify attributes of a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object). Returns a 200 OK with the [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) as the body. Fires a [Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update) Gateway event. If the `channel_id` is set to null, this will force the target user to be disconnected from voice. > info > All parameters to this endpoint are optional and nullable. When moving members to channels, the API user _must_ have permissions to both connect to the channel and have the `MOVE_MEMBERS` permission. @@ -1009,7 +1009,7 @@ Modify attributes of a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) ## Modify Current Member % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/members/@me -Modifies the current member in a guild. Returns a 200 with the updated member object on success. Fires a [Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update) Gateway event. +Modifies the current member in a guild. Returns a 200 with the updated member object on success. Fires a [Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1025,7 +1025,7 @@ Modifies the current member in a guild. Returns a 200 with the updated member ob > danger > Deprecated in favor of [Modify Current Member](#DOCS_RESOURCES_GUILD/modify-current-member). -Modifies the nickname of the current user in a guild. Returns a 200 with the nickname on success. Fires a [Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update) Gateway event. +Modifies the nickname of the current user in a guild. Returns a 200 with the nickname on success. Fires a [Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1038,21 +1038,21 @@ Modifies the nickname of the current user in a guild. Returns a 200 with the nic ## Add Guild Member Role % PUT /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/members/{user.id#DOCS_RESOURCES_USER/user-object}/roles/{role.id#DOCS_TOPICS_PERMISSIONS/role-object} -Adds a role to a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object). Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update) Gateway event. +Adds a role to a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object). Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. ## Remove Guild Member Role % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/members/{user.id#DOCS_RESOURCES_USER/user-object}/roles/{role.id#DOCS_TOPICS_PERMISSIONS/role-object} -Removes a role from a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object). Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update) Gateway event. +Removes a role from a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object). Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. ## Remove Guild Member % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/members/{user.id#DOCS_RESOURCES_USER/user-object} -Remove a member from a guild. Requires `KICK_MEMBERS` permission. Returns a 204 empty response on success. Fires a [Guild Member Remove](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-remove) Gateway event. +Remove a member from a guild. Requires `KICK_MEMBERS` permission. Returns a 204 empty response on success. Fires a [Guild Member Remove](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-remove) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1077,7 +1077,7 @@ Returns a [ban](#DOCS_RESOURCES_GUILD/ban-object) object for the given user or a ## Create Guild Ban % PUT /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/bans/{user.id#DOCS_RESOURCES_USER/user-object} -Create a guild ban, and optionally delete previous messages sent by the banned user. Requires the `BAN_MEMBERS` permission. Returns a 204 empty response on success. Fires a [Guild Ban Add](#DOCS_TOPICS_GATEWAY_EVENTS/guild-ban-add) Gateway event. +Create a guild ban, and optionally delete previous messages sent by the banned user. Requires the `BAN_MEMBERS` permission. Returns a 204 empty response on success. Fires a [Guild Ban Add](#DOCS_EVENTS_GATEWAY_EVENTS/guild-ban-add) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1091,7 +1091,7 @@ Create a guild ban, and optionally delete previous messages sent by the banned u ## Remove Guild Ban % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/bans/{user.id#DOCS_RESOURCES_USER/user-object} -Remove the ban for a user. Requires the `BAN_MEMBERS` permissions. Returns a 204 empty response on success. Fires a [Guild Ban Remove](#DOCS_TOPICS_GATEWAY_EVENTS/guild-ban-remove) Gateway event. +Remove the ban for a user. Requires the `BAN_MEMBERS` permissions. Returns a 204 empty response on success. Fires a [Guild Ban Remove](#DOCS_EVENTS_GATEWAY_EVENTS/guild-ban-remove) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1132,7 +1132,7 @@ Returns a [role](#DOCS_TOPICS_PERMISSIONS/role-object) object for the specified ## Create Guild Role % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/roles -Create a new [role](#DOCS_TOPICS_PERMISSIONS/role-object) for the guild. Requires the `MANAGE_ROLES` permission. Returns the new [role](#DOCS_TOPICS_PERMISSIONS/role-object) object on success. Fires a [Guild Role Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-role-create) Gateway event. All JSON params are optional. +Create a new [role](#DOCS_TOPICS_PERMISSIONS/role-object) for the guild. Requires the `MANAGE_ROLES` permission. Returns the new [role](#DOCS_TOPICS_PERMISSIONS/role-object) object on success. Fires a [Guild Role Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-role-create) Gateway event. All JSON params are optional. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1151,7 +1151,7 @@ Create a new [role](#DOCS_TOPICS_PERMISSIONS/role-object) for the guild. Require ## Modify Guild Role Positions % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/roles -Modify the positions of a set of [role](#DOCS_TOPICS_PERMISSIONS/role-object) objects for the guild. Requires the `MANAGE_ROLES` permission. Returns a list of all of the guild's [role](#DOCS_TOPICS_PERMISSIONS/role-object) objects on success. Fires multiple [Guild Role Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-role-update) Gateway events. +Modify the positions of a set of [role](#DOCS_TOPICS_PERMISSIONS/role-object) objects for the guild. Requires the `MANAGE_ROLES` permission. Returns a list of all of the guild's [role](#DOCS_TOPICS_PERMISSIONS/role-object) objects on success. Fires multiple [Guild Role Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-role-update) Gateway events. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1167,7 +1167,7 @@ This endpoint takes a JSON array of parameters in the following format: ## Modify Guild Role % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/roles/{role.id#DOCS_TOPICS_PERMISSIONS/role-object} -Modify a guild role. Requires the `MANAGE_ROLES` permission. Returns the updated [role](#DOCS_TOPICS_PERMISSIONS/role-object) on success. Fires a [Guild Role Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-role-update) Gateway event. +Modify a guild role. Requires the `MANAGE_ROLES` permission. Returns the updated [role](#DOCS_TOPICS_PERMISSIONS/role-object) on success. Fires a [Guild Role Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-role-update) Gateway event. > info > All parameters to this endpoint are optional and nullable. @@ -1189,7 +1189,7 @@ Modify a guild role. Requires the `MANAGE_ROLES` permission. Returns the updated ## Modify Guild MFA Level % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/mfa -Modify a guild's MFA level. Requires guild ownership. Returns the updated [level](#DOCS_RESOURCES_GUILD/guild-object-mfa-level) on success. Fires a [Guild Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-update) Gateway event. +Modify a guild's MFA level. Requires guild ownership. Returns the updated [level](#DOCS_RESOURCES_GUILD/guild-object-mfa-level) on success. Fires a [Guild Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-update) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1202,7 +1202,7 @@ Modify a guild's MFA level. Requires guild ownership. Returns the updated [level ## Delete Guild Role % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/roles/{role.id#DOCS_TOPICS_PERMISSIONS/role-object} -Delete a guild role. Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Guild Role Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-role-delete) Gateway event. +Delete a guild role. Requires the `MANAGE_ROLES` permission. Returns a 204 empty response on success. Fires a [Guild Role Delete](#DOCS_EVENTS_GATEWAY_EVENTS/guild-role-delete) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1222,7 +1222,7 @@ By default, prune will not remove users with roles. You can optionally include s ## Begin Guild Prune % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/prune -Begin a prune operation. Requires the `MANAGE_GUILD` and `KICK_MEMBERS` permissions. Returns an object with one `pruned` key indicating the number of members that were removed in the prune operation. For large guilds it's recommended to set the `compute_prune_count` option to `false`, forcing `pruned` to `null`. Fires multiple [Guild Member Remove](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-remove) Gateway events. +Begin a prune operation. Requires the `MANAGE_GUILD` and `KICK_MEMBERS` permissions. Returns an object with one `pruned` key indicating the number of members that were removed in the prune operation. For large guilds it's recommended to set the `compute_prune_count` option to `false`, forcing `pruned` to `null`. Fires multiple [Guild Member Remove](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-remove) Gateway events. By default, prune will not remove users with roles. You can optionally include specific roles in your prune by providing the `include_roles` parameter. Any inactive user that has a subset of the provided role(s) will be included in the prune and users with additional roles will not. @@ -1255,7 +1255,7 @@ Returns a list of [integration](#DOCS_RESOURCES_GUILD/integration-object) object ## Delete Guild Integration % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/integrations/{integration.id#DOCS_RESOURCES_GUILD/integration-object} -Delete the attached [integration](#DOCS_RESOURCES_GUILD/integration-object) object for the guild. Deletes any associated webhooks and kicks the associated bot if there is one. Requires the `MANAGE_GUILD` permission. Returns a 204 empty response on success. Fires [Guild Integrations Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-integrations-update) and [Integration Delete](#DOCS_TOPICS_GATEWAY_EVENTS/integration-delete) Gateway events. +Delete the attached [integration](#DOCS_RESOURCES_GUILD/integration-object) object for the guild. Deletes any associated webhooks and kicks the associated bot if there is one. Requires the `MANAGE_GUILD` permission. Returns a 204 empty response on success. Fires [Guild Integrations Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-integrations-update) and [Integration Delete](#DOCS_EVENTS_GATEWAY_EVENTS/integration-delete) Gateway events. > info > This endpoint supports the `X-Audit-Log-Reason` header. @@ -1266,14 +1266,14 @@ Returns a [guild widget settings](#DOCS_RESOURCES_GUILD/guild-widget-settings-ob ## Modify Guild Widget % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/widget -Modify a [guild widget settings](#DOCS_RESOURCES_GUILD/guild-widget-settings-object) object for the guild. All attributes may be passed in with JSON and modified. Requires the `MANAGE_GUILD` permission. Returns the updated [guild widget settings](#DOCS_RESOURCES_GUILD/guild-widget-settings-object) object. Fires a [Guild Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-update) Gateway event. +Modify a [guild widget settings](#DOCS_RESOURCES_GUILD/guild-widget-settings-object) object for the guild. All attributes may be passed in with JSON and modified. Requires the `MANAGE_GUILD` permission. Returns the updated [guild widget settings](#DOCS_RESOURCES_GUILD/guild-widget-settings-object) object. Fires a [Guild Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-update) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. ## Get Guild Widget % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/widget.json -Returns the [widget](#DOCS_RESOURCES_GUILD/guild-widget-object) for the guild. Fires an [Invite Create](#DOCS_TOPICS_GATEWAY_EVENTS/invite-create) Gateway event when an invite channel is defined and a new [Invite](#DOCS_RESOURCES_INVITE/invite-object) is generated. +Returns the [widget](#DOCS_RESOURCES_GUILD/guild-widget-object) for the guild. Fires an [Invite Create](#DOCS_EVENTS_GATEWAY_EVENTS/invite-create) Gateway event when an invite channel is defined and a new [Invite](#DOCS_RESOURCES_INVITE/invite-object) is generated. ## Get Guild Vanity URL % GET /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/vanity-url @@ -1317,7 +1317,7 @@ Returns the [Welcome Screen](#DOCS_RESOURCES_GUILD/welcome-screen-object) object ## Modify Guild Welcome Screen % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/welcome-screen -Modify the guild's [Welcome Screen](#DOCS_RESOURCES_GUILD/welcome-screen-object). Requires the `MANAGE_GUILD` permission. Returns the updated [Welcome Screen](#DOCS_RESOURCES_GUILD/welcome-screen-object) object. May fire a [Guild Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-update) Gateway event. +Modify the guild's [Welcome Screen](#DOCS_RESOURCES_GUILD/welcome-screen-object). Requires the `MANAGE_GUILD` permission. Returns the updated [Welcome Screen](#DOCS_RESOURCES_GUILD/welcome-screen-object) object. May fire a [Guild Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-update) Gateway event. > info > All parameters to this endpoint are optional and nullable diff --git a/docs/resources/Guild_Scheduled_Event.mdx b/docs/resources/Guild_Scheduled_Event.mdx index f596bc4084..6b12501b33 100644 --- a/docs/resources/Guild_Scheduled_Event.mdx +++ b/docs/resources/Guild_Scheduled_Event.mdx @@ -271,7 +271,7 @@ Returns a list of [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/ ## Create Guild Scheduled Event % POST /guilds/\{guild.id#DOCS_RESOURCES_GUILD/guild-object\}/scheduled-events -Create a guild scheduled event in the guild. Returns a [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) object on success. Fires a [Guild Scheduled Event Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-create) Gateway event. +Create a guild scheduled event in the guild. Returns a [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) object on success. Fires a [Guild Scheduled Event Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-scheduled-event-create) Gateway event. > info > A guild can have a maximum of 100 events with `SCHEDULED` or `ACTIVE` status at any time. @@ -311,7 +311,7 @@ Get a guild scheduled event. Returns a [guild scheduled event](#DOCS_RESOURCES_G ## Modify Guild Scheduled Event % PATCH /guilds/\{guild.id#DOCS_RESOURCES_GUILD/guild-object\}/scheduled-events/\{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object\} -Modify a guild scheduled event. Returns the modified [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) object on success. Fires a [Guild Scheduled Event Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-update) Gateway event. +Modify a guild scheduled event. Returns the modified [guild scheduled event](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object) object on success. Fires a [Guild Scheduled Event Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-scheduled-event-update) Gateway event. > info > To start or end an event, use this endpoint to modify the event's [status](#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object-guild-scheduled-event-status) field. @@ -350,7 +350,7 @@ Modify a guild scheduled event. Returns the modified [guild scheduled event](#DO ## Delete Guild Scheduled Event % DELETE /guilds/\{guild.id#DOCS_RESOURCES_GUILD/guild-object\}/scheduled-events/\{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object\} -Delete a guild scheduled event. Returns a `204` on success. Fires a [Guild Scheduled Event Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-scheduled-event-delete) Gateway event. +Delete a guild scheduled event. Returns a `204` on success. Fires a [Guild Scheduled Event Delete](#DOCS_EVENTS_GATEWAY_EVENTS/guild-scheduled-event-delete) Gateway event. ## Get Guild Scheduled Event Users % GET /guilds/\{guild.id#DOCS_RESOURCES_GUILD/guild-object\}/scheduled-events/\{guild_scheduled_event.id#DOCS_RESOURCES_GUILD_SCHEDULED_EVENT/guild-scheduled-event-object\}/users diff --git a/docs/resources/Guild_Template.md b/docs/resources/Guild_Template.md index 9473577b18..f4d5bb241f 100644 --- a/docs/resources/Guild_Template.md +++ b/docs/resources/Guild_Template.md @@ -105,7 +105,7 @@ Returns a [guild template](#DOCS_RESOURCES_GUILD_TEMPLATE/guild-template-object) ## Create Guild from Guild Template % POST /guilds/templates/{template.code#DOCS_RESOURCES_GUILD_TEMPLATE/guild-template-object} -Create a new guild based on a template. Returns a [guild](#DOCS_RESOURCES_GUILD/guild-object) object on success. Fires a [Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) Gateway event. +Create a new guild based on a template. Returns a [guild](#DOCS_RESOURCES_GUILD/guild-object) object on success. Fires a [Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) Gateway event. > warn > This endpoint can be used only by bots in less than 10 guilds. diff --git a/docs/resources/Invite.md b/docs/resources/Invite.md index d3f8471a81..9649395850 100644 --- a/docs/resources/Invite.md +++ b/docs/resources/Invite.md @@ -158,7 +158,7 @@ Returns an [invite](#DOCS_RESOURCES_INVITE/invite-object) object for the given c ## Delete Invite % DELETE /invites/{invite.code#DOCS_RESOURCES_INVITE/invite-object} -Delete an invite. Requires the `MANAGE_CHANNELS` permission on the channel this invite belongs to, or `MANAGE_GUILD` to remove any invite across the guild. Returns an [invite](#DOCS_RESOURCES_INVITE/invite-object) object on success. Fires an [Invite Delete](#DOCS_TOPICS_GATEWAY_EVENTS/invite-delete) Gateway event. +Delete an invite. Requires the `MANAGE_CHANNELS` permission on the channel this invite belongs to, or `MANAGE_GUILD` to remove any invite across the guild. Returns an [invite](#DOCS_RESOURCES_INVITE/invite-object) object on success. Fires an [Invite Delete](#DOCS_EVENTS_GATEWAY_EVENTS/invite-delete) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. diff --git a/docs/resources/Message.md b/docs/resources/Message.md index 567805237a..919bc42cc9 100644 --- a/docs/resources/Message.md +++ b/docs/resources/Message.md @@ -11,10 +11,10 @@ Represents a message sent in a channel within Discord. ###### Message Structure > info -> Fields specific to the `MESSAGE_CREATE` and `MESSAGE_UPDATE` events are listed in the [Gateway documentation](#DOCS_TOPICS_GATEWAY_EVENTS/message-create). +> Fields specific to the `MESSAGE_CREATE` and `MESSAGE_UPDATE` events are listed in the [Gateway documentation](#DOCS_EVENTS_GATEWAY_EVENTS/message-create). > warn -> An app will receive empty values in the `content`, `embeds`, `attachments`, and `components` fields while `poll` will be omitted if they have not configured (or been approved for) the [`MESSAGE_CONTENT` privileged intent (`1 << 15`)](#DOCS_TOPICS_GATEWAY/message-content-intent). +> An app will receive empty values in the `content`, `embeds`, `attachments`, and `components` fields while `poll` will be omitted if they have not configured (or been approved for) the [`MESSAGE_CONTENT` privileged intent (`1 << 15`)](#DOCS_EVENTS_GATEWAY/message-content-intent). | Field | Type | Description | |---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -57,7 +57,7 @@ Represents a message sent in a channel within Discord. \[1\] The author object follows the structure of the user object, but is only a valid user in the case where the message is generated by a user or bot user. If the message is generated by a webhook, the author object corresponds to the webhook's id, username, and avatar. You can tell if a message is generated by a webhook by checking for the `webhook_id` on the message object. -\[2\] An app will receive empty values in the `content`, `embeds`, `attachments`, and `components` fields while `poll` will be omitted if they have not configured (or been approved for) the [`MESSAGE_CONTENT` privileged intent (`1 << 15`)](#DOCS_TOPICS_GATEWAY/message-content-intent). +\[2\] An app will receive empty values in the `content`, `embeds`, `attachments`, and `components` fields while `poll` will be omitted if they have not configured (or been approved for) the [`MESSAGE_CONTENT` privileged intent (`1 << 15`)](#DOCS_EVENTS_GATEWAY/message-content-intent). \[3\] Not all channel mentions in a message will appear in `mention_channels`. Only textual channels that are visible to everyone in a lurkable guild will ever be included. Only crossposted messages (via Channel Following) currently include `mention_channels` at all. If no mentions in the message meet these requirements, this field will not be sent. @@ -724,7 +724,7 @@ If operating on a guild channel, this endpoint requires the current user to have > warn > Discord may strip certain characters from message content, like invalid unicode characters or characters which cause unexpected message formatting. If you are passing user-generated strings into message content, consider sanitizing the data to prevent unexpected behavior and using `allowed_mentions` to prevent unexpected mentions. -Post a message to a guild text or DM channel. Returns a [message](#DOCS_RESOURCES_MESSAGE/message-object) object. Fires a [Message Create](#DOCS_TOPICS_GATEWAY_EVENTS/message-create) Gateway event. See [message formatting](#DOCS_REFERENCE/message-formatting) for more information on how to properly format messages. +Post a message to a guild text or DM channel. Returns a [message](#DOCS_RESOURCES_MESSAGE/message-object) object. Fires a [Message Create](#DOCS_EVENTS_GATEWAY_EVENTS/message-create) Gateway event. See [message formatting](#DOCS_REFERENCE/message-formatting) for more information on how to properly format messages. To create a message as a reply or forward of another message, apps can include a [`message_reference`](#DOCS_RESOURCES_MESSAGE/message-reference-structure). Refer to the documentation for required fields. @@ -748,7 +748,7 @@ Files must be attached using a `multipart/form-data` body as described in [Uploa | Field | Type | Description | |--------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | content?\* | string | Message contents (up to 2000 characters) | -| nonce? | integer or string | Can be used to verify a message was sent (up to 25 characters). Value will appear in the [Message Create event](#DOCS_TOPICS_GATEWAY_EVENTS/message-create). | +| nonce? | integer or string | Can be used to verify a message was sent (up to 25 characters). Value will appear in the [Message Create event](#DOCS_EVENTS_GATEWAY_EVENTS/message-create). | | tts? | boolean | `true` if this is a TTS message | | embeds?\* | array of [embed](#DOCS_RESOURCES_MESSAGE/embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) | | allowed_mentions? | [allowed mention object](#DOCS_RESOURCES_MESSAGE/allowed-mentions-object) | Allowed mentions for the message | @@ -783,21 +783,21 @@ Examples for file uploads are available in [Uploading Files](#DOCS_REFERENCE/upl Crosspost a message in an Announcement Channel to following channels. This endpoint requires the `SEND_MESSAGES` permission, if the current user sent the message, or additionally the `MANAGE_MESSAGES` permission, for all other messages, to be present for the current user. -Returns a [message](#DOCS_RESOURCES_MESSAGE/message-object) object. Fires a [Message Update](#DOCS_TOPICS_GATEWAY_EVENTS/message-update) Gateway event. +Returns a [message](#DOCS_RESOURCES_MESSAGE/message-object) object. Fires a [Message Update](#DOCS_EVENTS_GATEWAY_EVENTS/message-update) Gateway event. ## Create Reaction % PUT /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_MESSAGE/message-object}/reactions/{emoji#DOCS_RESOURCES_EMOJI/emoji-object}/@me -Create a reaction for the message. This endpoint requires the `READ_MESSAGE_HISTORY` permission to be present on the current user. Additionally, if nobody else has reacted to the message using this emoji, this endpoint requires the `ADD_REACTIONS` permission to be present on the current user. Returns a 204 empty response on success. Fires a [Message Reaction Add](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-add) Gateway event. +Create a reaction for the message. This endpoint requires the `READ_MESSAGE_HISTORY` permission to be present on the current user. Additionally, if nobody else has reacted to the message using this emoji, this endpoint requires the `ADD_REACTIONS` permission to be present on the current user. Returns a 204 empty response on success. Fires a [Message Reaction Add](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-add) Gateway event. The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding) or the request will fail with `10014: Unknown Emoji`. To use custom emoji, you must encode it in the format `name:id` with the emoji name and emoji id. ## Delete Own Reaction % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_MESSAGE/message-object}/reactions/{emoji#DOCS_RESOURCES_EMOJI/emoji-object}/@me -Delete a reaction the current user has made for the message. Returns a 204 empty response on success. Fires a [Message Reaction Remove](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-remove) Gateway event. +Delete a reaction the current user has made for the message. Returns a 204 empty response on success. Fires a [Message Reaction Remove](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-remove) Gateway event. The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding) or the request will fail with `10014: Unknown Emoji`. To use custom emoji, you must encode it in the format `name:id` with the emoji name and emoji id. ## Delete User Reaction % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_MESSAGE/message-object}/reactions/{emoji#DOCS_RESOURCES_EMOJI/emoji-object}/{user.id#DOCS_RESOURCES_USER/user-object} -Deletes another user's reaction. This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user. Returns a 204 empty response on success. Fires a [Message Reaction Remove](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-remove) Gateway event. +Deletes another user's reaction. This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user. Returns a 204 empty response on success. Fires a [Message Reaction Remove](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-remove) Gateway event. The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding) or the request will fail with `10014: Unknown Emoji`. To use custom emoji, you must encode it in the format `name:id` with the emoji name and emoji id. ## Get Reactions % GET /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_MESSAGE/message-object}/reactions/{emoji#DOCS_RESOURCES_EMOJI/emoji-object} @@ -822,11 +822,11 @@ The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding ## Delete All Reactions % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_MESSAGE/message-object}/reactions -Deletes all reactions on a message. This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user. Fires a [Message Reaction Remove All](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-remove-all) Gateway event. +Deletes all reactions on a message. This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user. Fires a [Message Reaction Remove All](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-remove-all) Gateway event. ## Delete All Reactions for Emoji % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_MESSAGE/message-object}/reactions/{emoji#DOCS_RESOURCES_EMOJI/emoji-object} -Deletes all the reactions for a given emoji on a message. This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user. Fires a [Message Reaction Remove Emoji](#DOCS_TOPICS_GATEWAY_EVENTS/message-reaction-remove-emoji) Gateway event. +Deletes all the reactions for a given emoji on a message. This endpoint requires the `MANAGE_MESSAGES` permission to be present on the current user. Fires a [Message Reaction Remove Emoji](#DOCS_EVENTS_GATEWAY_EVENTS/message-reaction-remove-emoji) Gateway event. The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding) or the request will fail with `10014: Unknown Emoji`. To use custom emoji, you must encode it in the format `name:id` with the emoji name and emoji id. ## Edit Message % PATCH /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_MESSAGE/message-object} @@ -835,7 +835,7 @@ Edit a previously sent message. The fields `content`, `embeds`, and `flags` can When the `content` field is edited, the `mentions` array in the message object will be reconstructed from scratch based on the new content. The `allowed_mentions` field of the edit request controls how this happens. If there is no explicit `allowed_mentions` in the edit request, the content will be parsed with _default_ allowances, that is, without regard to whether or not an `allowed_mentions` was present in the request that originally created the message. -Returns a [message](#DOCS_RESOURCES_MESSAGE/message-object) object. Fires a [Message Update](#DOCS_TOPICS_GATEWAY_EVENTS/message-update) Gateway event. +Returns a [message](#DOCS_RESOURCES_MESSAGE/message-object) object. Fires a [Message Update](#DOCS_EVENTS_GATEWAY_EVENTS/message-update) Gateway event. Refer to [Uploading Files](#DOCS_REFERENCE/uploading-files) for details on attachments and `multipart/form-data` requests. Any provided files will be **appended** to the message. To remove or replace files you will have to supply the `attachments` field which specifies the files to retain on the message after edit. @@ -861,14 +861,14 @@ Any provided files will be **appended** to the message. To remove or replace fil ## Delete Message % DELETE /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/{message.id#DOCS_RESOURCES_MESSAGE/message-object} -Delete a message. If operating on a guild channel and trying to delete a message that was not sent by the current user, this endpoint requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Message Delete](#DOCS_TOPICS_GATEWAY_EVENTS/message-delete) Gateway event. +Delete a message. If operating on a guild channel and trying to delete a message that was not sent by the current user, this endpoint requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Message Delete](#DOCS_EVENTS_GATEWAY_EVENTS/message-delete) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. ## Bulk Delete Messages % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/messages/bulk-delete -Delete multiple messages in a single request. This endpoint can only be used on guild channels and requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Message Delete Bulk](#DOCS_TOPICS_GATEWAY_EVENTS/message-delete-bulk) Gateway event. +Delete multiple messages in a single request. This endpoint can only be used on guild channels and requires the `MANAGE_MESSAGES` permission. Returns a 204 empty response on success. Fires a [Message Delete Bulk](#DOCS_EVENTS_GATEWAY_EVENTS/message-delete-bulk) Gateway event. Any message IDs given that do not exist or are invalid will count towards the minimum and maximum message count (currently 2 and 100 respectively). diff --git a/docs/resources/Poll.md b/docs/resources/Poll.md index b943c95dca..df4128b94d 100644 --- a/docs/resources/Poll.md +++ b/docs/resources/Poll.md @@ -144,4 +144,4 @@ Get a list of users that voted for this specific answer. Immediately ends the poll. You cannot end polls from other users. -Returns a [message](#DOCS_RESOURCES_MESSAGE/message-object) object. Fires a [Message Update](#DOCS_TOPICS_GATEWAY_EVENTS/message-update) Gateway event. +Returns a [message](#DOCS_RESOURCES_MESSAGE/message-object) object. Fires a [Message Update](#DOCS_EVENTS_GATEWAY_EVENTS/message-update) Gateway event. diff --git a/docs/resources/Soundboard.md b/docs/resources/Soundboard.md index eb6b34236e..72ec7910ec 100644 --- a/docs/resources/Soundboard.md +++ b/docs/resources/Soundboard.md @@ -4,11 +4,11 @@ sidebar_label: Soundboard # Soundboard Resource -Users can play soundboard sounds in voice channels, triggering a [Voice Channel Effect Send](#DOCS_TOPICS_GATEWAY_EVENTS/voice-channel-effect-send) Gateway event for users connected to the voice channel. +Users can play soundboard sounds in voice channels, triggering a [Voice Channel Effect Send](#DOCS_EVENTS_GATEWAY_EVENTS/voice-channel-effect-send) Gateway event for users connected to the voice channel. There is a set of [default sounds](#DOCS_RESOURCES_SOUNDBOARD/list-default-soundboard-sounds) available to all users. Soundboard sounds can also be [created in a guild](#DOCS_RESOURCES_SOUNDBOARD/create-guild-soundboard-sound); users will be able to use the sounds in the guild, and Nitro subscribers can use them in all guilds. -Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Request Soundboard Sounds](#DOCS_TOPICS_GATEWAY_EVENTS/request-soundboard-sounds). +Soundboard sounds in a set of guilds can be retrieved over the Gateway using [Request Soundboard Sounds](#DOCS_EVENTS_GATEWAY_EVENTS/request-soundboard-sounds). ### Soundboard Sound Object @@ -62,7 +62,7 @@ https://cdn.discordapp.com/soundboard-sounds/{sound_id} ## Send Soundboard Sound % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/send-soundboard-sound -Send a soundboard sound to a voice channel the user is connected to. Fires a [Voice Channel Effect Send](#DOCS_TOPICS_GATEWAY_EVENTS/voice-channel-effect-send) Gateway event. +Send a soundboard sound to a voice channel the user is connected to. Fires a [Voice Channel Effect Send](#DOCS_EVENTS_GATEWAY_EVENTS/voice-channel-effect-send) Gateway event. Requires the `SPEAK` and `USE_SOUNDBOARD` permissions, and also the `USE_EXTERNAL_SOUNDS` permission if the sound is from a different server. Additionally, requires the user to be connected to the voice channel, having a [voice state](#DOCS_RESOURCES_VOICE/voice-state-object) without `deaf`, `self_deaf`, `mute`, or `suppress` enabled. @@ -93,7 +93,7 @@ Returns a [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) ## Create Guild Soundboard Sound % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds -Create a new soundboard sound for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) object on success. Fires a [Guild Soundboard Sound Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-create) Gateway event. +Create a new soundboard sound for the guild. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) object on success. Fires a [Guild Soundboard Sound Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-soundboard-sound-create) Gateway event. > info > Soundboard sounds have a max file size of 512kb and a max duration of 5.2 seconds. @@ -113,7 +113,7 @@ Create a new soundboard sound for the guild. Requires the `CREATE_GUILD_EXPRESSI ## Modify Guild Soundboard Sound % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds/{sound.id#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object} -Modify the given soundboard sound. For sounds created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other sounds, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) object on success. Fires a [Guild Soundboard Sound Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-update) Gateway event. +Modify the given soundboard sound. For sounds created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other sounds, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [soundboard sound](#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object) object on success. Fires a [Guild Soundboard Sound Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-soundboard-sound-update) Gateway event. > warn > All parameters to this endpoint are optional. @@ -132,7 +132,7 @@ Modify the given soundboard sound. For sounds created by the current user, requi ## Delete Guild Soundboard Sound % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/soundboard-sounds/{sound.id#DOCS_RESOURCES_SOUNDBOARD/soundboard-sound-object} -Delete the given soundboard sound. For sounds created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other sounds, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Soundboard Sound Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-soundboard-sound-delete) Gateway event. +Delete the given soundboard sound. For sounds created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other sounds, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Soundboard Sound Delete](#DOCS_EVENTS_GATEWAY_EVENTS/guild-soundboard-sound-delete) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. diff --git a/docs/resources/Stage_Instance.md b/docs/resources/Stage_Instance.md index 33ba54d094..8f4fab64e9 100644 --- a/docs/resources/Stage_Instance.md +++ b/docs/resources/Stage_Instance.md @@ -54,7 +54,7 @@ Below are some definitions related to stages. - `MOVE_MEMBERS` - **Topic**: This is the blurb that gets shown below the channel's name, among other places. - **Public**: A Stage instance is public when it has a `privacy_level` of `PUBLIC`. While a guild has a public Stage instance: - - Users in the Stage can have the Stage show in their [activities](#DOCS_TOPICS_GATEWAY_EVENTS/presence). + - Users in the Stage can have the Stage show in their [activities](#DOCS_EVENTS_GATEWAY_EVENTS/presence). - [Invites](#DOCS_RESOURCES_INVITE/invite-object) to the Stage channel will have the `stage_instance` field. ## Auto Closing @@ -63,7 +63,7 @@ When a Stage channel has no speakers for a certain period of time (on the order ## Create Stage Instance % POST /stage-instances -Creates a new Stage instance associated to a Stage channel. Returns that [Stage instance](#DOCS_RESOURCES_STAGE_INSTANCE/stage-instance-object-stage-instance-structure). Fires a [Stage Instance Create](#DOCS_TOPICS_GATEWAY_EVENTS/stage-instance-create) Gateway event. +Creates a new Stage instance associated to a Stage channel. Returns that [Stage instance](#DOCS_RESOURCES_STAGE_INSTANCE/stage-instance-object-stage-instance-structure). Fires a [Stage Instance Create](#DOCS_EVENTS_GATEWAY_EVENTS/stage-instance-create) Gateway event. Requires the user to be a moderator of the Stage channel. @@ -88,7 +88,7 @@ Gets the stage instance associated with the Stage channel, if it exists. ## Modify Stage Instance % PATCH /stage-instances/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object} -Updates fields of an existing Stage instance. Returns the updated [Stage instance](#DOCS_RESOURCES_STAGE_INSTANCE/stage-instance-object-stage-instance-structure). Fires a [Stage Instance Update](#DOCS_TOPICS_GATEWAY_EVENTS/stage-instance-update) Gateway event. +Updates fields of an existing Stage instance. Returns the updated [Stage instance](#DOCS_RESOURCES_STAGE_INSTANCE/stage-instance-object-stage-instance-structure). Fires a [Stage Instance Update](#DOCS_EVENTS_GATEWAY_EVENTS/stage-instance-update) Gateway event. Requires the user to be a moderator of the Stage channel. @@ -104,7 +104,7 @@ Requires the user to be a moderator of the Stage channel. ## Delete Stage Instance % DELETE /stage-instances/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object} -Deletes the Stage instance. Returns `204 No Content`. Fires a [Stage Instance Delete](#DOCS_TOPICS_GATEWAY_EVENTS/stage-instance-delete) Gateway event. +Deletes the Stage instance. Returns `204 No Content`. Fires a [Stage Instance Delete](#DOCS_EVENTS_GATEWAY_EVENTS/stage-instance-delete) Gateway event. Requires the user to be a moderator of the Stage channel. diff --git a/docs/resources/Sticker.md b/docs/resources/Sticker.md index bbdc56ea13..1bfdc338d7 100644 --- a/docs/resources/Sticker.md +++ b/docs/resources/Sticker.md @@ -128,7 +128,7 @@ Returns a [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object for the given ## Create Guild Sticker % POST /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/stickers -Create a new sticker for the guild. Send a `multipart/form-data` body. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object on success. Fires a [Guild Stickers Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-stickers-update) Gateway event. +Create a new sticker for the guild. Send a `multipart/form-data` body. Requires the `CREATE_GUILD_EXPRESSIONS` permission. Returns the new [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object on success. Fires a [Guild Stickers Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-stickers-update) Gateway event. Every guilds has five free sticker slots by default, and each Boost level will grant access to more slots. @@ -152,7 +152,7 @@ Every guilds has five free sticker slots by default, and each Boost level will g ## Modify Guild Sticker % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/stickers/{sticker.id#DOCS_RESOURCES_STICKER/sticker-object} -Modify the given sticker. For stickers created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other stickers, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object on success. Fires a [Guild Stickers Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-stickers-update) Gateway event. +Modify the given sticker. For stickers created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other stickers, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns the updated [sticker](#DOCS_RESOURCES_STICKER/sticker-object) object on success. Fires a [Guild Stickers Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-stickers-update) Gateway event. > info > All parameters to this endpoint are optional. @@ -170,7 +170,7 @@ Modify the given sticker. For stickers created by the current user, requires eit ## Delete Guild Sticker % DELETE /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/stickers/{sticker.id#DOCS_RESOURCES_STICKER/sticker-object} -Delete the given sticker. For stickers created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other stickers, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Stickers Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-stickers-update) Gateway event. +Delete the given sticker. For stickers created by the current user, requires either the `CREATE_GUILD_EXPRESSIONS` or `MANAGE_GUILD_EXPRESSIONS` permission. For other stickers, requires the `MANAGE_GUILD_EXPRESSIONS` permission. Returns `204 No Content` on success. Fires a [Guild Stickers Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-stickers-update) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. diff --git a/docs/resources/User.md b/docs/resources/User.md index aa8d7da444..9873d800ce 100644 --- a/docs/resources/User.md +++ b/docs/resources/User.md @@ -190,7 +190,7 @@ Returns a [user](#DOCS_RESOURCES_USER/user-object) object for a given user ID. ## Modify Current User % PATCH /users/@me -Modify the requester's user account settings. Returns a [user](#DOCS_RESOURCES_USER/user-object) object on success. Fires a [User Update](#DOCS_TOPICS_GATEWAY_EVENTS/user-update) Gateway event. +Modify the requester's user account settings. Returns a [user](#DOCS_RESOURCES_USER/user-object) object on success. Fires a [User Update](#DOCS_EVENTS_GATEWAY_EVENTS/user-update) Gateway event. > info > All parameters to this endpoint are optional. @@ -241,7 +241,7 @@ Returns a [guild member](#DOCS_RESOURCES_GUILD/guild-member-object) object for t ## Leave Guild % DELETE /users/@me/guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object} -Leave a guild. Returns a 204 empty response on success. Fires a [Guild Delete](#DOCS_TOPICS_GATEWAY_EVENTS/guild-delete) Gateway event and a [Guild Member Remove](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-remove) Gateway event. +Leave a guild. Returns a 204 empty response on success. Fires a [Guild Delete](#DOCS_EVENTS_GATEWAY_EVENTS/guild-delete) Gateway event and a [Guild Member Remove](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-remove) Gateway event. ## Create DM % POST /users/@me/channels @@ -258,7 +258,7 @@ Create a new DM channel with a user. Returns a [DM channel](#DOCS_RESOURCES_CHAN ## Create Group DM % POST /users/@me/channels -Create a new group DM channel with multiple users. Returns a [DM channel](#DOCS_RESOURCES_CHANNEL/channel-object) object. This endpoint was intended to be used with the now-deprecated GameBridge SDK. Fires a [Channel Create](#DOCS_TOPICS_GATEWAY_EVENTS/channel-create) Gateway event. +Create a new group DM channel with multiple users. Returns a [DM channel](#DOCS_RESOURCES_CHANNEL/channel-object) object. This endpoint was intended to be used with the now-deprecated GameBridge SDK. Fires a [Channel Create](#DOCS_EVENTS_GATEWAY_EVENTS/channel-create) Gateway event. > warn > This endpoint is limited to 10 active group DMs. diff --git a/docs/resources/Voice.md b/docs/resources/Voice.md index 4981e5ea59..cddebc402a 100644 --- a/docs/resources/Voice.md +++ b/docs/resources/Voice.md @@ -68,7 +68,7 @@ Returns the specified user's [voice state](#DOCS_RESOURCES_VOICE/voice-state-obj ## Modify Current User Voice State % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/voice-states/@me -Updates the current user's voice state. Returns `204 No Content` on success. Fires a [Voice State Update](#DOCS_TOPICS_GATEWAY_EVENTS/voice-state-update) Gateway event. +Updates the current user's voice state. Returns `204 No Content` on success. Fires a [Voice State Update](#DOCS_EVENTS_GATEWAY_EVENTS/voice-state-update) Gateway event. ###### JSON Params @@ -90,7 +90,7 @@ There are currently several caveats for this endpoint: ## Modify User Voice State % PATCH /guilds/{guild.id#DOCS_RESOURCES_GUILD/guild-object}/voice-states/{user.id#DOCS_RESOURCES_USER/user-object} -Updates another user's voice state. Fires a [Voice State Update](#DOCS_TOPICS_GATEWAY_EVENTS/voice-state-update) Gateway event. +Updates another user's voice state. Fires a [Voice State Update](#DOCS_EVENTS_GATEWAY_EVENTS/voice-state-update) Gateway event. ###### JSON Params diff --git a/docs/resources/Webhook.md b/docs/resources/Webhook.md index 669f4cba2f..af8f306872 100644 --- a/docs/resources/Webhook.md +++ b/docs/resources/Webhook.md @@ -6,6 +6,8 @@ sidebar_label: Webhook Webhooks are a low-effort way to post messages to channels in Discord. They do not require a bot user or authentication to use. +Apps can also subscribe to webhook events (i.e. outgoing webhooks) when events happen *in* Discord, which is detailed in the [Webhook Events](#DOCS_EVENTS_WEBHOOK_EVENTS) documentation. + ### Webhook Object Used to represent a webhook. @@ -31,6 +33,9 @@ Used to represent a webhook. ###### Webhook Types +> info +> These types don't include [webhook events](#DOCS_EVENTS_WEBHOOK_EVENTS), which are outgoing webhooks sent to your app by Discord. See [Webhook Events](#DOCS_EVENTS_WEBHOOK_EVENTS) for details. + | Value | Name | Description | |-------|------------------|----------------------------------------------------------------------------------------------------------------| | 1 | Incoming | Incoming Webhooks can post messages to channels with a generated token | @@ -105,7 +110,7 @@ Used to represent a webhook. ## Create Webhook % POST /channels/{channel.id#DOCS_RESOURCES_CHANNEL/channel-object}/webhooks -Creates a new webhook and returns a [webhook](#DOCS_RESOURCES_WEBHOOK/webhook-object) object on success. Requires the `MANAGE_WEBHOOKS` permission. Fires a [Webhooks Update](#DOCS_TOPICS_GATEWAY_EVENTS/webhooks-update) Gateway event. +Creates a new webhook and returns a [webhook](#DOCS_RESOURCES_WEBHOOK/webhook-object) object on success. Requires the `MANAGE_WEBHOOKS` permission. Fires a [Webhooks Update](#DOCS_EVENTS_GATEWAY_EVENTS/webhooks-update) Gateway event. An error will be returned if a webhook name (`name`) is not valid. A webhook name is valid if: @@ -143,7 +148,7 @@ Same as above, except this call does not require authentication and returns no u ## Modify Webhook % PATCH /webhooks/{webhook.id#DOCS_RESOURCES_WEBHOOK/webhook-object} -Modify a webhook. Requires the `MANAGE_WEBHOOKS` permission. Returns the updated [webhook](#DOCS_RESOURCES_WEBHOOK/webhook-object) object on success. Fires a [Webhooks Update](#DOCS_TOPICS_GATEWAY_EVENTS/webhooks-update) Gateway event. +Modify a webhook. Requires the `MANAGE_WEBHOOKS` permission. Returns the updated [webhook](#DOCS_RESOURCES_WEBHOOK/webhook-object) object on success. Fires a [Webhooks Update](#DOCS_EVENTS_GATEWAY_EVENTS/webhooks-update) Gateway event. > info > All parameters to this endpoint are optional @@ -165,7 +170,7 @@ Same as above, except this call does not require authentication, does not accept ## Delete Webhook % DELETE /webhooks/{webhook.id#DOCS_RESOURCES_WEBHOOK/webhook-object} -Delete a webhook permanently. Requires the `MANAGE_WEBHOOKS` permission. Returns a `204 No Content` response on success. Fires a [Webhooks Update](#DOCS_TOPICS_GATEWAY_EVENTS/webhooks-update) Gateway event. +Delete a webhook permanently. Requires the `MANAGE_WEBHOOKS` permission. Returns a `204 No Content` response on success. Fires a [Webhooks Update](#DOCS_EVENTS_GATEWAY_EVENTS/webhooks-update) Gateway event. > info > This endpoint supports the `X-Audit-Log-Reason` header. diff --git a/docs/rich_presence/Overview.mdx b/docs/rich_presence/Overview.mdx index 4546ba7aa9..0b629780bf 100644 --- a/docs/rich_presence/Overview.mdx +++ b/docs/rich_presence/Overview.mdx @@ -57,7 +57,7 @@ The Rich Presence invite image appears when [invites](#DOCS_DEVELOPER_TOOLS_GAME Up to 300 custom assets can be added for your app to use when setting Rich Presence for a Discord user. These assets can be anything that help orient others to what a user is doing inside of your Activity or 3rd party game. -If you need more than 300 custom assets or want to use images stored somewhere else, you can also [specify an external URL](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-asset-image) as long it still has the proper dimensions and size. +If you need more than 300 custom assets or want to use images stored somewhere else, you can also [specify an external URL](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-asset-image) as long it still has the proper dimensions and size. > info > For tips on choosing assets, take a look at the [Rich Presence best practices guide](#DOCS_RICH_PRESENCE_BEST_PRACTICES/have-interesting-expressive-art). diff --git a/docs/rich_presence/Using_with_the_Embedded_App_SDK.mdx b/docs/rich_presence/Using_with_the_Embedded_App_SDK.mdx index b9717d26f2..1c222d1ef2 100644 --- a/docs/rich_presence/Using_with_the_Embedded_App_SDK.mdx +++ b/docs/rich_presence/Using_with_the_Embedded_App_SDK.mdx @@ -74,7 +74,7 @@ const { code } = await discordSdk.commands.authorize({ ### setActivity Fields -When calling [`setActivity()`](#DOCS_DEVELOPER_TOOLS_EMBEDDED_APP_SDK/setactivity), you are expected to pass a partial [activity object](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-structure). +When calling [`setActivity()`](#DOCS_DEVELOPER_TOOLS_EMBEDDED_APP_SDK/setactivity), you are expected to pass a partial [activity object](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-structure). Below is a table with many of the available fields for the activity partial. Some were left out since they don't have an effect for Activities. @@ -85,12 +85,12 @@ Below is a table with many of the available fields for the activity partial. Som | field | type | description | |------------|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| -| type | integer | [Activity](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-types) type, which determines the header text for the Rich Presence data | +| type | integer | [Activity](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-types) type, which determines the header text for the Rich Presence data | | state | string | User's current party status | | details | string | What the player is currently doing in your Activity | -| timestamps | [timestamps](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-timestamps) object | Unix timestamps to display start and/or end times | -| assets | [assets](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-assets) object | Images used for the Rich Presence data (and their hover texts) | -| party | [party](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-party) object | Information for the current party of the player | +| timestamps | [timestamps](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-timestamps) object | Unix timestamps to display start and/or end times | +| assets | [assets](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-assets) object | Images used for the Rich Presence data (and their hover texts) | +| party | [party](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-party) object | Information for the current party of the player | ### setActivity Example diff --git a/docs/rich_presence/Using_with_the_Game_SDK.mdx b/docs/rich_presence/Using_with_the_Game_SDK.mdx index 0d3924e235..26ff2a735f 100644 --- a/docs/rich_presence/Using_with_the_Game_SDK.mdx +++ b/docs/rich_presence/Using_with_the_Game_SDK.mdx @@ -216,7 +216,7 @@ Currently, the SDK does not support this. Party slot information is determined b #### Q: Can I send images via the payload rather than uploading them to my app's settings? -Yes! In addition to uploading an asset and specifying its name, you can also specify an external image URL for us to proxy. For more information, see [Activity Asset Image](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object-activity-asset-image). +Yes! In addition to uploading an asset and specifying its name, you can also specify an external image URL for us to proxy. For more information, see [Activity Asset Image](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object-activity-asset-image). #### Q: OK—I've got it working! Now, how do I make my integration look _awesome_? diff --git a/docs/topics/OAuth2.md b/docs/topics/OAuth2.md index 444a838b14..17202c34ff 100644 --- a/docs/topics/OAuth2.md +++ b/docs/topics/OAuth2.md @@ -259,7 +259,7 @@ In return, you will receive an access token (without a refresh token): ## Bot Users -Discord's API provides bot users, which are a separate type of user dedicated to automation. Bot users are automatically added to all apps, and are authenticated using the bot token found in your [app's settings](https://discord.com/developers/applications). Unlike the normal OAuth2 flow, bot users have full access to most API routes without using bearer tokens, and can connect to the [Real Time Gateway](#DOCS_TOPICS_GATEWAY). +Discord's API provides bot users, which are a separate type of user dedicated to automation. Bot users are automatically added to all apps, and are authenticated using the bot token found in your [app's settings](https://discord.com/developers/applications). Unlike the normal OAuth2 flow, bot users have full access to most API routes without using bearer tokens, and can connect to the [Real Time Gateway](#DOCS_EVENTS_GATEWAY). ### Bot vs User Accounts diff --git a/docs/topics/Opcodes_and_Status_Codes.md b/docs/topics/Opcodes_and_Status_Codes.md index f1bc796f7c..7105857a1a 100644 --- a/docs/topics/Opcodes_and_Status_Codes.md +++ b/docs/topics/Opcodes_and_Status_Codes.md @@ -30,18 +30,18 @@ In order to prevent broken reconnect loops, you should consider some close codes |------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------| | 4000 | Unknown error | We're not sure what went wrong. Try reconnecting? | true | | 4001 | Unknown opcode | You sent an invalid [Gateway opcode](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway-gateway-opcodes) or an invalid payload for an opcode. Don't do that! | true | -| 4002 | Decode error | You sent an invalid [payload](#DOCS_TOPICS_GATEWAY/sending-events) to Discord. Don't do that! | true | -| 4003 | Not authenticated | You sent us a payload prior to [identifying](#DOCS_TOPICS_GATEWAY/identifying), or this session has been invalidated. | true | -| 4004 | Authentication failed | The account token sent with your [identify payload](#DOCS_TOPICS_GATEWAY_EVENTS/identify) is incorrect. | false | +| 4002 | Decode error | You sent an invalid [payload](#DOCS_EVENTS_GATEWAY/sending-events) to Discord. Don't do that! | true | +| 4003 | Not authenticated | You sent us a payload prior to [identifying](#DOCS_EVENTS_GATEWAY/identifying), or this session has been invalidated. | true | +| 4004 | Authentication failed | The account token sent with your [identify payload](#DOCS_EVENTS_GATEWAY_EVENTS/identify) is incorrect. | false | | 4005 | Already authenticated | You sent more than one identify payload. Don't do that! | true | -| 4007 | Invalid `seq` | The sequence sent when [resuming](#DOCS_TOPICS_GATEWAY_EVENTS/resume) the session was invalid. Reconnect and start a new session. | true | +| 4007 | Invalid `seq` | The sequence sent when [resuming](#DOCS_EVENTS_GATEWAY_EVENTS/resume) the session was invalid. Reconnect and start a new session. | true | | 4008 | Rate limited | Woah nelly! You're sending payloads to us too quickly. Slow it down! You will be disconnected on receiving this. | true | | 4009 | Session timed out | Your session timed out. Reconnect and start a new one. | true | -| 4010 | Invalid shard | You sent us an invalid [shard when identifying](#DOCS_TOPICS_GATEWAY/sharding). | false | -| 4011 | Sharding required | The session would have handled too many guilds - you are required to [shard](#DOCS_TOPICS_GATEWAY/sharding) your connection in order to connect. | false | +| 4010 | Invalid shard | You sent us an invalid [shard when identifying](#DOCS_EVENTS_GATEWAY/sharding). | false | +| 4011 | Sharding required | The session would have handled too many guilds - you are required to [shard](#DOCS_EVENTS_GATEWAY/sharding) your connection in order to connect. | false | | 4012 | Invalid API version | You sent an invalid version for the gateway. | false | -| 4013 | Invalid intent(s) | You sent an invalid intent for a [Gateway Intent](#DOCS_TOPICS_GATEWAY/gateway-intents). You may have incorrectly calculated the bitwise value. | false | -| 4014 | Disallowed intent(s) | You sent a disallowed intent for a [Gateway Intent](#DOCS_TOPICS_GATEWAY/gateway-intents). You may have tried to specify an intent that you [have not enabled or are not approved for](#DOCS_TOPICS_GATEWAY/privileged-intents). | false | +| 4013 | Invalid intent(s) | You sent an invalid intent for a [Gateway Intent](#DOCS_EVENTS_GATEWAY/gateway-intents). You may have incorrectly calculated the bitwise value. | false | +| 4014 | Disallowed intent(s) | You sent a disallowed intent for a [Gateway Intent](#DOCS_EVENTS_GATEWAY/gateway-intents). You may have tried to specify an intent that you [have not enabled or are not approved for](#DOCS_EVENTS_GATEWAY/privileged-intents). | false | ## Voice @@ -80,10 +80,10 @@ Our voice gateways have their own set of opcodes and close codes. | Code | Description | Explanation | |------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | 4001 | Unknown opcode | You sent an invalid [opcode](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/voice-voice-opcodes). | -| 4002 | Failed to decode payload | You sent an invalid payload in your [identifying](#DOCS_TOPICS_GATEWAY_EVENTS/identify) to the Gateway. | -| 4003 | Not authenticated | You sent a payload before [identifying](#DOCS_TOPICS_GATEWAY_EVENTS/identify) with the Gateway. | -| 4004 | Authentication failed | The token you sent in your [identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) payload is incorrect. | -| 4005 | Already authenticated | You sent more than one [identify](#DOCS_TOPICS_GATEWAY_EVENTS/identify) payload. Stahp. | +| 4002 | Failed to decode payload | You sent an invalid payload in your [identifying](#DOCS_EVENTS_GATEWAY_EVENTS/identify) to the Gateway. | +| 4003 | Not authenticated | You sent a payload before [identifying](#DOCS_EVENTS_GATEWAY_EVENTS/identify) with the Gateway. | +| 4004 | Authentication failed | The token you sent in your [identify](#DOCS_EVENTS_GATEWAY_EVENTS/identify) payload is incorrect. | +| 4005 | Already authenticated | You sent more than one [identify](#DOCS_EVENTS_GATEWAY_EVENTS/identify) payload. Stahp. | | 4006 | Session no longer valid | Your session is no longer valid. | | 4009 | Session timeout | Your session has timed out. | | 4011 | Server not found | We can't find the server you're trying to connect to. | diff --git a/docs/topics/RPC.md b/docs/topics/RPC.md index 5b4da72f1d..db3117e873 100644 --- a/docs/topics/RPC.md +++ b/docs/topics/RPC.md @@ -998,7 +998,7 @@ Used to update a user's Rich Presence. | Field | Type | Description | |----------|----------------------------------------------------------------|-----------------------------------------| | pid | integer | the application's process id | -| activity | [activity](#DOCS_TOPICS_GATEWAY_EVENTS/activity-object) object | the rich presence to assign to the user | +| activity | [activity](#DOCS_EVENTS_GATEWAY_EVENTS/activity-object) object | the rich presence to assign to the user | ###### Example Set Activity Payload diff --git a/docs/topics/Threads.md b/docs/topics/Threads.md index 05f3126ac4..816489a802 100644 --- a/docs/topics/Threads.md +++ b/docs/topics/Threads.md @@ -6,7 +6,7 @@ Threads have been designed to be very similar to [channel](#DOCS_RESOURCES_CHANN ## Backwards Compatibility -Threads are only available in API v9 and above. Bots that do not update to API v9 or above will not receive most gateway events for threads, or things that happen in threads (such as [Message Create](#DOCS_TOPICS_GATEWAY_EVENTS/message-create)). Bots on API v8 will still receive gateway events for Interactions. +Threads are only available in API v9 and above. Bots that do not update to API v9 or above will not receive most gateway events for threads, or things that happen in threads (such as [Message Create](#DOCS_EVENTS_GATEWAY_EVENTS/message-create)). Bots on API v8 will still receive gateway events for Interactions. The list of gateway events that may be dropped includes, but is not limited to: @@ -76,9 +76,9 @@ Finally, threads are treated slightly differently from channels in the gateway p ## Gateway Events -- [Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) contains a field, `threads`, which is an array of channel objects. This represents all active threads in the guild that the current user is able to view. -- When a thread is created, updated, or deleted, a [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create), [Thread Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-update), or [Thread Delete](#DOCS_TOPICS_GATEWAY_EVENTS/thread-delete) event is sent. Like their channel counterparts, these just contain a thread. -- Since the gateway only syncs active threads that the user can see, if a user _gains_ access to a channel, then the gateway may need to sync the active threads in that channel to the user. It will send a [Thread List Sync](#DOCS_TOPICS_GATEWAY_EVENTS/thread-list-sync) event for this. +- [Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) contains a field, `threads`, which is an array of channel objects. This represents all active threads in the guild that the current user is able to view. +- When a thread is created, updated, or deleted, a [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create), [Thread Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-update), or [Thread Delete](#DOCS_EVENTS_GATEWAY_EVENTS/thread-delete) event is sent. Like their channel counterparts, these just contain a thread. +- Since the gateway only syncs active threads that the user can see, if a user _gains_ access to a channel, then the gateway may need to sync the active threads in that channel to the user. It will send a [Thread List Sync](#DOCS_EVENTS_GATEWAY_EVENTS/thread-list-sync) event for this. ## Thread Membership @@ -91,20 +91,20 @@ Membership is tracked in an array of [thread member](#DOCS_RESOURCES_CHANNEL/thr ### Syncing for the current user -- A [Thread Members Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-members-update) Gateway Event is always sent when the current user is added to or removed from a thread. -- A [Thread Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-member-update) Gateway Event is sent whenever the current user's [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object is updated. +- A [Thread Members Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-members-update) Gateway Event is always sent when the current user is added to or removed from a thread. +- A [Thread Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-member-update) Gateway Event is sent whenever the current user's [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object is updated. - Certain API calls, such as listing archived threads and search will return an array of [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) objects for any returned threads the current user is a member of. Other API calls, such as getting a channel will return the [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object for the current user as a property on the channel, if the current user is a member of the thread. -- The [Guild Create](#DOCS_TOPICS_GATEWAY_EVENTS/guild-create) Gateway Event will contain a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object as a property on any returned threads the current is a member of. -- The [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) Gateway Event will contain a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object as a property of the thread if the current user is a member of, and the user has recently gained access to view the parent channel. -- The [Thread List Sync](#DOCS_TOPICS_GATEWAY_EVENTS/thread-list-sync) Gateway Event will contain an array of [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) objects for any returned threads the current user is a member of. +- The [Guild Create](#DOCS_EVENTS_GATEWAY_EVENTS/guild-create) Gateway Event will contain a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object as a property on any returned threads the current is a member of. +- The [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create) Gateway Event will contain a [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) object as a property of the thread if the current user is a member of, and the user has recently gained access to view the parent channel. +- The [Thread List Sync](#DOCS_EVENTS_GATEWAY_EVENTS/thread-list-sync) Gateway Event will contain an array of [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) objects for any returned threads the current user is a member of. ### Syncing for other users > info -> These require the `GUILD_MEMBERS` [Gateway Intent](#DOCS_TOPICS_GATEWAY/gateway-intents) +> These require the `GUILD_MEMBERS` [Gateway Intent](#DOCS_EVENTS_GATEWAY/gateway-intents) - An API `GET` call to [`/channels//thread-members`](#DOCS_RESOURCES_CHANNEL/list-thread-members) which returns an array of [thread member](#DOCS_RESOURCES_CHANNEL/thread-member-object) objects. -- The [Thread Members Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-members-update) Gateway Event which will include all users who were added to or removed from a thread by an action. +- The [Thread Members Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-members-update) Gateway Event which will include all users who were added to or removed from a thread by an action. ## Editing & Deleting Threads @@ -143,9 +143,9 @@ Webhooks can send messages to threads by using the `thread_id` query parameter. ## Details about Thread Access and Syncing -While the syncing of threads is similar to channels, there are two important differences that are relevant for [Thread List Sync](#DOCS_TOPICS_GATEWAY_EVENTS/thread-list-sync) and [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) events: +While the syncing of threads is similar to channels, there are two important differences that are relevant for [Thread List Sync](#DOCS_EVENTS_GATEWAY_EVENTS/thread-list-sync) and [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create) events: -1. The [Gateway](#DOCS_TOPICS_GATEWAY) will only sync threads that the app has permission to view +1. The [Gateway](#DOCS_EVENTS_GATEWAY) will only sync threads that the app has permission to view 2. The Gateway will only sync threads once the app has "subscribed" to the guild. For context, in Discord's official clients, a subscription happens when the user visits a channel in the guild. These differences mean there is some unique behavior that is worth going into. @@ -156,7 +156,7 @@ These differences mean there is some unique behavior that is worth going into. When an app is added to a private thread, it likely doesn't have that thread in memory yet since it doesn't have permission to view it. -Private threads are only synced to you if you are a member or a moderator. Whenever a user is added to a private thread, the Gateway also sends a [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) event. This ensures the client always has a non-null value for that thread. +Private threads are only synced to you if you are a member or a moderator. Whenever a user is added to a private thread, the Gateway also sends a [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create) event. This ensures the client always has a non-null value for that thread. > info > The `THREAD_CREATE` event is also sent when the user is a moderator (and thus would already have the channel in memory). @@ -165,33 +165,33 @@ Private threads are only synced to you if you are a member or a moderator. Whene Upon connecting to the Gateway, apps will be automatically subscribed to thread events and active threads. -However, when a non-app is added to a public thread but hasn't subscribed to threads, it may not have that thread in memory yet (which is a requirement for Discord's clients). Because of this, the Gateway will send a [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) event when a user is added to _any_ thread, even if the event is not necessary for apps. +However, when a non-app is added to a public thread but hasn't subscribed to threads, it may not have that thread in memory yet (which is a requirement for Discord's clients). Because of this, the Gateway will send a [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create) event when a user is added to _any_ thread, even if the event is not necessary for apps. ### Channel Access #### Gaining Access to Channels -When an app gains access to a channel (for example, they're given the moderator role), they likely won't have the threads in memory for that channel since the Gateway only syncs threads that the client has permission to view. To account for this, a [Thread List Sync](#DOCS_TOPICS_GATEWAY_EVENTS/thread-list-sync) event is sent. +When an app gains access to a channel (for example, they're given the moderator role), they likely won't have the threads in memory for that channel since the Gateway only syncs threads that the client has permission to view. To account for this, a [Thread List Sync](#DOCS_EVENTS_GATEWAY_EVENTS/thread-list-sync) event is sent. -The [Thread List Sync](#DOCS_TOPICS_GATEWAY_EVENTS/thread-list-sync) event contains a `channel_ids` array, which is the IDs of all channels whose threads are being synced. This field can be used to first clear out any active threads whose `parent_id` is in the `channel_ids` array, and then ingest any threads that were in the event. +The [Thread List Sync](#DOCS_EVENTS_GATEWAY_EVENTS/thread-list-sync) event contains a `channel_ids` array, which is the IDs of all channels whose threads are being synced. This field can be used to first clear out any active threads whose `parent_id` is in the `channel_ids` array, and then ingest any threads that were in the event. #### Losing Access to Channels -When an app loses access to a channel, the Gateway does **not** send it [Thread Delete](#DOCS_TOPICS_GATEWAY_EVENTS/thread-delete) event (or any equivalent thread-specific event). Instead, the app will receive the event that caused its permissions on the channel to change. +When an app loses access to a channel, the Gateway does **not** send it [Thread Delete](#DOCS_EVENTS_GATEWAY_EVENTS/thread-delete) event (or any equivalent thread-specific event). Instead, the app will receive the event that caused its permissions on the channel to change. -If an app wanted to track when it lost access to any thread, it's possible but difficult as it would need to handle all cases correctly. Usually, events that cause permission changes are a [Guild Role Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-role-update), [Guild Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/guild-member-update) or [Channel Update](#DOCS_TOPICS_GATEWAY_EVENTS/channel-update) event. +If an app wanted to track when it lost access to any thread, it's possible but difficult as it would need to handle all cases correctly. Usually, events that cause permission changes are a [Guild Role Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-role-update), [Guild Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/guild-member-update) or [Channel Update](#DOCS_EVENTS_GATEWAY_EVENTS/channel-update) event. > info > Discord's clients check their permissions *first* when performing an action. That way, even if it has some stale data, it does not end up acting on it. -Additionally, when a user or app loses access to a channel, they are not removed from the thread and will continue to be reported as a member of that thread. However, they will **not** receive any new Gateway events unless they are removed from the thread, in which case they will receive a [Thread Members Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-members-update) event. +Additionally, when a user or app loses access to a channel, they are not removed from the thread and will continue to be reported as a member of that thread. However, they will **not** receive any new Gateway events unless they are removed from the thread, in which case they will receive a [Thread Members Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-members-update) event. ### Unarchiving a Thread When a thread is unarchived, there is no guarantee that an app has the thread or its member status in memory. To account for this, the Gateway will send two events (in the listed order): -1. A [Thread Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-update) event, which contains the full channel object. -2. A [Thread Member Update](#DOCS_TOPICS_GATEWAY_EVENTS/thread-member-update) event, which is sent to all members of the unarchived thread. Discord's clients only load active threads into memory on start, so this event is sent even if it may not be relevant to most apps. +1. A [Thread Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-update) event, which contains the full channel object. +2. A [Thread Member Update](#DOCS_EVENTS_GATEWAY_EVENTS/thread-member-update) event, which is sent to all members of the unarchived thread. Discord's clients only load active threads into memory on start, so this event is sent even if it may not be relevant to most apps. ## Forums @@ -220,7 +220,7 @@ Threads in thread-only channels have the same permissions behavior as threads in It's worth calling out a few details about fields specific to thread-only channels that may be important to keep in mind: -- The `last_message_id` field is the ID of the most recently created thread in that channel. As with messages, your app will not receive a `CHANNEL_UPDATE` event when the field is changed. Instead clients should update the value when receiving [Thread Create](#DOCS_TOPICS_GATEWAY_EVENTS/thread-create) events. +- The `last_message_id` field is the ID of the most recently created thread in that channel. As with messages, your app will not receive a `CHANNEL_UPDATE` event when the field is changed. Instead clients should update the value when receiving [Thread Create](#DOCS_EVENTS_GATEWAY_EVENTS/thread-create) events. - The `topic` field is what is shown in the "Guidelines" section within the Discord client. - The `rate_limit_per_user` field limits how frequently threads can be created. There is a new `default_thread_rate_limit_per_user` field on thread-only channels as well, which limits how often messages can be sent _in a thread_. This field is copied into `rate_limit_per_user` on the thread at creation time. - The `available_tags` field can be set when creating or updating a channel, which determines which tags can be set on individual threads within the thread's `applied_tags` field. diff --git a/docs/topics/Voice_Connections.mdx b/docs/topics/Voice_Connections.mdx index bc8a4f4008..957c2d0946 100644 --- a/docs/topics/Voice_Connections.mdx +++ b/docs/topics/Voice_Connections.mdx @@ -1,6 +1,6 @@ # Voice -Voice connections operate in a similar fashion to the [Gateway](#DOCS_TOPICS_GATEWAY) connection. However, they use a different set of payloads and a separate UDP-based connection for voice data transmission. Because UDP is used for both receiving and transmitting voice data, your client _must_ be able to receive UDP packets, even through a firewall or NAT (see [UDP Hole Punching](https://en.wikipedia.org/wiki/UDP_hole_punching) for more information). The Discord Voice servers implement functionality (see [IP Discovery](#DOCS_TOPICS_VOICE_CONNECTIONS/ip-discovery)) for discovering the local machines remote UDP IP/Port, which can assist in some network configurations. +Voice connections operate in a similar fashion to the [Gateway](#DOCS_EVENTS_GATEWAY) connection. However, they use a different set of payloads and a separate UDP-based connection for voice data transmission. Because UDP is used for both receiving and transmitting voice data, your client _must_ be able to receive UDP packets, even through a firewall or NAT (see [UDP Hole Punching](https://en.wikipedia.org/wiki/UDP_hole_punching) for more information). The Discord Voice servers implement functionality (see [IP Discovery](#DOCS_TOPICS_VOICE_CONNECTIONS/ip-discovery)) for discovering the local machines remote UDP IP/Port, which can assist in some network configurations. ## Voice Gateway Versioning @@ -28,7 +28,7 @@ Previously if the version query string `v` was omitted the voice gateway would d ### Retrieving Voice Server Information -The first step in connecting to a voice server (and in turn, a guild's voice channel) is formulating a request that can be sent to the [Gateway](#DOCS_TOPICS_GATEWAY), which will return information about the voice server we will connect to. Because Discord's voice platform is widely distributed, users **should never** cache or save the results of this call. To inform the gateway of our intent to establish voice connectivity, we first send an [Opcode 4 Gateway Voice State Update](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway): +The first step in connecting to a voice server (and in turn, a guild's voice channel) is formulating a request that can be sent to the [Gateway](#DOCS_EVENTS_GATEWAY), which will return information about the voice server we will connect to. Because Discord's voice platform is widely distributed, users **should never** cache or save the results of this call. To inform the gateway of our intent to establish voice connectivity, we first send an [Opcode 4 Gateway Voice State Update](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/gateway): ###### Gateway Voice State Update Example @@ -44,7 +44,7 @@ The first step in connecting to a voice server (and in turn, a guild's voice cha } ``` -If our request succeeded, the gateway will respond with _two_ events—a [Voice State Update](#DOCS_TOPICS_GATEWAY_EVENTS/voice-state-update) event and a [Voice Server Update](#DOCS_TOPICS_GATEWAY_EVENTS/voice-server-update) event—meaning your library must properly wait for both events before continuing. The first will contain a new key, `session_id`, and the second will provide voice server information we can use to establish a new voice connection: +If our request succeeded, the gateway will respond with _two_ events—a [Voice State Update](#DOCS_EVENTS_GATEWAY_EVENTS/voice-state-update) event and a [Voice Server Update](#DOCS_EVENTS_GATEWAY_EVENTS/voice-server-update) event—meaning your library must properly wait for both events before continuing. The first will contain a new key, `session_id`, and the second will provide voice server information we can use to establish a new voice connection: ###### Example Voice Server Update Payload @@ -72,7 +72,7 @@ When sending a voice state update to change channels within the same guild, it i ## Establishing a Voice Websocket Connection -Once we retrieve a session_id, token, and endpoint information, we can connect and handshake with the voice server over another secure WebSocket. Unlike the gateway endpoint we receive in an HTTP [Get Gateway](#DOCS_TOPICS_GATEWAY/get-gateway) request, the endpoint received from our [Voice Server Update](#DOCS_TOPICS_GATEWAY_EVENTS/voice-server-update) payload does not contain a URL protocol, so some libraries may require manually prepending it with "wss://" before connecting. Once connected to the voice WebSocket endpoint, we can send an [Opcode 0 Identify](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/voice) payload with our server_id, user_id, session_id, and token: +Once we retrieve a session_id, token, and endpoint information, we can connect and handshake with the voice server over another secure WebSocket. Unlike the gateway endpoint we receive in an HTTP [Get Gateway](#DOCS_EVENTS_GATEWAY/get-gateway) request, the endpoint received from our [Voice Server Update](#DOCS_EVENTS_GATEWAY_EVENTS/voice-server-update) payload does not contain a URL protocol, so some libraries may require manually prepending it with "wss://" before connecting. Once connected to the voice WebSocket endpoint, we can send an [Opcode 0 Identify](#DOCS_TOPICS_OPCODES_AND_STATUS_CODES/voice) payload with our server_id, user_id, session_id, and token: ###### Example Voice Identify Payload diff --git a/docs/tutorials/Developing_a_User_Installable_App.mdx b/docs/tutorials/Developing_a_User_Installable_App.mdx index 3aa5516144..9c5c9f07f8 100644 --- a/docs/tutorials/Developing_a_User_Installable_App.mdx +++ b/docs/tutorials/Developing_a_User_Installable_App.mdx @@ -83,7 +83,7 @@ Now that you have the credentials you need, we'll configure your app to support ### Add Guild Members intent -The sample app fetches members in the server when constructing a fake game leaderboard. Getting server members requires a special permission called a [privileged intent](#DOCS_TOPICS_GATEWAY/privileged-intents), so we'll add that to our app. +The sample app fetches members in the server when constructing a fake game leaderboard. Getting server members requires a special permission called a [privileged intent](#DOCS_EVENTS_GATEWAY/privileged-intents), so we'll add that to our app. Go to the **Bot** page and find the **Privileged Gateway Intents** section. Toggle "Server Member Intent" to be active. diff --git a/docs/tutorials/Upgrading_to_Application_Commands.md b/docs/tutorials/Upgrading_to_Application_Commands.md index 2a4b1cddde..36beb10e11 100644 --- a/docs/tutorials/Upgrading_to_Application_Commands.md +++ b/docs/tutorials/Upgrading_to_Application_Commands.md @@ -128,17 +128,17 @@ Permissions for specific roles, users, and channels can be updated by your app i ## Handling Commands -Commands use the [interactions model](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING) through HTTP-based outgoing webhooks or the WebSocket-based [Interaction Create gateway event](#DOCS_TOPICS_GATEWAY_EVENTS/interaction-create). Regardless of the transit method used to arrive, your app will receive relevant information when a Discord user triggers one of your app’s interactions. +Commands use the [interactions model](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING) through HTTP-based outgoing webhooks or the WebSocket-based [Interaction Create gateway event](#DOCS_EVENTS_GATEWAY_EVENTS/interaction-create). Regardless of the transit method used to arrive, your app will receive relevant information when a Discord user triggers one of your app’s interactions. > warn -> If you continue using Gateway events, you’ll still receive message events but the payloads will have empty string or array data for message content-related fields like `content`, `embeds`, `attachments`, and `components` while `poll` will be omitted. You can read more in the [message content intent](#DOCS_TOPICS_GATEWAY/message-content-intent) section. +> If you continue using Gateway events, you’ll still receive message events but the payloads will have empty string or array data for message content-related fields like `content`, `embeds`, `attachments`, and `components` while `poll` will be omitted. You can read more in the [message content intent](#DOCS_EVENTS_GATEWAY/message-content-intent) section. For commands, this means that each time one of your commands is used, your app will receive information like the command name and the user who triggered it. More information about this information is below in the section on [parsing command payloads](#DOCS_TUTORIALS_UPGRADING_TO_APPLICATION_COMMANDS/parsing-command-payloads). ### Adding an Interactions Endpoint URL > info -> This step is specific to receiving interactions over HTTP. If you prefer to use the [Gateway](#DOCS_TOPICS_GATEWAY), this step won't be applicable to your app. +> This step is specific to receiving interactions over HTTP. If you prefer to use the [Gateway](#DOCS_EVENTS_GATEWAY), this step won't be applicable to your app. Before your app can receive interactions, you’ll need to set up an **Interaction Endpoint URL** in your app settings. This endpoint should be a public URL where Discord can send all interactions-related requests.