From 2f1ad9f8312d8804515c44b0033ffc391737a660 Mon Sep 17 00:00:00 2001 From: Suspense <64612795+AlmostSuspense@users.noreply.github.com> Date: Sun, 22 Jun 2025 15:23:38 +0200 Subject: [PATCH 1/7] add caveat for allowed mentions in interactions --- docs/resources/message.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index c14c9351a6..61ee1248e7 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -650,9 +650,9 @@ 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 message content or message component content. This corresponds with existing behavior. +If the `allowed_mentions` field is not passed in the body, mentions will be parsed based on the content of the message and its components, except in interactions, where only user mentions are parsed by default. You will need to configure `allowed_mentions` in order to ping `@everyone`, `@here` or roles. -In the example below we would ping @here (and also @role124 and @user123) +In the example below, we would ping @here (and also @role124 and @user123): ```json { From c2eb6d10136cc29b938fc0caedfa6952150b425e Mon Sep 17 00:00:00 2001 From: Suspense <64612795+AlmostSuspense@users.noreply.github.com> Date: Tue, 24 Jun 2025 12:39:15 +0200 Subject: [PATCH 2/7] =?UTF-8?q?deeper=20rewrite=20of=20allowed=20mentions?= =?UTF-8?q?=20docs=20=F0=9F=A4=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/resources/message.mdx | 83 ++++++++++++++++++++++++-------------- 1 file changed, 52 insertions(+), 31 deletions(-) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index 61ee1248e7..c0545b12b7 100644 --- a/docs/resources/message.mdx +++ b/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 red ping badge +- Users can customize their notification settings through the Discord app, which might cause them to only receive the red ping badge and no push notification + ###### Allowed Mention Types @@ -637,47 +643,65 @@ 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) | +| 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 | -###### Allowed Mentions Reference +###### Allowed Mentions Examples -Due to the complexity of possibilities, we have included a set of examples and behavior for the allowed mentions field. +Because the behavior of the `allowed_mentions` field is more complex than it seems, here's a set of examples: -If the `allowed_mentions` field is not passed in the body, mentions will be parsed based on the content of the message and its components, except in interactions, where only user mentions are parsed by default. You will need to configure `allowed_mentions` in order to ping `@everyone`, `@here` or roles. -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's members and the `5678` user mentions would be parsed, but **not** the `@here` at the beginning. Passing a `Falsy` value like `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": [] @@ -685,43 +709,40 @@ The `parse` field is mutually exclusive with the other fields. In the example be } ``` -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"] } } ``` From 6293354590a53e3c09c24fbe54c0f18eccf59cd9 Mon Sep 17 00:00:00 2001 From: Suspense <64612795+AlmostSuspense@users.noreply.github.com> Date: Tue, 24 Jun 2025 13:37:58 +0200 Subject: [PATCH 3/7] red ping -> notification --- docs/resources/message.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index c0545b12b7..8ec00cce39 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -630,9 +630,9 @@ For the `attachments` array in Message Create/Edit requests, only the `id` is re 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 red ping badge -- Users can customize their notification settings through the Discord app, which might cause them to only receive the red ping badge and no push notification +- 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 From 43173fcc57e928216e5f7248fd46adaa8ba19778 Mon Sep 17 00:00:00 2001 From: Suspense <64612795+AlmostSuspense@users.noreply.github.com> Date: Tue, 24 Jun 2025 19:56:38 +0200 Subject: [PATCH 4/7] Update message.mdx --- docs/resources/message.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index 8ec00cce39..7480faaa58 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -697,7 +697,7 @@ If you want to completely suppress all mentions in the message, you can configur ``` -It is important to note that the `parse` field is **mutually exclusive** with the other fields. In the example below, only the `1234` role's members and the `5678` user mentions would be parsed, but **not** the `@here` at the beginning. Passing a `Falsy` value like `null` or an empty array 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 { @@ -710,8 +710,7 @@ It is important to note that the `parse` field is **mutually exclusive** with th ``` -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. +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 { From f82f1a5ee3793b068e2e08231e46e86c20bc8a35 Mon Sep 17 00:00:00 2001 From: Suspense Date: Thu, 26 Jun 2025 19:19:42 +0200 Subject: [PATCH 5/7] fix spaces --- docs/resources/message.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index 7480faaa58..0836d7cb20 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -665,12 +665,12 @@ The default value for the `allowed_mentions` field, used when it is not passed i -| 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 | +| 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 | ###### Allowed Mentions Examples From 427c1bc9d6dc368c181bb9eefdae89f94ef0ae2f Mon Sep 17 00:00:00 2001 From: Suspense <64612795+AlmostSuspense@users.noreply.github.com> Date: Thu, 26 Jun 2025 19:53:40 +0200 Subject: [PATCH 6/7] Update docs/resources/message.mdx Co-authored-by: Mark Mandel --- docs/resources/message.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index 0836d7cb20..1e407c373f 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -647,7 +647,7 @@ Setting the `allowed_mentions` field lets you determine whether users will recei 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: +In **regular messages**, all mention types are parsed, which is equivalent to sending the following data: ```json { From 27584d20302d63f17673467edc3d616714677e15 Mon Sep 17 00:00:00 2001 From: Suspense <64612795+AlmostSuspense@users.noreply.github.com> Date: Thu, 26 Jun 2025 19:54:21 +0200 Subject: [PATCH 7/7] Update docs/resources/message.mdx Co-authored-by: Mark Mandel --- docs/resources/message.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/message.mdx b/docs/resources/message.mdx index 1e407c373f..bac120471f 100644 --- a/docs/resources/message.mdx +++ b/docs/resources/message.mdx @@ -655,7 +655,7 @@ In **regular messages**, all mention types are parsed, which is equivalent to se } ``` -- In **interactions** and **webhooks**, only user mentions are parsed, which corresponds to the following: +In **interactions** and **webhooks**, only user mentions are parsed, which corresponds to the following: ```json {