mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-25 10:42:19 -05:00
357 lines
14 KiB
XML
357 lines
14 KiB
XML
<?xml version='1.0' encoding='UTF-8'?>
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
|
%ents;
|
|
]>
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
|
<xep>
|
|
<header>
|
|
<title>Message Reactions</title>
|
|
<abstract>This specification defines a way for adding reactions to a message.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0444</number>
|
|
<status>Experimental</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<approver>Council</approver>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
<spec>XEP-0001</spec>
|
|
<spec>XEP-0030</spec>
|
|
<spec>XEP-0115</spec>
|
|
<spec>XEP-0203</spec>
|
|
<spec>XEP-0334</spec>
|
|
<spec>XEP-0359</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>reactions</shortname>
|
|
<author>
|
|
<firstname>Natalie</firstname>
|
|
<surname>Wirth</surname>
|
|
<email>xsf@larma.de</email>
|
|
</author>
|
|
<author>
|
|
<firstname>Marvin</firstname>
|
|
<surname>Wissfeld</surname>
|
|
<email>xsf@larma.de</email>
|
|
<jid>jabber@larma.de</jid>
|
|
</author>
|
|
<revision>
|
|
<version>0.2.0</version>
|
|
<date>2022-12-30</date>
|
|
<initials>NC</initials>
|
|
<remark>Add emoji rejection mechanism.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1.1</version>
|
|
<date>2022-12-30</date>
|
|
<initials>egp</initials>
|
|
<remark>Add the XML Schema</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1.0</version>
|
|
<date>2020-10-13</date>
|
|
<initials>XEP Editor (jsc)</initials>
|
|
<remark>Accepted by vote of Council on 2020-10-07.</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2019-07-14</date>
|
|
<initials>nw/mw</initials>
|
|
<remark><p>First draft.</p></remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>
|
|
Message reactions allow to express an opinion or feeling towards a message
|
|
in a quick and light-weight way. Reactions are described in the form of
|
|
emojis and can enhance communication especially when chatting with multiple
|
|
parties. Other possible uses include voting and checking to-do list items.
|
|
</p>
|
|
<p>
|
|
Reactions are typically displayed in a summarizing fashion visually attached
|
|
to the message they belong to.
|
|
</p>
|
|
<p>
|
|
Related work has been done in &xep0367;. However, it can't be used for
|
|
reactions, as it would cause difficulties with non-supporting clients, is
|
|
not tailored to emojis and does not specify removal of reactions. To solve
|
|
these issues, this XEP introduces a separate XML element for reactions.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='Discovering support' anchor='disco'>
|
|
<section2 topic="Basic support" anchor="disco-base">
|
|
<p>
|
|
If a client implements message reactions, it MUST specify the
|
|
'urn:xmpp:reactions:0' feature in its service discovery information features
|
|
as specified in &xep0030; and the Entity Capabilities profile specified in &xep0115;.
|
|
</p>
|
|
<example caption='Client requests information about a chat partner's client'><![CDATA[
|
|
<iq type='get'
|
|
to='romeo@montague.lit/orchard'
|
|
from='juliet@capulet.lit/balcony'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
|
</iq>]]></example>
|
|
<example caption='Partner's client advertises support for reactions'><![CDATA[
|
|
<iq type='result'
|
|
to='juliet@capulet.lit/balcony'
|
|
from='romeo@montague.lit/orchard'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
...
|
|
<feature var='urn:xmpp:reactions:0'/>
|
|
...
|
|
</query>
|
|
</iq>]]></example>
|
|
</section2>
|
|
<section2 topic="Restricted reactions" anchor="disco-restricted">
|
|
<p>
|
|
In some cases, only a limited number and/or subset
|
|
of emojis are allowed to react to a message.
|
|
This is particularly useful in the context of gateways to other chat
|
|
networks that are not as permissive about which and how many emojis
|
|
can be used for message reactions.
|
|
MUC components may also allow room admins to restrict the subset and/or number
|
|
of emojis per message.
|
|
</p>
|
|
<p>
|
|
To allow clients to adapt their UIs, entities that have such restrictions in place
|
|
SHOULD advertise it with &xep0128; in a &xep0004; using the
|
|
'urn:xmpp:reactions:0:restrictions' namespace as FORM_TYPE.
|
|
</p>
|
|
<example caption='Entities advertises support for restricted reactions'><![CDATA[
|
|
<iq type='result'
|
|
to='juliet@capulet.lit/balcony'
|
|
from='romeo@montague.lit/orchard'
|
|
id='info1'>
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
|
...
|
|
<feature var='urn:xmpp:reactions:0'/>
|
|
<x xmlns='jabber:x:data' type='result'>
|
|
<field var='FORM_TYPE' type='hidden'>
|
|
<value>urn:xmpp:reactions:0:restrictions</value>
|
|
</field>
|
|
<field var='max_reactions_per_user'>
|
|
<value>1</value>
|
|
</field>
|
|
<field var='allowlist'>
|
|
<value>💘</value>
|
|
<value>❤️</value>
|
|
<value>💜</value>
|
|
</field>
|
|
</x>
|
|
...
|
|
</query>
|
|
</iq>]]></example>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Use Cases' anchor='usecases'>
|
|
<section2 topic="Sending reactions to a message" anchor="sending-reactions">
|
|
<p>
|
|
When a user chooses to react to a message with a certain emoji, the
|
|
client sends a <message> stanza containing a <reactions>
|
|
element. The chosen emoji is included in a <reaction> element within
|
|
the <reactions> element. The message is referred to by including its
|
|
id or in MUCs its stanza-id as defined in &xep0359; in the 'id' attribute
|
|
of the reactions element.
|
|
</p>
|
|
<example caption="Romeo sends a message"><![CDATA[
|
|
<message to='juliet@capulet.net/balcony' id='744f6e18-a57a-11e9-a656-4889e7820c76' type='chat'>
|
|
<body>Hello, world!</body>
|
|
</message>]]></example>
|
|
<example caption="Juliet sends a 👋 reaction to the message"><![CDATA[
|
|
<message to='romeo@capulet.net/orchard' id='7fdd29fa-a57a-11e9-b04a-4889e7820c76' type='chat'>
|
|
<reactions id='744f6e18-a57a-11e9-a656-4889e7820c76' xmlns='urn:xmpp:reactions:0'>
|
|
<reaction>👋</reaction>
|
|
</reactions>
|
|
<store xmlns="urn:xmpp:hints"/>
|
|
</message>]]></example>
|
|
</section2>
|
|
<section2 topic="Updating reactions to a message" anchor="updating-reactions">
|
|
<p>
|
|
If the user chooses to remove reactions from or add reactions to a
|
|
message they have already reacted to, the client sends a <message>
|
|
with all <reaction> elements that are (still or newly) applicable
|
|
to that message.
|
|
</p>
|
|
<example caption="Juliet adds a 🐢 reaction to the message"><![CDATA[
|
|
<message to='romeo@capulet.net/orchard' id='96d73204-a57a-11e9-88b8-4889e7820c76' type='chat'>
|
|
<reactions id='744f6e18-a57a-11e9-a656-4889e7820c76' xmlns='urn:xmpp:reactions:0'>
|
|
<reaction>👋</reaction>
|
|
<reaction>🐢</reaction>
|
|
</reactions>
|
|
<store xmlns="urn:xmpp:hints"/>
|
|
</message>]]></example>
|
|
<p>
|
|
In order to remove all reactions from a message, an empty
|
|
<reactions> element is sent.
|
|
</p>
|
|
<example caption="Juliet removes all reactions from the message"><![CDATA[
|
|
<message to='romeo@capulet.net/orchard' id='973c9d2e-a57a-11e9-af82-4889e7820c76' type='chat'>
|
|
<reactions id='744f6e18-a57a-11e9-a656-4889e7820c76' xmlns='urn:xmpp:reactions:0'/>
|
|
<store xmlns="urn:xmpp:hints"/>
|
|
</message>]]></example>
|
|
</section2>
|
|
<section2 topic="Rejecting a reaction" anchor="rejecting">
|
|
<p>
|
|
Entities implementing reaction restrictions MUST reply to invalid reactions payloads
|
|
with a message type="error" containing a 'not-acceptable' error.
|
|
The error payload SHOULD contain a human-readable text message explaining the reaction rules.
|
|
</p>
|
|
<example caption="Romeo sends a message"><![CDATA[
|
|
<message from="romeo@legacy-love-network.capulet.net"
|
|
to='juliet@capulet.net'
|
|
id='restricted-reactions-1'
|
|
type='chat'>
|
|
<body>I shall only accept heart emojis as reactions</body>
|
|
</message>]]></example>
|
|
<example caption="Juliet reacts with both a 💘 and a 💜"><![CDATA[
|
|
<message from="juliet@capulet.net"
|
|
to='romeo@legacy-love-network.capulet.net'
|
|
id='will-be-rejected1'
|
|
type='chat'>
|
|
<reactions id='restricted-reactions-1' xmlns='urn:xmpp:reactions:0'>
|
|
<reaction>💘</reaction>
|
|
<reaction>💜</reaction>
|
|
</reactions>
|
|
<store xmlns="urn:xmpp:hints"/>
|
|
</message>]]></example>
|
|
<example caption="Romeo rejects the reactions"><![CDATA[
|
|
<message from="romeo@legacy-love-network.capulet.net"
|
|
to="juliet@capulet.net"
|
|
type="error"
|
|
id="will-be-rejected1">
|
|
<error xmlns="jabber:client" type="modify">
|
|
<not-acceptable xmlns="urn:ietf:params:xml:ns:xmpp-stanzas" />
|
|
<text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
|
|
Only 💘, ❤️ and 💜 are allowed as reactions on this legacy IM network,
|
|
and you can only use a single emoji at once.
|
|
</text>
|
|
</error>
|
|
</message>]]></example>
|
|
<p>
|
|
When receiving this error message, the reaction-sending entity MUST revert the "message reactions"
|
|
to its previous state in its user interface.
|
|
</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Business Rules' anchor='rules'>
|
|
<p>Messages MUST NOT contain more then one <reactions> element</p>
|
|
<p>
|
|
A message containing a <reactions> element SHOULD be of type 'chat'
|
|
or 'groupchat'.
|
|
</p>
|
|
<p>
|
|
A <reaction> element SHOULD only contain Unicode codepoints that can
|
|
be displayed as a single emoji, as specified in the latest revision of the
|
|
<link url="http://www.unicode.org/reports/tr51/">Unicode® Technical Standard #51</link> <note>Unicode® Technical Standard #51 <<link url="http://www.unicode.org/reports/tr51/">http://www.unicode.org/reports/tr51/</link>>.</note>.
|
|
Receiving entities MAY ignore <reaction> elements that do not comply
|
|
with this specification.
|
|
</p>
|
|
<p>
|
|
A receiving client SHOULD show reactions attached to the message they where
|
|
in response to. Reactions MAY be displayed in a summarized fashion.
|
|
</p>
|
|
<p>
|
|
A <reactions> element MUST NOT contain the same reaction more than
|
|
once. A receiving entity SHOULD ignore duplicate reactions inside a
|
|
<reactions> element.
|
|
</p>
|
|
<p>
|
|
The sending entity SHOULD add a <store/> hint, as defined in &xep0334;,
|
|
if the message being reacted to does not carry a <no-store/> hint.
|
|
</p>
|
|
<p>
|
|
If a message is updated using &xep0308;, the 'id' attribute of the
|
|
<reactions> element SHOULD reference the original message id.
|
|
A receiving entity SHOULD accept messages with a <reactions> element
|
|
referencing a message correction and SHOULD handle such element as if
|
|
it was using the message id of the original message.
|
|
</p>
|
|
<section2 topic='Acceptable reactions' anchor='acceptable-reactions'>
|
|
<p>
|
|
In direct conversations, a reaction MUST only be accepted if the senders
|
|
bare JID matches the bare JID of any of the two involved parties.
|
|
</p>
|
|
<p>
|
|
In MUCs and MUC PMs, the recipient SHOULD ensure that the real bare JID of
|
|
the sending occupant did not already send a reaction to that message to
|
|
accept it as a new reaction, e.g. by keeping track of leave/join
|
|
presences since the message was send. This implies that in semi-anonymous
|
|
MUCs it MAY be impossible to attach reactions to a message received from
|
|
the history. A reaction MAY still be a valid reaction update (as per the
|
|
next paragraph) if it was not accepted as a new reaction.
|
|
</p>
|
|
<p>
|
|
A reaction MUST only be considered an update if it orignates from the same
|
|
sender as a previous reaction message. In direct conversations, this means
|
|
the bare JID MUST match the original bare JID. In MUCs and MUC PMs the
|
|
senders full JID MAY not match the original full JID, but the recipient
|
|
MUST ensure that the real bare JID of the sending occupant is the same as
|
|
the real bare JID of the previous reaction message, e.g. by keeping track
|
|
of leave/join presences.
|
|
</p>
|
|
<p>
|
|
If a message containing a <reactions> element arrives delayed, which
|
|
means it carries a <delay/> element, as defined in &xep0203; it SHOULD
|
|
only be accepted, if no newer reaction from the same sender was already
|
|
accepted.
|
|
</p>
|
|
</section2>
|
|
<section2 topic='Using the correct ID' anchor='business-id'>
|
|
<p>
|
|
For messages of type 'groupchat', the stanza's 'id' attribute MUST NOT be
|
|
used for reactions. Instead, in group chat situations, the ID assigned to
|
|
the stanza by the group chat itself must be used. This is discovered in a
|
|
<stanza-id> element with a 'by' attribute that matches the bare JID
|
|
of the group chat, as defined in &xep0359;.
|
|
</p>
|
|
<p>
|
|
This implies that group chat messages without a &xep0359; stanza-id cannot
|
|
be reacted to.
|
|
</p>
|
|
<p>
|
|
For other message types the sender should use the 'id' from a &xep0359;
|
|
<origin-id> if present, or the value of the 'id' attribute on the
|
|
<message> otherwise.
|
|
</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
|
<p>This document requires no interaction with &IANA;.</p>
|
|
</section1>
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<section2 topic='Protocol Namespaces' anchor='ns'>
|
|
<p>The ®ISTRAR; includes 'urn:xmpp:reactions:0' in its registry of protocol namespaces (see &NAMESPACES;).</p>
|
|
<ul>
|
|
<li>urn:xmpp:reactions:0</li>
|
|
</ul>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='XML Schema' anchor='schema'>
|
|
<section2 topic='urn:xmpp:reactions:0' anchor='schema-reactions'>
|
|
<code><![CDATA[
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
|
|
|
<xs:schema
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
|
targetNamespace='urn:xmpp:reactions:0'
|
|
xmlns='urn:xmpp:reactions:0'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:element name='reactions'>
|
|
<xs:complexType>
|
|
<xs:sequence minOccurs='0' maxOccurs='unbounded'>
|
|
<xs:element name='reaction' type='xs:string'/>
|
|
</xs:sequence>
|
|
<xs:attribute name='id' type='xs:string' use='required'/>
|
|
</xs:complexType>
|
|
</xs:element>
|
|
|
|
</xs:schema>]]></code>
|
|
</section2>
|
|
</section1>
|
|
</xep>
|