XEP-xxxx: Explicit Mentions

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) [1] room owners to specify permissions related to mentions.

2. Discovering Support¶

An entity implementing this specification MUST advertise urn:xmpp:mentions:0 as a Service Discovery (XEP-0030) [2] feature. Subsequent features in this document may also be required to advertise support, if implemented.

3. Use Cases¶

3.1 Mentioning an Individual¶

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) [1] rooms, an occupantid attribute MUST be present, containing the mentioned user's Anonymous unique occupant identifiers for MUCs (XEP-0421) [3] identifier, if the room supports them. Otherwise, a jid attribute MUST be present, containing the mentioned user's JID.

Example 1. Mentioning a user in a room¶

<message to='news@chat.commons.example' type='groupchat'>
  <body>Hello, Alice!</body>
  <mention xmlns='urn:xmpp:mentions:0'
    begin='7'
    end='12'
    occupantid='alice@occupant-id'/>
  </message>

3.2 Mentioning Groups¶

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.

3.2.1 Mentions via Memberships¶

The following table lists groups based on membership or occupancy of an entity, such as channels, spaces, or servers.

Table 1: Groups¶

Mention type	Description
urn:xmpp:mentions:0#channel	Mention all occupants of a Multi-User Chat (XEP-0045) [1] room.
urn:xmpp:mentions:0#space	Mention all members of a Server-side spaces (XEP-0503) [4] space.
urn:xmpp:mentions:0#server	Mention all users of a server.

3.2.1.1 Channel

Channel mentions are used to mention all users in a Multi-User Chat (XEP-0045) [1] room, similarly to @everyone or @room on legacy platforms. If no uri attribute is present, and the current context is a MUC, then the room being mentioned is assumed to be the current room. The uri attribute MAY be used to specify a different room whose members should be mentioned, and MUST be included when used outside of a MUC.

Example 2. Mention all users in a room¶

  <message to='news@chat.commons.example' type='groupchat'>
    <body>Hey all!</body>
    <mention xmlns='urn:xmpp:mentions:0' mentions='urn:xmpp:mentions:0#channel' />
  </message>

3.2.1.2 Space

Space mentions are used to mention all users of a Server-side spaces (XEP-0503) [4] space. If no uri attribute is present, and the current MUC advertises a space that it is part of, then the space being mentioned is assumed to be the one advertised by the room. The uri attribute MAY be used to specify a different space, and MUST be used outside of MUCs or if the MUC does not advertise a parent space.

Example 3. Mention all users of a space¶

  <message to='news@chat.commons.example' type='groupchat'>
    <body>The rules for all rooms within this space have been updated.</body>
    <mention xmlns='urn:xmpp:mentions:0' mentions='urn:xmpp:mentions:0#space'
      uri='xmpp:spaces.commons.example;node=space'/>
  </message>

3.2.1.3 Server

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.

Example 4. Mention all users of a server¶

  <message to='news@chat.commons.example' type='groupchat'>
    <body>We will be upgrading the server in two hours.</body>
    <mention xmlns='urn:xmpp:mentions:0' mentions='urn:xmpp:mentions:0#server'
      uri='xmpp:commons.example'/>
  </message>

3.2.2 Mentions via Roles and Affiliations¶

It is possible to mention occupants with specific Multi-User Chat (XEP-0045) [1] roles or affiliations. The mention type to use is defined in the table below. Supporting implementations MUST advertise the urn:xmpp:mentions:0#associations namespace, and all of the defined role and affiliation types MUST be implemented to support this feature.

Table 2: Mention types¶

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

Example 5. Mention moderators in a room¶

  <message to='news@chat.commons.example' type='groupchat'>
    <body>Any moderator to handle the spam above please?</body>
    <mention xmlns='urn:xmpp:mentions:0' mentions='urn:xmpp:mentions:0#moderators' />
  </message>

3.2.3 Mentions via Hats¶

Hats, specified in Hats (XEP-0317) [5], may also be mentioned using the urn:xmpp:mentions:0#hats namespace, with the uri attribute containing the hat's URI.

Example 6. Mentioning all (hats) students in a room¶

  <message to='news@chat.commons.example' type='groupchat'>
    <body>To all students, [..]</body>
    <mention xmlns='urn:xmpp:mentions:0' mentions='urn:xmpp:mentions:0#hats'
      uri='http://schemas.example.com/hats#students'/>
  </message>

3.3 Begin and End Attributes¶

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) [6] links).

Begin and end pairs in a message SHOULD NOT overlap, except in the case where they are all equal.

Example 7. Mentioning members of a loosely defined group in a channel with many occupants¶

