Mentions and allowed_mentions

A bot can name anyone in its text, but who actually gets notified is decided by allowed_mentions and by what the bot may do. The defaults are careful on purpose: a bot never pings everyone or a whole role by accident.

The object

{"allowed_mentions": {"parse": ["users", "roles", "everyone"], "users": ["<user id>"], "roles": ["<role id>"]}}
FieldMeaning
parseKinds of mentions in the text that may notify: "users", "roles", "everyone" (@all and @here)
usersMember ids that may be notified
rolesRole ids whose members may be notified

The rules

In the textNotifies when
@usernameAlways for members who can view the channel, unless the message sends allowed_mentions without "users"
@all, @hereOnly when the bot may mention everyone (Mention @all and @here) and parse contains "everyone"
@Role NameOnly when parse contains "roles" or roles lists the role's id, and the role is mentionable, or the bot may mention everyone (then any custom role, never @everyone or the managed bot roles)
  • Role mentions are off by default. A message without allowed_mentions notifies no role.
  • Only members who can view the channel are ever notified, whatever the object says.
  • Bots are notified only when named directly, never through a role, @all or @here.

Edits, uploads and answers

  • An edit (PATCH /channels/{id}/messages/{id}) takes allowed_mentions like a post. Without it, the new text notifies the members it names and never @all, @here or a role, so editing a message removes its role mentions instead of adding them. An edit that sends allowed_mentions counts as a post for the channel's limit of 5 per 5 seconds.
  • An upload takes the same object as the form field allowed_mentions, JSON-encoded, for example {"parse":["everyone","roles"]}.
  • Interaction answers (callback 4, follow-ups, the first message after a deferred answer, @original edits) follow the same rules as a post.
  • Incoming webhooks use the webhook's own settings: allow_user_mentions and allow_everyone can only narrow what a request asks for.

In the SDKs

await client.rest.createMessage(channelId, {
  content: '@Raiders the boss rush starts in 10 minutes',
  allowed_mentions: { parse: ['roles'] },
})
_, err := c.REST.CreateMessage(ctx, channelID, mnema.MessageCreate{
	Content:         "@Raiders the boss rush starts in 10 minutes",
	AllowedMentions: &mnema.AllowedMentions{Parse: []string{"roles"}},
})

Something wrong on this page? Tell us.