Mentioning somebody is usually done in the context of a multi-user chat: a notification is triggered when somebody's nickname is written, and it often only works when a client is online and monitoring the conversation.
But it is more and more common to mention people in other contexts (e.g. microblogging), and it is desirable that this works even when an entity is offline or not aware of the context. This XEP offers a simple solution to mention people in any context, online or offline and even outside of XMPP.
JID mention must:
The syntax used by the software willing to mention a jid is up to the implemention. Nickname followed by ":" is commonly used in group chats like MUC or Internet Relay Chat (IRC) while "@" followed by nickname is often used with microblogging. Note that if it is not possible to associate a nickname with a jid without ambiguity, a bare jid SHOULD be used instead of a nickname.
To mention an entity, a <message/> stanza must be sent to the bare jid of the entity with a <mention/> elements which MUST have the 'urn:xmpp:mention:0' namespace. The <mention/> element MUST have a 'uri' attribute which links to the context where the entity has been mentioned. This URI can be the URI of a MUC room, a PubSub node, a Jingle file (e.g. a photo where mentioned entity appears), a website, or anything which makes sense. A <body/> element MUST be present with a human readable text indicating the mentioned URI (e.g. “You have been mentioned on xmpp:xsf@muc.xmpp.org?join”). No other elements or attributes are mandatory.
<message from='romeo@montage.net' to='juliet@capulet.lit' id='123'>
<mention xmlns='urn:xmpp:mention:0' uri='xmpp:balcony@chat.shakespeare.lit?join' />
<body>
You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join
</body>
</message>
Sometime the 'uri' refers to an element which is a child of other one(s). For instance, a mentioned URI may refer to a website comment with a direct link, which is a part of a more general conversation, or PubSub URI refers to a microblog comment which is a child of another comment, itself a child of the main item.
In this case, it is desirable for the mentioned entity to know where is the main item, so it can understand the whole context. To deal with this, the mentioning entity MAY declare the path to the uri by adding a <parents/> element which MUST contain one or more <parent/> elements. Each <parent/> element MUST contain an 'uri' attribute with the URI of the parent. If more than one parents are specified, they MUST be put in order, from the more distant one to the last child just before the one specified in the main <mention/> element.
<message from='romeo@montage.net' to='juliet@capulet.lit' id='123'>
<mention xmlns='urn:xmpp:mention:0' uri='xmpp:pubsub.montague.lit?;node=urn%3Axmpp%3Amicroblog%3A0%3Acomments%2Fdd88c9bc58886fce0049ed050df0c5f2'>
<parents>
<parent uri='xmpp:romeo%40montague.lit?;node=urn%3Axmpp%3Amicroblog%3A0;item=2ze57d9c-1c46-21df-830c-002143d3d2qgf' />
</parents>
</mention>
<body>
You have been mentioned on xmpp:pubsub.montague.lit?;node=urn%3Axmpp%3Amicroblog%3A0%3Acomments%2Fdd88c9bc58886fce0049ed050df0c5f2
</body>
</message>
To help the mentioned entity understand the context, the mentioning entity MAY add a <context> element which include human readable text. What is inside is at the discretion of the mentioning entity, it MAY be the paragraph where the entity is mentioned, or anything useful.
<message from='juliet@capulet.lit' to='romeo@montage.net' id='123'>
<mention xmlns='urn:xmpp:mention:0' uri='xmpp:balcony@chat.shakespeare.lit?join'>
<context>
O Romeo, Romeo! wherefore art thou Romeo?
Deny thy father and refuse thy name!
Or, if thou wilt not, be but sworn my love,
And I'll no longer be a Capulet.
</context>
</mention>
<body>
You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join
</body>
</message>
If the mention is done outside of XMPP context (e.g.: on a website), the 'from' attribute of the message may be the jid of a server component or a bot. In this case, the mentioning entity can give information on the real author of the mention.
The author of the mention MAY be specified in <author/> element. If present, it MUST contain one or more of the following elements:
<message from='xmpp_bot.shakespeare.example.net' to='juliet@capulet.lit' id='123'>
<mention xmlns='urn:xmpp:mention:0' uri='https://www.ball.shakespeare.example.net'>
<author>
<name>Lord Capulet</name>
<jid>capulet@capulet.lit</jid>
</author>
</mention>
<body>
You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join
</body>
</message>
In some contexts, an URI may not be sufficient to locate the exact place of the mention. For instance, it may be useful to know the exact message of a MUC room where the mention did take place. If a mentioning entity wants to specify the exact part of the location where the mention happened, it MAY use a <part/> element. This element contains information dependent on the mentioned URI. For now, only stanza-id is used, but later versions of this specification, or other XEPs can add new elements.
If the mentioned URI refers to an XMPP context (e.g. a MUC room), a stanza id can be specified. To do so, the Unique and Stable Stanza IDs (XEP-0359) [4] semantic is used: mentioning entity MAY add a <stanza-id/> element to the <part/> element as specified in XEP-0359.
<message from='juliet@capulet.lit' to='romeo@montage.net' id='123'>
<mention xmlns='urn:xmpp:mention:0' uri='xmpp:balcony@chat.shakespeare.lit?join'>
<context>
O Romeo, Romeo! wherefore art thou Romeo?
Deny thy father and refuse thy name!
Or, if thou wilt not, be but sworn my love,
And I'll no longer be a Capulet.
</context>
<part>
<stanza-id xmlns='urn:xmpp:sid:0'
id='4b3ec1b6-10ca-498a-af20-378ffaaafddd'
by='balcony@chat.shakespeare.lit'/>
</part>
</mention>
<body>
You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join
</body>
</message>
A server MAY provide a way for clients to configure their notifications (e.g. send by email instead of XMPP, accept mentions only from entities in the roster). To do so, the Ad-Hoc Commands (XEP-0050) [5] is used on the well-defined command node 'urn:xmpp:mention:0#configure'.
If a entity supports the JID mention protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:mention:0" in response to a Service Discovery (XEP-0030) [6] information request:
<iq from='kingclaudius@shakespeare.lit/castle'
id='disco1'
to='laertes@shakespeare.lit/castle'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq from='laertes@shakespeare.lit/castle'
id='disco1'
to='kingclaudius@shakespeare.lit/castle'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='urn:xmpp:mention:0'/>
...
</query>
</iq>
A server doesn't have to announce JID mention namespace as it is a client feature, but if it offers a configuration node as specified in the configuration section, it MUST announce this fact by including a service discovery feature of "urn:xmpp:mention:0#configure".
This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [7].
The XMPP Registrar [8] includes 'urn:xmpp:mention:0' in its registry of protocol namespaces (see <https://xmpp.org/registrar/namespaces.html>).
If the protocol defined in this specification undergoes a revision that is not fully backwards-compatible with an older version, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:mention:0'
xmlns='urn:xmpp:mention:0'
elementFormDefault='qualified'>
<xs:import namespace='urn:xmpp:sid:1'
schemaLocation='http://xmpp.org/schemas/sid.xsd'/>
<xs:element name='mention'>
<xs:complexType>
<xs:attribute name='uri' use='required' type='xs:string'/>
<xs:element name='parents' minOccurs='0' maxOccurs='1'>
<xs:element name='parent' minOccurs='1' maxOccurs='unbounded'>
<xs:attribute name='uri' use='required' type='xs:string'/>
</xs:element>
</xs:element>
<xs:element name='context' minOccurs='0' maxOccurs='1'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string' />
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='author' minOccurs='0' maxOccurs='1'>
<xs:complexType>
<xs:sequence>
<xs:choice minOccurs='1' maxOccurs='unbounded'>
<xs:element ref='jid'/>
<xs:element ref='email'/>
<xs:element ref='name'/>
<xs:element ref='nick'/>
</xs:choice>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='part' minOccurs='0' maxOccurs='1'>
<xs:complexType>
<xs:sequence>
<xs:choice minOccurs='1' maxOccurs='unbounded'>
<xs:element ref='urn:xmpp:sid:1' />
</xs:choice>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:complexType>
</xs:element>
</xs:schema>
Thanks to Adrien Cossa for his review/corrections.
This document in other formats: XML PDF
This XMPP Extension Protocol is copyright © 1999 – 2024 by the XMPP Standards Foundation (XSF).
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.
## 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. ##
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.
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).
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.
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.
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.
Errata can be sent to <editor@xmpp.org>.
The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>.
2. XEP-0045: Multi-User Chat <https://xmpp.org/extensions/xep-0045.html>.
3. XEP-0369: Mediated Information eXchange (MIX) <https://xmpp.org/extensions/xep-0369.html>.
4. XEP-0359: Unique and Stable Stanza IDs <https://xmpp.org/extensions/xep-0359.html>.
5. XEP-0050: Ad-Hoc Commands <https://xmpp.org/extensions/xep-0050.html>.
6. XEP-0030: Service Discovery <https://xmpp.org/extensions/xep-0030.html>.
7. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
8. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <https://xmpp.org/registrar/>.
Note: Older versions of this specification might be available at https://xmpp.org/extensions/attic/
First draft.
@report{poisson2016xepxxxx,
title = {JID Mention},
author = {Poisson, Jérôme},
type = {XEP},
number = {xxxx},
version = {0.0.1},
institution = {XMPP Standards Foundation},
url = {https://xmpp.org/extensions/xep-xxxx.html},
date = {2016-01-16/2016-01-16},
}END