Skip to content

Commit a7dfd25

Browse files
PakjeBecelPakjeBecel
authored
Updated "Message" and "Webhook" resource page and "Using Message Components" page with the new components v2 behaviour (#7507)
* docs: update allowed mentions object section Updated the section with the new components v2 behaviour. * docs: update create message and edit message section Updated both sections with the new components v2 behaviour. * docs: update sending a message with a component section Added a warning alert box to make users aware of the "IS_COMPONENTS_V2" message flag being irreversible when set to a message. * docs: update execute webhook and edit webhook message section Updated both desction with the new components v2 behaviour. * docs: update edit message section Updated the section with the asterisk being moved from the "flags" description to the "flags" field. Removed one of the asterisks since only one was present inside the table. * fix: reverted change to avoid conflicts with #7508 * fixed table
1 parent a652e40 commit a7dfd25

File tree

3 files changed

+58
-45
lines changed

3 files changed

+58
-45
lines changed

‎docs/components/using-message-components.mdx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ If you are sending components as part of a [webhook](/docs/resources/webhook) yo
2424

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

27+
:::warn
28+
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.
29+
:::
30+
2731
This flag indicates that the message contains components and disables traditional content and embeds.
2832

2933
All content must be sent as components instead of using the standard message format.

‎docs/resources/message.mdx

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -648,7 +648,7 @@ The allowed mention field allows for more granular control over mentions without
648648

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

651-
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.
651+
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.
652652

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

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

714-
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.
714+
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.
715715
e.g. The following example is valid, and would mention user 123, but _not_ user 125 since there is no mention of
716716
user 125 in the content.
717717

@@ -806,12 +806,14 @@ When creating a message, apps must provide a value for **at least one of** `cont
806806
| files[n]?\* | file contents | Contents of the file being sent. See [Uploading Files](/docs/reference#uploading-files) |
807807
| payload_json? | string | JSON-encoded body of non-file params, only for `multipart/form-data` requests. See [Uploading Files](/docs/reference#uploading-files) |
808808
| attachments? | array of partial [attachment](/docs/resources/message#attachment-object) objects | Attachment objects with filename and description. See [Uploading Files](/docs/reference#uploading-files) |
809-
| 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) |
809+
| 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) |
810810
| 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. |
811811
| poll? | [poll](/docs/resources/poll#poll-create-request-object) request object | A poll! |
812812

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

815+
\*\* 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.
816+
815817
###### Example Request Body (application/json)
816818

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

890-
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).
892+
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).
891893

892-
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.
894+
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.
893895

894896
Returns a [message](/docs/resources/message#message-object) object. Fires a [Message Update](/docs/events/gateway-events#message-update) Gateway event.
895897

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

907909
###### JSON/Form Params
908910

909-
| Field | Type | Description |
910-
|------------------|---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
911-
| content | string | Message contents (up to 2000 characters) |
912-
| embeds | array of [embed](/docs/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) |
913-
| flags | integer | Edit the [flags](/docs/resources/message#message-object-message-flags) of a message (only `SUPPRESS_EMBEDS` can currently be set/unset) |
914-
| allowed_mentions | [allowed mention object](/docs/resources/message#allowed-mentions-object) | Allowed mentions for the message |
915-
| components | array of [message component](/docs/components/reference#component-object) | Components to include with the message |
916-
| files[n] | file contents | Contents of the file being sent/edited. See [Uploading Files](/docs/reference#uploading-files) |
917-
| payload_json | string | JSON-encoded body of non-file params (multipart/form-data only). See [Uploading Files](/docs/reference#uploading-files) |
918-
| 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) |
911+
| Field | Type | Description |
912+
|------------------|---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
913+
| content | string | Message contents (up to 2000 characters) |
914+
| embeds | array of [embed](/docs/resources/message#embed-object) objects | Up to 10 `rich` embeds (up to 6000 characters) |
915+
| flags\* | integer | Edit the [flags](/docs/resources/message#message-object-message-flags) of a message (`SUPPRESS_EMBEDS` and `IS_COMPONENTS_V2` only) |
916+
| allowed_mentions | [allowed mention object](/docs/resources/message#allowed-mentions-object) | Allowed mentions for the message |
917+
| components | array of [message component](/docs/components/reference#component-object) | Components to include with the message |
918+
| files[n] | file contents | Contents of the file being sent/edited. See [Uploading Files](/docs/reference#uploading-files) |
919+
| payload_json | string | JSON-encoded body of non-file params (multipart/form-data only). See [Uploading Files](/docs/reference#uploading-files) |
920+
| 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) |
921+
922+
\* 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.
919923

920924
## Delete Message
921925
<Route method="DELETE">/channels/[\{channel.id\}](/docs/resources/channel#channel-object)/messages/[\{message.id\}](/docs/resources/message#message-object)</Route>

0 commit comments

Comments
 (0)