Accepted as Experimental by council vote on 2026-03-31
Proposal handover
First draft.
A common feature in online communication is ability to explicitly address a message to a specific person or a group of people, and have their clients notify them on the way. This document provides a mechanism to allow users to explicitly reference individual users, as well as entire groups based on roles, affiliations, and hats in their messages. Furthermore, it provides a way for Multi-User Chat (XEP-0045)
An entity implementing this specification MUST advertise urn:xmpp:mentions:0 as a Service Discovery (XEP-0030)
There are two ways to mention an individual, depending on context. In both cases, a mention element with the urn:xmpp:mentions:0 type is sent, which MUST NOT contain a mentions attribute.
In Multi-User Chat (XEP-0045)
Users may wish to mention whole groups of users at once. The following subsections specify several types of groups that may be mentioned, all of which are OPTIONAL.
To mention a group, the mentions attribute MUST be present, containing a URI denoting the group type. The same URI MUST be advertised via service discovery on supported implementations. Custom group types not specified in this document MAY be used, provided they follow the same rules.
The following table lists groups based on membership or occupancy of an entity, such as channels, spaces, or servers.
| Mention type | Description |
|---|---|
| urn:xmpp:mentions:0#channel | Mention all occupants of a Multi-User Chat (XEP-0045) |
| urn:xmpp:mentions:0#space | Mention all members of a Server-side spaces (XEP-0503) |
| urn:xmpp:mentions:0#server | Mention all users of a server. |
Channel mentions are used to mention all users in a Multi-User Chat (XEP-0045)
Space mentions are used to mention all users of a Server-side spaces (XEP-0503)
Server mentions are used to mention all users of a particular server. This SHOULD NOT be used within semi-anonymous rooms, when responses to a server mention could reveal which users have accounts on that server, and may reveal your own account's server. All server mentions MUST include a uri attribute containing a URI to the server being mentioned, and MAY contain servers other than your own.
It is possible to mention occupants with specific Multi-User Chat (XEP-0045)
| Type | Description |
|---|---|
| urn:xmpp:mentions:0#moderators | Occupants with a moderator role |
| urn:xmpp:mentions:0#participants | Occupants with a participant role |
| urn:xmpp:mentions:0#visitors | Occupants with a visitor role |
| urn:xmpp:mentions:0#owner | Occupants with an owner affiliation |
| urn:xmpp:mentions:0#admin | Occupants with an admin affiliation |
| urn:xmpp:mentions:0#member | Occupants with a member affiliation |
| urn:xmpp:mentions:0#none | Occupants with no affiliation |
Hats, specified in Hats (XEP-0317)
If a mention element of type urn:xmpp:mentions:0 or its subtypes contains both begin and end attributes, the receiving entity MAY use this as a hint that the specified range of the content is being addressed to the specified occupant. If the element doesn't contain these attributes, the mention doesn't refer to a specific part of the content, and implementations MAY check other parts of the payload to know what it refers to, (e.g., XHTML-IM (XEP-0071)
Begin and end pairs in a message SHOULD NOT overlap, except in the case where they are all equal.
The hreflang attribute MAY be used to target a message with the corresponding xml:lang attribute, in conjunction with begin and end.
Mentions may be modified in order to change their behaviour. The modifiers specified here MUST be in the urn:xmpp:mentions:0 namespace, and placed as a child of the mention element. Modifiers not specified here MAY be used, provided they use a separate namespace and advertise support similarly to custom groups.
The following table lists the possible modifiers.
| Modifier | Description |
|---|---|
| {urn:xmpp:mentions:0}active | Only notify if user is active |
| {urn:xmpp:mentions:0}noping | Do not notify the mentioned user |
The active modifier tells receiving entities that only users active when the message is sent should be mentioned. This works similarly to @here in many legacy messengers, except that it can be applied to any type of mention here. Implementations SHOULD notify the user if they are currently active, and SHOULD NOT notify them otherwise. It is up to implementations to decide what constitutes "active". Examples include an online status or recent activity in the client.
The noping modifier tells receiving entities that the sender does not wish to notify the mentioned user. This could be useful to explicitly reference a specific user or group without disturbing the user(s) in question, such as for distinguishing two users with the same name or directing someone to another user or group.
Administrators of Multi-User Chat (XEP-0045)
Rooms which provide permissions MUST advertise support with urn:xmpp:mentions:0. Mentions MAY be sent in rooms which do not have permissions set, and/or do not advertise support for them; it is up to receiving entities to determine how to handle mentions in rooms without configured permissions.
The following examples demonstrate how a user can get and set the permissions configuration form.
In the following response, the mentions#count and mentions#individual fields MUST be present at minimum. All other fields are OPTIONAL, but they MUST be present if and only if the corresponding feature is advertised in service discovery. The following form's fields SHOULD also be advertised in the room's muc#roominfo extension form.
Receiving entities SHOULD ignore all mentions if the message contains more mentions than the threshold specified by mentions#count. Receiving entities SHOULD ignore a given mention if the sender does not have at least the minimum role required by the room.
If the user is an owner of the room, they may fill out the form and submit it to change the configuration.
Upon success, the room MUST inform the user.
If the user is not an owner, a <forbidden /> error MUST be returned.
Upon successful change of configuration, the service SHOULD broadcast the changes to all users. The message SHOULD include only those fields which have been modified.
This specification allows sending clients to convey a user's intent. Implementations SHOULD also allow sending participants to talk about someone without having to mention them.
No specific server support is required for mentions to be sent between entities, though implementing permissions in MUCs is RECOMMENDED. It is up to receiving entities whether or not a given mention refers to them, and whether the mention should notify the user. User interfaces SHOULD have an option to suppress notifications for the various types of mentions independently of MUC permission settings.
Anonymous unique occupant identifiers for MUCs (XEP-0421)
As Anonymous unique occupant identifiers for MUCs (XEP-0421)
This specification allows users to explicitly choose whether to mention a user or group, removing the need to use old regex-based name matches, which are prone to false positives. It also allows users to refer to someone else without disturbing them and without relying on tricks to prevent regex matches.
If an implementation sends a mention element of type urn:xmpp:mentions:0 or its subtypes which contains a valid hreflang attribute that refers to content with an xml:lang attribute, it SHOULD take care to send a mention for every languages it sends.
Setting proper permissions in MUCs can help mitigate the possibility for malicious entities to abuse the ability to mention groups of people. Servers MAY filter mentions which violate the configured permissions, and MAY do further filtering according to their own rules. No attempt is made to mitigate abuse of regex-based implicit mentions; implementations SHOULD allow implicit mentions to be turned off.
This specification allows sending mentions without including them in the message body, effectively hiding them from the user. User interfaces SHOULD allow users to view a list of all mentions attached to a message.
Use of explicit mentions with OMEMO can leak metadata about who the message is directed towards, if only the body of the message is encrypted.
Using Anonymous unique occupant identifiers for MUCs (XEP-0421)
None.
TODO
TODO
Most clients currently use regex-based solutions to determine whether a user should be notified of a message. This is prone to false positives, especially for users with common words as names. It also provides no mechanism for a user to refer to someone else without notifying them.
An early revision of References (XEP-0372)
This specification is designed to depend on a proposed revision to References (XEP-0372)
TODO
Special thanks to pep for providing the initial document which this one is based off of, and for allowing me to continue work on it.