Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Webhook Events documentation #7233

Merged
merged 28 commits into from
Oct 25, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/Reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion docs/change_log/2017-07-19-breaking-change-version-6.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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.
14 changes: 7 additions & 7 deletions docs/change_log/2020-02-14-gateway-intents.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Original file line number Diff line number Diff line change
Expand Up @@ -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.
8 changes: 4 additions & 4 deletions docs/change_log/2020-09-24-api-and-gateway-v8.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,18 @@ 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`.
* `embed_enabled` and `embed_channel_id` have been removed. Use `widget_enabled` and `widget_channel_id` instead.
* 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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
2 changes: 1 addition & 1 deletion docs/change_log/2020-11-16-inline-replies.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion docs/change_log/2022-02-14-api-v10.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 2 additions & 2 deletions docs/change_log/2022-06-16-auto-moderation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Loading