<?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 Receipts</title> <abstract>This document specifies an XMPP protocol extension for message receipts.</abstract> &LEGALNOTICE; <number>0184</number> <status>Experimenal</status> <type>Standards Track</type> <sig>Standards</sig> <approver>Council</approver> <dependencies> <spec>XMPP Core</spec> </dependencies> <supersedes> <spec>XEP-0022 (in part)</spec> </supersedes> <supersededby/> <shortname>amp-receipts</shortname> &stpeter; &hildjj; <revision> <version>0.3</version> <date>2006-11-06</date> <initials>psa</initials> <remark><p>Removed reliability features, which belong at a different level.</p></remark> </revision> <revision> <version>0.2</version> <date>2006-09-21</date> <initials>psa</initials> <remark><p>Added two more scenarios; defined business rule about not sending to bare JIDs; specified security consideration regarding presence leaks.</p></remark> </revision> <revision> <version>0.1</version> <date>2006-04-11</date> <initials>psa</initials> <remark><p>Initial version.</p></remark> </revision> <revision> <version>0.0.2</version> <date>2006-04-07</date> <initials>psa</initials> <remark><p>Added text and examples for service discovery; added text and examples for chat session negotiation; added recommendations regarding message processing, retries, etc.</p></remark> </revision> <revision> <version>0.0.1</version> <date>2006-03-27</date> <initials>psa</initials> <remark><p>First draft.</p></remark> </revision> </header> <section1 topic='Introduction' anchor='intro'> <p>While &xep0079; provides message acknowledgements at the server level, it does not extend that model all the way to the client. However, sometimes client-level acknowledgements are needed, for example to provide "receipts". This document defines a mechanism for XMPP message receipts, which are functionally equivalent to the "delivered" or "displayed" event in &xep0022;, which this specification in part obsoletes. <note>This specification does not distinguish between delivery and presentation, as was done in the message events protocol, in part because no existing clients make the distinction.</note> </p> </section1> <section1 topic='Requirements' anchor='reqs'> <p>This document addresses the following requirements:</p> <ol> <li>Enable a sender to request notification that an XMPP message stanza has been received.</li> <li>Enable a recipient to provide message receipts if desired.</li> </ol> <p>Note: This document explicitly does not define a protocol for "guaranteed delivery", since that term (like "security") means different things to different people. Instead, we define a more focused protocol that addresses the need for message receipts, thus solving one problem that falls under the heading of "guaranteed delivery".</p> </section1> <section1 topic='Protocol Format' anchor='format'> <p>In order to make it possible for senders to request and for recipients to generate message receipts, we define a new <cite>Advanced Message Processing</cite> rule: "receipt". In accordance with <cite>XEP-0079</cite>, we provide the following information about the receipt rule:</p> <ul> <li>The namespace shall be "http://jabber.org/protocol/amp?condition=receipt".</li> <li>The condition applies only to final receipt by the intended recipient; therefore, the per-hop flag does not apply.</li> <li>The only defined value of the receipt rule is "received".</li> <li>This condition is met if a message processing application (client) controlled by the intended recipient has received and processed the message; the term "processed" is understood to include presentation to a human user if appropriate or any other application-specific client-side processing, including generation of an error response if the application determines that the message contents cannot be handled.</li> <li>Although any defined action may be triggered, the only action needed in order to support message receipts is the "notify" action.</li> </ul> <p>The following is an example of a message that includes a request for return receipt.</p> <example caption='A message with receipt requested'><![CDATA[ <message from='northumberland@shakespeare.lit/westminster' id='richard2-4.1.247' to='kingrichard@royalty.england.lit/throne'> <body>My lord, dispatch; read o'er these articles.</body> <amp xmlns='http://jabber.org/protocol/amp'> <rule condition='receipt' action='notify' value='received'/> </amp> </message> ]]></example> <p>The recipient MUST generate a receipt if and only if it meets all of the following criteria:</p> <ol> <li>It supports Advanced Message Processing.</li> <li>It supports the "receipt" rule.</li> <li>It is configured to return receipts, either globally or for this recipient.</li> </ol> <example caption='A message receipt'><![CDATA[ <message from='kingrichard@royalty.england.lit/throne' id='richard2-4.1.247' to='northumberland@shakespeare.lit/westminster'> <amp xmlns='http://jabber.org/protocol/amp' status='notify'> <rule condition='receipt' action='notify' value='received'/> </amp> </message> ]]></example> <p>If the recipient does not meet all of the foregoing criteria, it MUST NOT return a receipt and MUST NOT return an error.</p> </section1> <section1 topic='Business Rules' anchor='rules'> <p>The general business rules specified for Advanced Message Processing in <cite>XEP-0079</cite> apply to any rule; in addition, the following business rules apply specifically to the receipt rule:</p> <ol start='1'> <li><p>A sender SHOULD NOT include a request for message receipts when sending a message to the bare JID (&BAREJID;) of the recipient, only when sending to a full JID (&FULLJID;).</p></li> <li><p>A sender SHOULD NOT include a request for message receipts unless it knows (via &xep0030; or &xep0115;) that the intended recipient supports the protocol described herein or unless the use of message receipts is negotiated via &xep0155;.</p></li> </ol> <p>Naturally, the receipt rule can be combined wiith rules specified in <cite>XEP-0079</cite> (e.g., the deliver rule) for more complete reporting.</p> </section1> <section1 topic='Service Discovery' anchor='disco'> <p>If a sender wishes to request message receipts, it SHOULD first discover whether the intended recipient supports message receipts. Support can be discovered indirectly via <cite>Entity Capabilities</cite> or directly via <cite>Service Discovery</cite>.</p> <p>If an entity supports Advanced Message Processing, it MUST report that by including a service discovery feature of "http://jabber.org/protocol/amp" as described in <cite>XEP-0079</cite>:</p> <example caption="Initial Service Discovery information request"><![CDATA[ <iq from='northumberland@shakespeare.lit/westminster' to='kingrichard@royalty.england.lit/throne' type='get'> <query xmlns='http://jabber.org/protocol/disco#info'/> </iq> ]]></example> <example caption="Service Discovery information response"><![CDATA[ <iq from='kingrichard@royalty.england.lit/throne' to='northumberland@shakespeare.lit/westminster' type='result'> <query xmlns='http://jabber.org/protocol/disco#info'> ... <feature var='http://jabber.org/protocol/amp'/> ... </query> </iq> ]]></example> <p>An entity that supports Advanced Message Processing SHOULD also maintain a service discovery node named "http://jabber.org/protocol/amp", at which it advertises the individual actions and conditions it supports. If an entity supports message receipts, it SHOULD respond to service discovery information requests sent to that node with a reply that includes the 'http://jabber.org/protocol/amp?condition=receipt' condition:</p> <example caption="Request for information about individual actions and conditions"><![CDATA[ <iq from='northumberland@shakespeare.lit/westminster' to='kingrichard@royalty.england.lit/throne' type='get'> <query xmlns='http://jabber.org/protocol/disco#info' node='http://jabber.org/protocol/amp'/> </iq> ]]></example> <example caption="Response for individual actions and conditions"><![CDATA[ <iq from='kingrichard@royalty.england.lit/throne' to='northumberland@shakespeare.lit/westminster' type='result'> <query xmlns='http://jabber.org/protocol/disco#info' node='http://jabber.org/protocol/amp'> ... <feature var='http://jabber.org/protocol/amp?condition=receipt'/> ... </query> </iq> ]]></example> </section1> <section1 topic='Negotiation' anchor='neg'> <p>Two entities MAY negotiate the use of message receipts for a given session using <cite>Chat Session Negotiation</cite>. The parameter to be negotiated is named "http://jabber.org/protocol/amp?condition=receipt". Its use is illustrated in the following examples.</p> <example caption="User requests chat session"><![CDATA[ <message type='normal' from='northumberland@shakespeare.lit/westminster' to='kingrichard@royalty.england.lit/throne' id='init1'> <thread>ffd7076498744578d10edabfe7f4a866</thread> <feature xmlns='http://jabber.org/protocol/feature-neg'> <x xmlns='jabber:x:data' type='form'> <field var='FORM_TYPE' type='hidden'> <value>http://jabber.org/protocol/chatneg</value> </field> <field label='Accept this chat?' type='boolean' var='accept'> <value>true</value> <required/> </field> <field label='Enable Message Receipts?' type='boolean' var='http://jabber.org/protocol/amp?condition=receipt'> <value>0</value> </field> </x> </feature> </message> ]]></example> <example caption="Contact accepts offer and specifies parameters"><![CDATA[ <message type='normal' from='kingrichard@royalty.england.lit/throne' to='northumberland@shakespeare.lit/westminster' id='init1'> <thread>ffd7076498744578d10edabfe7f4a866</thread> <feature xmlns='http://jabber.org/protocol/feature-neg'> <x xmlns='jabber:x:data' type='submit'> <field var='FORM_TYPE' type='hidden'> <value>http://jabber.org/protocol/chatneg</value> </field> <field var='accept'> <value>true</value> </field> <field var='http://jabber.org/protocol/amp?condition=receipt'> <value>1</value> </field> </x> </feature> </message> ]]></example> </section1> <section1 topic='Implementation Notes' anchor='impl'> <p>Although a sender MAY attempt to resend a message if it knows that the recipient supports message receipts and it does not receive a reply within some configurable timeout period, resend logic is out of scope for this specification.</p> </section1> <section1 topic='Security Considerations' anchor='security'> <p>It is possible for a recipient to leak its presence when returning message receipts; therefore, a recipient SHOULD NOT return message receipts to senders who are not otherwise authorized to view its presence.</p> </section1> <section1 topic='IANA Considerations' anchor='iana'> <p>No interaction with &IANA; is necessary as a result of this document.</p> </section1> <section1 topic='XMPP Registrar Considerations' anchor='registrar'> <section2 topic='Rule Conditions Registry' anchor='registrar-conditions'> <p>The ®ISTRAR; maintains a registry of Advanced Message Processing <rule/> conditions (see &CONDITIONS;). The Registrar shall add the following condition to the registry:</p> <code><![CDATA[ <condition> <name>receipt</name> <ns>http://jabber.org/protocol/amp?condition=receipt</ns> <per-hop>false</per-hop> <value>received</value> <processing> The condition is met if a message processing application (client) controlled by the intended recipient has received and processed the message, including presentation to a human user if appropriate. </processing> <doc>XEP-0184</doc> </condition> ]]></code> </section2> <section2 topic='Field Standardization' anchor='registrar-formtype'> <p>&xep0068; defines a process for standardizing the fields used within Data Forms qualified by a particular namespace and the XMPP Registrar maintains a registry of such fields (see &FORMTYPES;). The Registrar shall add the following field for use in Chat Session Negotiation forms:</p> <code caption='Registry Submission'><![CDATA[ <form_type> <name>http://jabber.org/protocol/chatneg</name> <field var='http://jabber.org/protocol/amp?condition=receipt' type='boolean' label='Whether to enable Message Receipts per XEP-0184'/> </form_type> ]]></code> </section2> </section1> <section1 topic='Acknowledgements' anchor='ack'> <p>Thanks to Joe Kemp and Kevin Smith for their input.</p> </section1> </xep>