Skip to content

Updated "Message" and "Webhook" resource page and "Using Message Components" page with the new components v2 behaviour #7507

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.

Sign up for GitHub

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

Merged
merged 7 commits into from
May 12, 2025
Merged

Updated "Message" and "Webhook" resource page and "Using Message Components" page with the new components v2 behaviour #7507

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
941d359
docs: update allowed mentions object section
PakjeBecel Apr 23, 2025
e1fe800
docs: update create message and edit message section
PakjeBecel Apr 23, 2025
8549d83
docs: update sending a message with a component section
PakjeBecel Apr 23, 2025
fbbbbf3
docs: update execute webhook and edit webhook message section
PakjeBecel Apr 24, 2025
93d7d0e
docs: update edit message section
PakjeBecel Apr 24, 2025
7702e7f
fix: reverted change to avoid conflicts with #7508
PakjeBecel Apr 24, 2025
987e3e7
fixed table
PakjeBecel May 12, 2025
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: 5 additions & 1 deletion docs/components/using-message-components.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@ If you are sending components as part of a [webhook](/docs/resources/webhook) yo

To send a message with a component, you need to set the `IS_COMPONENTS_V2` flag (`1<<15`) in your message's `flags` field. This can be done when using [Message Create](/docs/resources/message#create-message), [Execute Webhook](/docs/resources/webhook#execute-webhook), or [responding to an interaction](/docs/interactions/receiving-and-responding#create-followup-message).

:::warn
Setting the `IS_COMPONENTS_V2` message flag cannot be reverted: once the message has been sent, the flag cannot be removed from the message when editing the message.
:::

This flag indicates that the message contains components and disables traditional content and embeds.

