<p>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.</p>
<p>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.</p>
</section1>
<section1topic='Requirements'anchor='reqs'>
<p>JID mention must:</p>
<ul>
<li>work online and offline</li>
<li>work if the entity is not aware of the context</li>
<li>work outside of XMPP context (e.g. in a website)</li>
<li>not be tied to a particular syntax</li>
<li>(desirable) be easy to implement</li>
</ul>
</section1>
<section1topic='Glossary'anchor='glossary'>
<ul>
<li><strong>Mentioning entity</strong> — the entity which wants to mention somebody.</li>
<li><strong>Mentioned entity</strong> — the entity actually mentioned.</li>
<li><strong>Mentioned URI</strong> — URI where the entity is mentioned.</li>
<li><strong>PubSub</strong> — &xep0060;.</li>
<li><strong>MUC</strong> — &xep0045;.</li>
<li><strong>MIX</strong> — &xep0369;.</li>
</ul>
</section1>
<section1topic='Mentioning an entity'anchor='mention'>
<section2topic='Basic syntax'anchor='base'>
<p>The syntax used by the software willing to mention a jid is up to the implemention. Nickname followed by "<strong>:</strong>" is commonly used in group chats like MUC or Internet Relay Chat (IRC) while "<strong>@</strong>" 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.</p>
<p>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 <strong>'urn:xmpp:mention:0'</strong> 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.</p>
<examplecaption='basic mention of Juliet'><![CDATA[
You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join
</body>
</message>
]]></example>
</section2>
<section2topic='Context parents'anchor='parents'>
<p>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.</p>
<p>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.</p>
<examplecaption='mention of Juliet in microblog comments'><![CDATA[
You have been mentioned on xmpp:pubsub.montague.lit?;node=urn%3Axmpp%3Amicroblog%3A0%3Acomments%2Fdd88c9bc58886fce0049ed050df0c5f2
</body>
</message>
]]></example>
</section2>
<section2topic='Context hint'anchor='context'>
<p>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.</p>
<examplecaption='mention with context hint'><![CDATA[
You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join
</body>
</message>
]]></example>
</section2>
<section2topic='Mention author'anchor='author'>
<p>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.</p>
<p>The author of the mention MAY be specified in <author/> element. If present, it MUST contain one or more of the following elements:</p>
<ul>
<li><em>JID</em> — the user jid, in a <jid/> element</li>
<li><em>email</em> — the user email address, in a <email/> element</li>
<li><em>Full Name</em> — the user full name, in a <name/> element</li>
<li><em>Nickname</em> — the user nickname, in a <nick/> element</li>
</ul>
<examplecaption='mention with its author'><![CDATA[
You have been mentioned on xmpp:balcony@chat.shakespeare.lit?join
</body>
</message>
]]></example>
</section2>
<section2topic='Mentioned part'anchor='part'>
<p>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.</p>
<p>If the mentioned URI refers to an XMPP context (e.g. a MUC room), a stanza id can be specified. To do so, the &xep0359; semantic is used: mentioning entity MAY add a <stanza-id/> element to the <part/> element as specified in XEP-0359.</p>
<examplecaption='mention with context hint'><