<message to='news@chat.commons.example' type='groupchat'>
  <body>Hi Spartacists!</body>
  <!-- @begin and @end are equal throughout all mentions here -->
  <mention xmlns='urn:xmpp:mentions:0'
    begin='3'
    end='14'
    occupantid='rosa@occupant-id'/>
  <mention xmlns='urn:xmpp:mentions:0'
    begin='3'
    end='14'
    occupantid='clara@occupant-id'/>
  <mention xmlns='urn:xmpp:mentions:0'
    begin='3'
    end='14'
    occupantid='karl@occupant-id'/>
</message>

3.4 Hreflang Attribute¶

The hreflang attribute MAY be used to target a message with the corresponding xml:lang attribute, in conjunction with begin and end.

Example 8. Mentioning a user in two languages¶

<message to='news@chat.commons.example' type='groupchat'>
  <!-- Supposing the stanza has been sent on a stream with xml:lang='en' -->
  <body>Hi Alice, how are you doing?</body>
  <mention xmlns='urn:xmpp:mentions:0'
    begin='3'
    end='8'
    hreflang='en'
    occupantid='ddfe47eabacabr2q1'/>
  <body xml:lang='ja'>こんにちは、アリス。お元気ですか？</body>
  <mention xmlns='urn:xmpp:mentions:0'
    begin='6'
    end='9'
    hreflang='ja'
    occupantid='ddfe47eabacabr2q1'/>
</message>

3.5 Modifiers¶

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.

Table 3: ¶

Modifier	Description
{urn:xmpp:mentions:0}active	Only notify if user is active
{urn:xmpp:mentions:0}noping	Do not notify the mentioned user

3.5.1 Active¶

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.

Example 9. Mention all active users of a room¶

<message to='news@chat.commons.example' type='groupchat'>
  <body>Hello, everybody!</body>
  <mention xmlns='urn:xmpp:mentions:0' mentions='urn:xmpp:mentions:0channel'>
    <active />
  </mention>
</message>

3.5.2 No Ping¶

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.

Example 10. Mention a user without notifying them¶

<message to='news@chat.commons.example' type='groupchat'>
  <body>Sorry, I was referring to Alice there.</body>
  <mention xmlns='urn:xmpp:mentions:0'
    begin='26'
    end='31'
    occupantid='alice@occupantid'>
    <noping />
  </mention>
</message>

3.6 Multi-User Chats Permissions¶

Administrators of Multi-User Chat (XEP-0045) [1] rooms may wish to limit how mentions are used. This section provides a mechanism for administrators to set permissions in a MUC, which receiving entities SHOULD refer to when deciding whether to notify the user.

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.

Example 11. Client requests permissions from room¶

<iq from='user@chat.commons.example/client'
  to='room@chat.commons.example'
  id='permissions1'
  type='get'>
  <query xmlns='urn:xmpp:mentions:0' />
</iq>

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.

Example 12. MUC returns configured permissions¶

<iq from='room@chat.commons.example'
  to='user@chat.commons.example/client'
  id='permissions1'
  type='result'>
  <query xmlns='urn:xmpp:mentions:0'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Permissions for Explicit Mentions</title>
      <instructions>
        Complete this form to inform entities about who can mention whom.
        The count is the maximum number of mentions allowed per message.
        For each mention type supported, the users allowed to use the type
        may be set to all participants, moderators only, or nobody.
      </instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>urn:xmpp:mentions:0</value>
      </field>
      <field var='mentions#count'
        label='How many mentions are allowed in a message?'
        type='text-single'>
        <required />
        <value>5</value>
      </field>
      <field var='mentions#individual'
        label='Who can mention individual users?'
        type='list-single'>
        <required />
        <value>participants</value>
        <option label='Participants'>
          <value>participants</value>
        </option>
        <option label='Moderators Only'>
          <value>moderators</value>
        </option>
        <option label='Nobody'>
          <value>none</value>
        </option>
      </field>
      <!-- If room supports urn:xmpp:mentions:0#channel: -->
      <field var='mentions#channel'
        label='Who can mention rooms?'
        type='list-single'>
        <required />
        <value>participants</value>
        <option label='Participants'>
          <value>participants</value>
        </option>
        <option label='Moderators Only'>
          <value>moderators</value>
        </option>
        <option label='Nobody'>
          <value>none</value>
        </option>
      </field>
      <!-- If room supports urn:xmpp:mentions:0#space: -->
      <field var='mentions#space'
        label='Who can mention spaces?'
        type='list-single'>
        <required />
        <value>participants</value>
        <option label='Participants'>
          <value>participants</value>
        </option>
        <option label='Moderators Only'>
          <value>moderators</value>
        </option>
        <option label='Nobody'>
          <value>none</value>
        </option>
      </field>
      <!-- If room supports urn:xmpp:mentions:0#server: -->
      <field var='mentions#server'
        label='Who can mention servers?'
        type='list-single'>
        <required />
        <value>participants</value>
        <option label='Participants'>
          <value>participants</value>
        </option>
        <option label='Moderators Only'>
          <value>moderators</value>
        </option>
        <option label='Nobody'>
          <value>none</value>
        </option>
      </field>
      <!-- If room supports urn:xmpp:mentions:0#associations: -->
      <field var='mentions#associations'
        label='Who can mention roles/affiliations?'
        type='list-single'>
        <required />
        <value>participants</value>
        <option label='Participants'>
          <value>participants</value>
        </option>
        <option label='Moderators Only'>
          <value>moderators</value>
        </option>
        <option label='Nobody'>
          <value>none</value>
        </option>
      </field>
      <!-- If room supports urn:xmpp:mentions:0#hats: -->
      <field var='mentions#hats'
        label='Who can mention hats?'
        type='list-single'>
        <required />
        <value>participants</value>
        <option label='Participants'>
          <value>participants</value>
        </option>
        <option label='Moderators Only'>
          <value>moderators</value>
        </option>
        <option label='Nobody'>
          <value>none</value>
        </option>
      </field>
    </x>
  </query>
