<?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 specification defines an XMPP protocol extension for message receipts, whereby the sender of a message can request notification that it has been received by the intended recipient.</abstract>
  &LEGALNOTICE;
  <number>0184</number>
  <status>Draft</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>receipts</shortname>
  <schemaloc>
    <url>http://www.xmpp.org/schemas/receipts.xsd</url>
  </schemaloc>
  &stpeter;
  &hildjj;
  <revision>
    <version>1.0</version>
    <date>2007-09-26</date>
    <initials>psa</initials>
    <remark><p>Per a vote of the XMPP Council, advanced to Draft.</p></remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2007-05-30</date>
    <initials>psa</initials>
    <remark><p>Per Council feedback, modified to use dedicated namespace (not AMP).</p></remark>
  </revision>
  <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>
  <p>Note: This extension is functionally equivalent to an <cite>Advanced Message Processing</cite> rule of "receipt" but uses a dedicated namespace to simplify processing by end user clients and intermediate routers.</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 dedicated protocol extension qualified by the 'urn:xmpp:receipts' namespace.</p>
  <p>There are two allowable elements in this namespace:</p>
  <ul>
    <li>&lt;request/&gt; -- included by a sending entity that wishes to know if the message has been received.</li>
    <li>&lt;received/&gt; -- included by a receiving entity that wishes to inform the sending entity that the message has been received.</li>
  </ul>
  <p>Specifically, the receiving entity shall return a &lt;received/&gt; notice if it 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.</p>
  <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>
  <request xmlns='urn:xmpp:receipts'/>
</message>
  ]]></example>
  <p>The recipient shall generate a receipt if and only if it supports the protocol defined herein and it is configured to return receipts, either globally or for this recipient (otherwise it MUST NOT return a receipt and SHOULD NOT return an error).</p>
  <example caption='A message receipt'><![CDATA[
<message
    from='kingrichard@royalty.england.lit/throne'
    id='richard2-4.1.247'
    to='northumberland@shakespeare.lit/westminster'>
  <received xmlns='urn:xmpp:receipts'/>
</message>
  ]]></example>
  <p>The &lt;received/&gt; element SHOULD be the only child of the &MESSAGE; stanza and MUST mirror the 'id' of the sent message.</p>
</section1>
<section1 topic='Business Rules' anchor='rules'>
  <p>The following business rules apply:</p>
  <ol start='1'>
    <li><p>A sender SHOULD NOT include a request for message receipts when sending a message to the bare JID &LOCALBARE; of the recipient, only when sending to a full JID &LOCALFULL;.</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>
    <li><p>A sender SHOULD include an 'id' attribute on the message so that the sender can properly track the receipt.</p></li>
  </ol>
  <p>Naturally, message receipts can be combined with the rules specified in <cite>Advanced Message Processing</cite> (e.g., the deliver rule) for more complete reporting.</p>
</section1>
<section1 topic='Determining Support' anchor='disco'>
  <p>If a sender wishes to request message receipts, it SHOULD first determine whether the intended recipient supports message receipts. This can be done directly via <cite>Service Discovery</cite> or indirectly via <cite>Entity Capabilities</cite>.</p>
  <p>If an entity supports message receipts, it MUST report that by including a service discovery feature of "urn:xmpp:receipts" in response to disco#info requests:</p>
  <example caption="Initial Service Discovery information request"><![CDATA[
<iq from='northumberland@shakespeare.lit/westminster'
    id='disco1'
    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'
    id='disco1'
    to='northumberland@shakespeare.lit/westminster'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:receipts'/>
    ...
  </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>Stanza Session Negotiation</cite>. The parameter to be negotiated is named "urn:xmpp:receipts". 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>urn:xmpp:ssn</value>
      </field>
      <field label='Accept this chat?'
             type='boolean' 
             var='accept'>
        <value>true</value>
        <required/>
      </field>
      <field label='Enable Message Receipts?'
             type='boolean' 
             var='urn:xmpp:receipts'>
        <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>urn:xmpp:ssn</value>
      </field>
      <field var='accept'>
        <value>true</value>
      </field>
      <field var='urn:xmpp:receipts'>
        <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='Protocol Namespaces' anchor='ns'>
    <p>The &REGISTRAR; includes "urn:xmpp:receipts" in its registry of protocol namespaces (see &NAMESPACES;).</p>
  </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 Stanza Session Negotiation forms:</p>
    <code caption='Registry Submission'><![CDATA[
<form_type>
  <name>urn:xmpp:ssn</name>
  <field
      var='urn:xmpp:receipts'
      type='boolean'
      label='Whether to enable Message Receipts per XEP-0184'/>
</form_type>
      ]]></code>
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:receipts'
    xmlns='urn:xmpp:receipts'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0184: http://www.xmpp.org/extensions/xep-0184.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='received' type='empty'/>

  <xs:element name='request' type='empty'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
  ]]></code>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to Joe Kemp and Kevin Smith for their input.</p>
</section1>
</xep>