All content must be sent as components instead of using the standard message format.
Expand Down Expand Up @@ -103,4 +107,4 @@ See the [list of supported component types](/docs/components/reference#component

You can use this information to respond to the interaction, update the message, or perform other actions, such as displaying a modal based on the user's input.

Check out the [Interactions documentation](/docs/interactions/overview) for more information on handling interactions and responding to user input from interactive components.
Check out the [Interactions documentation](/docs/interactions/overview) for more information on handling interactions and responding to user input from interactive components.
36 changes: 20 additions & 16 deletions docs/resources/message.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -625,7 +625,7 @@ For the `attachments` array in Message Create/Edit requests, only the `id` is re

### Allowed Mentions Object

The allowed mention field allows for more granular control over mentions without various hacks to the message content. This will always validate against message content to avoid phantom pings (e.g. to ping everyone, you must still have `@everyone` in the message content), and check against user/bot permissions.
The allowed mention field allows for more granular control over mentions without various hacks to the message. This will always validate against the message and components to avoid phantom pings (e.g. to ping everyone, you must still have `@everyone` in the message), and check against user/bot permissions.

###### Allowed Mention Types

Expand All @@ -648,7 +648,7 @@ The allowed mention field allows for more granular control over mentions without

Due to the complexity of possibilities, we have included a set of examples and behavior for the allowed mentions field.

If `allowed_mentions` is _not_ passed in (i.e. the key does not exist), the mentions will be parsed via the content. This corresponds with existing behavior.
If `allowed_mentions` is _not_ passed in (i.e. the key does not exist), the mentions will be parsed via the message content or message component content. This corresponds with existing behavior.

In the example below we would ping @here (and also @role124 and @user123)

Expand Down Expand Up @@ -711,7 +711,7 @@ Due to possible ambiguities, not all configurations are valid. An _invalid_ conf
Because `parse: ["users"]` and `users: [123, 124]` are both present, we would throw a validation error.
This is because the conditions cannot be fulfilled simultaneously (they are mutually exclusive).

Any entities with an ID included in the list of IDs can be mentioned. Note that the IDs of entities not present in the message's content will simply be ignored.
Any entities with an ID included in the list of IDs can be mentioned. Note that the IDs of entities not present in the message content or message component content will simply be ignored.
e.g. The following example is valid, and would mention user 123, but _not_ user 125 since there is no mention of
user 125 in the content.

Expand Down Expand Up @@ -806,12 +806,14 @@ When creating a message, apps must provide a value for **at least one of** `cont
| files[n]?\* | file contents | Contents of the file being sent. See [Uploading Files](/docs/reference#uploading-files) |
| payload_json? | string | JSON-encoded body of non-file params, only for `multipart/form-data` requests. See [Uploading Files](/docs/reference#uploading-files) |
| attachments? | array of partial [attachment](/docs/resources/message#attachment-object) objects | Attachment objects with filename and description. See [Uploading Files](/docs/reference#uploading-files) |
| flags? | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS` and `SUPPRESS_NOTIFICATIONS` can be set) |
| flags?\*\* | integer | [Message flags](/docs/resources/message#message-object-message-flags) combined as a [bitfield](https://en.wikipedia.org/wiki/Bit_field) (only `SUPPRESS_EMBEDS`, `SUPPRESS_NOTIFICATIONS` and `IS_COMPONENTS_V2` can be set) |
| enforce_nonce? | boolean | If true and nonce is present, it will be checked for uniqueness in the past few minutes. If another message was created by the same author with the same nonce, that message will be returned and no new message will be created. |
| poll? | [poll](/docs/resources/poll#poll-create-request-object) request object | A poll! |

\* At least one of `content`, `embeds`, `sticker_ids`, `components`, `files[n]`, or `poll` is required.

\*\* When the flag `IS_COMPONENTS_V2` is set, the message can only contain `components`. Providing `content`, `embeds`, `sticker_ids`, `files[n]`, or `poll` will fail with a 400 BAD REQUEST response.

###### Example Request Body (application/json)

```json
Expand Down Expand Up @@ -887,9 +889,9 @@ The `emoji` must be [URL Encoded](https://en.wikipedia.org/wiki/Percent-encoding
## Edit Message
<Route type="PATCH">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/[\{message.id\}](/docs/resources/message#message-object)</Route>

Edit a previously sent message. The fields `content`, `embeds`, and `flags` can be edited by the original message author. Other users can only edit `flags` and only if they have the `MANAGE_MESSAGES` permission in the corresponding channel. When specifying flags, ensure to include all previously set flags/bits in addition to ones that you are modifying. Only `flags` documented in the table below may be modified by users (unsupported flag changes are currently ignored without error).
Edit a previously sent message. The fields `content`, `embeds`, `flags` and `components` can be edited by the original message author. Other users can only edit `flags` and only if they have the `MANAGE_MESSAGES` permission in the corresponding channel. When specifying flags, ensure to include all previously set flags/bits in addition to ones that you are modifying. Only `flags` documented in the table below may be modified by users (unsupported flag changes are currently ignored without error).

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.
When the `content` field is edited, the arrays `mentions` and `mention_roles` and the boolean `mention_everyone` in the message object will be reconstructed from scratch based on the new content. When the message flag `IS_COMPONENTS_V2` is set, the reconstructed arrays and boolean are based on the edited content in the `components` array. 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/events/gateway-events#message-update) Gateway event.

Expand All @@ -906,16 +908,18 @@ All parameters to this endpoint are optional and nullable.

###### JSON/Form Params

| Field | Type | Description |
|------------------|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| content | string | Message contents (up to 2000 characters) |
| embeds | array of [embed](/docs/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) |
| flags | integer | Edit the [flags](/docs/resources/message#message-object-message-flags) of a message (only `SUPPRESS_EMBEDS` can currently be set/unset) |
| allowed_mentions | [allowed mention object](/docs/resources/message#allowed-mentions-object) | Allowed mentions for the message |
| components | array of [message component](/docs/components/reference#component-object) | Components to include with the message |
| files[n] | file contents | Contents of the file being sent/edited. See [Uploading Files](/docs/reference#uploading-files) |
| payload_json | string | JSON-encoded body of non-file params (multipart/form-data only). See [Uploading Files](/docs/reference#uploading-files) |
| attachments | array of [attachment](/docs/resources/message#attachment-object) objects | Attached files to keep and possible descriptions for new files. See [Uploading Files](/docs/reference#uploading-files) |
| Field | Type | Description |
|------------------|---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| content | string | Message contents (up to 2000 characters) |
| embeds | array of [embed](/docs/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) |
| flags\* | integer | Edit the [flags](/docs/resources/message#message-object-message-flags) of a message (`SUPPRESS_EMBEDS` and `IS_COMPONENTS_V2` only) |
| allowed_mentions | [allowed mention object](/docs/resources/message#allowed-mentions-object) | Allowed mentions for the message |
| components | array of [message component](/docs/components/reference#component-object) | Components to include with the message |
| files[n] | file contents | Contents of the file being sent/edited. See [Uploading Files](/docs/reference#uploading-files) |
| payload_json | string | JSON-encoded body of non-file params (multipart/form-data only). See [Uploading Files](/docs/reference#uploading-files) |
| attachments | array of [attachment](/docs/resources/message#attachment-object) objects | Attached files to keep and possible descriptions for new files. See [Uploading Files](/docs/reference#uploading-files) |

\* The `SUPPRESS_EMBEDS` flag can be both set and unset, while the `IS_COMPONENTS_V2` flag can only be set. When the `IS_COMPONENTS_V2` flag is set, any of the used `content`, `embeds`, `sticker_ids`, `files[n]` or `poll` values in the initial message must be set to `null` first, otherwise it will fail with a 400 BAD REQUEST response.

## Delete Message
<Route type="DELETE">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/[\{message.id\}](/docs/resources/message#message-object)</Route>
Expand Down
Loading