</iq>

If the user is an owner of the room, they may fill out the form and submit it to change the configuration.

Example 13. Owner submits permissions form¶

<iq from='user@chat.commons.example/client'
  to='room@chat.commons.example'
  id='permissions2'
  type='set'>
  <query xmlns='urn:xmpp:mentions:0'>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE'>
        <value>urn:xmpp:mentions:0</value>
      </field>
      <field var='mentions#count'>
        <value>1</value>
      </field>
      <field var='mentions#individual'>
        <value>participants</value>
      </field>
      <!-- If room supports urn:xmpp:mentions:0#channel: -->
      <field var='mentions#channel'>
        <value>moderators</value>
      </field>
      <!-- If room supports urn:xmpp:mentions:0#space: -->
      <field var='mentions#space'>
        <value>moderators</value>
      </field>
      <!-- If room supports urn:xmpp:mentions:0#server: -->
      <field var='mentions#server'>
        <value>moderators</value>
      </field>
      <!-- If room supports urn:xmpp:mentions:0#associations: -->
      <field var='mentions#associations'>
        <value>participants</value>
      </field>
      <!-- If room supports urn:xmpp:mentions:0#hats: -->
      <field var='mentions#hats'>
        <value>participants</value>
      </field>
    </x>
  </query>
</iq>

Upon success, the room MUST inform the user.

Example 14. Room informs owner of success¶

<iq to='room@chat.commons.example'
  from='user@chat.commons.example/client'
  id='permissions2'
  type='result' />

If the user is not an owner, a <forbidden /> error MUST be returned.

Example 15. Room denies access to non-owner¶

<iq to='room@chat.commons.example'
  from='user@chat.commons.example/client'
  id='permissions2'
  type='error'>
  <query xmlns='urn:xmpp:mentions:0' />
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas' />
  </error>
</iq>

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.

Example 16. Room notifies user of change¶

<message to='user@chat.commons.example/client'
  from='room@chat.commons.example
  id='permissions4'
  type='groupchat'>
  <x xmlns='jabber:x:data' type='result'>
    <title>Updated configuration for Explicit Mention Permissions</title>
    <field type='hidden' var='FORM_TYPE'>
      <value>urn:xmpp:mentions:0</value>
    </field>
    <!-- Supposing only count and individual were changed... -->
    <field var='mentions#count' type='text-single'>
      <value>1</value>
    </field>
    <field var='mentions#individual' type='list-single'>
      <value>participants</value>
    </field>
  </x>
</message>

4. Implementation Notes¶

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.

As Anonymous unique occupant identifiers for MUCs (XEP-0421) [3] in MUC can point to multiple nicknames, it may be confusing for clients which would want to display something based on the nickname (colors, etc.). It also may be an issue for a service sending push notifications that need to know which devices to send to.

5. Accessibility Considerations¶

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.

6. Internationalization Considerations¶

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.

7. Security Considerations¶

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) [3] instead of a regular participant JID in MUC prevents moderators possibly leaking JIDs they have access to that other occupants don't. Using occupant IDs even in non-anonymous rooms allows them to become semi-anonymous without leaking JIDs.

8. IANA Considerations¶

9. XMPP Registrar Considerations¶

9.1 Field Standardization¶

TODO

10. Design Considerations¶

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) [7] provides a basic means to explicitly mention a single user via JID, but no means of mentioning groups of users, nor means to extend mentions further.

This specification is designed to depend on a proposed revision to References (XEP-0372) [7], which makes references more generic and removes mentions, among other changes. If and when the revision is accepted, this specification may be updated to depend on References (XEP-0372) [7].

11. XML Schema¶

12. Acknowledgements¶

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.

Appendices

Appendix A: Document Information¶

Appendix B: Author Information¶

Snit Guckfung

Appendix C: Legal Notices¶

Copyright

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Visual Presentation

The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.

Appendix D: Relation to XMPP¶

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue¶

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.

Appendix F: Requirements Conformance¶

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.