Add caveat for allowed_mentions in interactions (#7629)

* add caveat for allowed mentions in interactions

* deeper rewrite of allowed mentions docs 🤠

* red ping -> notification

* Update message.mdx

* fix spaces

* Update docs/resources/message.mdx

Co-authored-by: Mark Mandel <[email protected]>

* Update docs/resources/message.mdx

Co-authored-by: Mark Mandel <[email protected]>

---------

Co-authored-by: Mark Mandel <[email protected]>

Author: AlmostSuspense

docs/resources/message.mdx

@@ -627,7 +627,13 @@ 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. 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.
+Setting the `allowed_mentions` field lets you determine whether users will receive notifications when you include mentions in the message content, or the content of components attached to that message. This field is always validated against your permissions and the presence of said mentions in the message, to avoid "phantom" pings where users receive a notification without a visible mention in the message. For example, if you want to ping everyone, including it in the `allowed_mentions` field is not enough, the mention format (`@everyone`) must also be present in the content of the message or its components. It is important to note that setting this field **does not** guarantee a push notification will be sent, as additional factors can influence this:
+
+- To mention roles and notify their members, the role's `mentionable` field must be set to `true`, or the bot must have the `MENTION_EVERYONE` permission
+- To mention `@everyone` and `@here`, the bot must have the `MENTION_EVERYONE` permission
+- Setting the `SUPPRESS_NOTIFICATIONS` flag when sending a message will disable push notifications and only cause a notification badge
+- Users can customize their notification settings through the Discord app, which might cause them to only receive a notification badge and no push notification
+
 
 ###### Allowed Mention Types
 
@@ -637,91 +643,105 @@ The allowed mention field allows for more granular control over mentions without
 | User Mentions     | "users"    | Controls user mentions                |
 | Everyone Mentions | "everyone" | Controls @everyone and @here mentions |
 
-###### Allowed Mentions Structure
+###### Default Settings for Allowed Mentions
+
+The default value for the `allowed_mentions` field, used when it is not passed in the body, varies depending on the context:
+
+In **regular messages**, all mention types are parsed, which is equivalent to sending the following data:
+
+```json
+{
+  "parse": ["users", "roles", "everyone"]
+} 
+```
+
+In **interactions** and **webhooks**, only user mentions are parsed, which corresponds to the following:
+
+```json
+{
+  "parse": ["users"]
+} 
+```
+
 
-| Field         | Type                           | Description                                                                                                                           |
-|---------------|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
-| parse?        | array of allowed mention types | An array of [allowed mention types](/docs/resources/message#allowed-mentions-object-allowed-mention-types) to parse from the content. |
-| roles?        | list of snowflakes             | Array of role_ids to mention (Max size of 100)                                                                                        |
-| users?        | list of snowflakes             | Array of user_ids to mention (Max size of 100)                                                                                        |
-| replied_user? | boolean                        | For replies, whether to mention the author of the message being replied to (default false)                                            |
 
-###### Allowed Mentions Reference
+| Field         | Type                           | Description                                                                                                                          |
+|---------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| parse?        | array of allowed mention types | An array of [allowed mention types](/docs/resources/message#allowed-mentions-object-allowed-mention-types) to parse from the content |
+| roles?        | array of snowflakes            | Array of role ids to mention, max 100                                                                                                |
+| users?        | array of snowflakes            | Array of user ids to mention, max 100                                                                                                |
+| replied_user? | boolean                        | For replies, whether to mention the author of the message being replied to, defaults to false                                        |
 
-Due to the complexity of possibilities, we have included a set of examples and behavior for the allowed mentions field.
+###### Allowed Mentions Examples
 
-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.
+Because the behavior of the `allowed_mentions` field is more complex than it seems, here's a set of examples:
 
-In the example below we would ping @here (and also @role124 and @user123)
+
+In the following case, we are sending a regular message **without** configuring `allowed_mentions`. As a result, all included mentions will be parsed.
 
 ```json
 {
-  "content": "@here Hi there from <@123>, cc <@&124>"
+  "content": "@here Hello <@&1234> and <@5678> 👋"
 }
 ```
 
-To suppress all mentions in a message use:
+If you want to completely suppress all mentions in the message, you can configure the `allowed_mentions` field as we've documented above:
 
 ```json
 {
-  "content": "@everyone hi there, <@&123>",
+  "content": "@here Hello <@&1234> and <@5678> 👋",
   "allowed_mentions": {
     "parse": []
   }
 }
 ```
 
-This will suppress _all_ mentions in the message (no @everyone or user mention).
 
-The `parse` field is mutually exclusive with the other fields. In the example below, we would ping users `123` and role `124`, but _not_ @everyone. Note that passing a `Falsy` value ([], null) into the "users" field does not trigger a validation error.
+It is important to note that the `parse` field is **mutually exclusive** with the other fields. In the example below, only the `1234` role and the `5678` user mentions would be parsed, but **not** the `@here` at the beginning. Passing a falsy value such as `null` or an empty array into the `users` field does not trigger a validation error.
 
 ```json
 {
-  "content": "@everyone <@123> <@&124>",
+  "content": "@here Hello <@&1234> and <@5678> 👋",
   "allowed_mentions": {
     "parse": ["users", "roles"],
     "users": []
   }
 }
 ```
 
-In the next example, we would ping @everyone, (and also users `123` and `124` if they suppressed
-@everyone mentions), but we would not ping any roles.
+
+In this next example, **only** `@everyone` would be parsed, as well as users `1234` and `5678` in case they suppressed `@everyone` mentions in their settings.
 
 ```json
 {
-  "content": "@everyone <@123> <@124> <@125> <@&200>",
+  "content": "@everyone <@1234> <@5678> <@&789> 👋",
   "allowed_mentions": {
     "parse": ["everyone"],
-    "users": ["123", "124"]
+    "users": ["1234", "5678"]
   }
 }
 ```
 
-Due to possible ambiguities, not all configurations are valid. An _invalid_ configuration is as follows
+
+Due to possible ambiguities, not all configurations are accepted. Here's an example of an *invalid* configuration, because it includes both `parse` and `users`, despite those fields being mutually exclusive, causing a validation error.
 
 ```json
 {
-  "content": "@everyone <@123> <@124> <@125> <@&200>",
+  "content": "@everyone <@1234> <@5678> <@9012> <@&200>",
   "allowed_mentions": {
     "parse": ["users"],
-    "users": ["123", "124"]
+    "users": ["1234", "5678"]
   }
 }
 ```
 
-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 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.
+Any entities whose id is included can be mentioned. Do note the API will silently ignore entities whose id are present in the `allowed_mentions` field, but not in the content of the message or its components. For example, in the following configuration, the user 123 mention would be parsed because it is present in the `content`. However, since there is no mention of user 456 in the `content`, they would not be notified.
 
 ```json
 {
-  "content": "<@123> Time for some memes.",
+  "content": "<@123> Time for some memes 🤠",
   "allowed_mentions": {
-    "users": ["123", "125"]
+    "users": ["123", "456"]
   }
 }
 ```