Add caveat for allowed_mentions in interactions #7629
Conversation
docs/resources/message.mdx
Outdated
| @@ -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. | |||
There was a problem hiding this comment.
Thanks for this! I was also wondering about this, so I went and asked the eng team, because it's complicated apparently!
This is what I heard back (and I merged together into something a bit more actionable).
This change is correct but could be more explicit. I'd suggest reframing the documentation to better clarify the default behavior and scope.
Missing Context on Default Behavior:
We could make the documentation clearly explain that default allowed_mentions behavior varies by context, e.g.
-
Regular messages: If no
allowed_mentionsis provided, the default allows all mentions:{ "parse": ["users", "roles", "everyone"] } -
Webhooks and Interactions: By default, these only allow user mentions:
{ "parse": ["users"] }
Clarification Needed on Scope:
The documentation should also clarify that allowed_mentions defines what mentions are parsed for notification consideration, not what mentions will definitely trigger notifications. Whether a notification is actually sent depends on additional factors like permissions. The field controls what's allowed to be considered for triggering notifications, not guaranteed delivery.
You up for making these changes in this PR?
There was a problem hiding this comment.
okay, I just committed more changes based on your feedback. I also wanted to reformat the examples in another PR, but now I think it makes sense to do it here?
You might want to change the term "red ping badge", to be clear it refers to this red thing, but I’m not sure what the official name is 😅
Adds documentation for this change from 2021 which somehow never made it to the docs