This document specifies a protocol for XMPP message receipts.
WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.
Status: Experimental
Type: Standards Track
Number: 0184
Version: 0.1
Last Updated: 2006-04-11
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: amp-receipts
Wiki Page: <http://wiki.jabber.org/index.php/Message Receipts (JEP-0184)>
Email:
stpeter@jabber.org
JID:
stpeter@jabber.org
Email:
jhildebrand@jabber.com
JID:
hildjj@jabber.org
This Jabber Enhancement Proposal is copyright 1999 - 2006 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software 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 JEP 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 keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
While Advanced Message Processing [1] 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.
This document addresses the following requirements:
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".
In general there are five possible scenarios (where "S" stands for sender and "R" stands for recipient):
Example 1. Scenario 1: Happy Path
S R | | | ------------------------------------> | | send message | | | | <------------------------------------ | | send receipt | | |
In Scenario 1, the use case ends successfully with message delivery, receipt delivery, and no retries.
Example 2. Scenario 2: Message Not Received
S R | | | -----------------------------x | | send message | | | | [trigger timeout] | | | | ------------------------------------> | | re-send message | | | | <------------------------------------ | | send receipt | | |
In Scenario 2, the use case ends successfully with message delivery failure, message retry, and receipt delivery.
Example 3. Scenario 3: Receipt Not Received
S R | | | ------------------------------------> | | send message | | | | x------------------------------- | | send receipt | | | | [trigger timeout] | | | | ------------------------------------> | | re-send message | | | | <------------------------------------ | | send receipt | | |
In Scenario 3, the use case ends successfully with message delivery, receipt delivery failure, message retry, and receipt delivery.
Example 4. Scenario 4: Message Sent, Sender Goes Offline
S R | | | ------------------------------------> | | send message | | | | ------------------------------------> | | send presence unavailable | | |
In Scenario 4, the use case ends unsuccessfully with message delivery and the sender generating presence unavailable (because the sender has gone offline, the recipient has no one to send the receipt to).
Example 5. Scenario 5: Message Sent, Recipient Goes Offline
S R | | | ------------------------------------> | | send message | | | | <------------------------------------ | | send presence unavailable | | |
In Scenario 5, the use case ends unsuccessfully with message delivery and the recipient generating presence unavailable (because the recipient has gone offline before sending a receipt, the sender cannot be sure that the message has been received).
In order to make it possible for senders to request, and for recipients to generate, message receipts, we define a new Advanced Message Processing rule: "receipt". In accordance with JEP-0079, we provide the following information about the receipt rule:
The following is an example of a message that includes a request for return receipt.
Example 6. A message with receipt requested
<message
from='northumberland@shakespeare.lit'
id='richard2-4.1.247'
to='kingrichard@royalty.england.lit'>
<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>
If the recipient supports Advanced Message Processing and the "receipt" rule, it MUST generate a receipt:
Example 7. A message receipt
<message
from='kingrichard@royalty.england.lit/throne'
id='richard2-4.1.247'
to='northumberland@shakespeare.lit'>
<amp xmlns='http://jabber.org/protocol/amp' status='notify'>
<rule condition='receipt' action='notify' value='received'/>
</amp>
</message>
The general business rules specified for Advanced Message Processing in JEP-0079 apply to any rule; in addition, the following business rules apply specifically to the receipt rule:
A sender SHOULD NOT include a request for message receipts unless it knows (via Service Discovery [4] or Entity Capabilities [5]) that the intended recipient supports the protocol described herein or unless the use of message receipts is negotiated via Chat Session Negotiation [6].
The sender (i.e., the message generating application controlled by the sender) MUST initiate a timeout upon sending each message, which timeout SHOULD be 30 seconds. If the sender does not receive a message receipt (or failure event) within its timeout period, it MUST re-send the message with an identical value of the XMPP 'id' attribute.
The sender MUST NOT send a large number of retries. How many retries are appropriate depends on how important the message is perceived to be. In any case, a sender SHOULD NOT send more than five retries.
The recipient (i.e., the message processing application controlled by the intended recipient that receives a given message) MUST initiate a timeout upon sending each message receipt, which timeout SHOULD be 60 seconds. If the recipient does not receive a re-sent message within its timeout period, it SHOULD stop waiting for a re-sent message and discard memory of that message ID.
The recipient MUST NOT include a request for message receipts in its acknowledgements. If the sender receives a request for message receipts in an acknowledgement, it MUST NOT acknowledge the acknowledement.
The recipient SHOULD send the message receipt once it has processed the message, which may include presenting it to a human user (e.g., visually or aurally). The receiving application SHOULD NOT require a human user to positively affirm that he or she has read and understood the message before sending the receipt, since this is unnecessarily intrusive in the context of instant messaging.
This document covers one use case: sending messages with return receipt requested, for which succcess is defined as the sender receiving a message receipt. As described above, there are five possible scenarios. These are described in more detail in the following sections.
In the "happy path", the sender sends the message and the recipient returns a receipt within the sender's timeout period.
Example 8. A message with receipt requested
<message
from='northumberland@shakespeare.lit'
id='richard2-4.1.247'
to='kingrichard@royalty.england.lit'>
<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 9. A message receipt
<message
from='kingrichard@royalty.england.lit/throne'
id='richard2-4.1.247'
to='northumberland@shakespeare.lit'>
<amp xmlns='http://jabber.org/protocol/amp' status='notify'>
<rule condition='receipt' action='notify' value='received'/>
</amp>
</message>
In this scenario the sender sends the message but it is not received for whatever reason; therefore the sender resends the message after the timeout period expires, the resent message is received, and the recipient returns a receipt within the sender's (second) timeout period.
Example 10. A message with receipt requested
<message
from='northumberland@shakespeare.lit'
id='richard2-4.1.247'
to='kingrichard@royalty.england.lit'>
<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>
The message is not received and the sender does not receive a receipt within the sender's timeout period; therefore the sender resends the message.
Example 11. A message with receipt requested
<message
from='northumberland@shakespeare.lit'
id='richard2-4.1.247'
to='kingrichard@royalty.england.lit'>
<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>
Now the message is received and the recipient returns a receipt.
Example 12. A message receipt
<message
from='kingrichard@royalty.england.lit/throne'
id='richard2-4.1.247'
to='northumberland@shakespeare.lit'>
<amp xmlns='http://jabber.org/protocol/amp' status='notify'>
<rule condition='receipt' action='notify' value='received'/>
</amp>
</message>
In this scenario the sender sends the message and it not received, but the message receipt is not received for whatever reason; therefore the sender resends the message after the timeout period expires, the resent message is received, and the recipient returns a receipt within the sender's (second) timeout period.
Example 13. A message with receipt requested
<message
from='northumberland@shakespeare.lit'
id='richard2-4.1.247'
to='kingrichard@royalty.england.lit'>
<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>
The message is received and the recipient returns a receipt.
Example 14. A message receipt
<message
from='kingrichard@royalty.england.lit/throne'
id='richard2-4.1.247'
to='northumberland@shakespeare.lit'>
<amp xmlns='http://jabber.org/protocol/amp' status='notify'>
<rule condition='receipt' action='notify' value='received'/>
</amp>
</message>
The message receipt is not received by the sender within the sender's timeout period; therefore the sender resends the message.
Example 15. A message with receipt requested
<message
from='northumberland@shakespeare.lit'
id='richard2-4.1.247'
to='kingrichard@royalty.england.lit'>
<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>
The resent message is received and the recipient returns a receipt, which is received by the sender within the sender's (second) timeout period.
Example 16. A message receipt
<message
from='kingrichard@royalty.england.lit/throne'
id='richard2-4.1.247'
to='northumberland@shakespeare.lit'>
<amp xmlns='http://jabber.org/protocol/amp' status='notify'>
<rule condition='receipt' action='notify' value='received'/>
</amp>
</message>
In this scenario the sender sends the message but immediately goes offline. Therefore the recipient MUST NOT send a receipt.
Example 17. A message with receipt requested
<message
from='northumberland@shakespeare.lit'
id='richard2-4.1.247'
to='kingrichard@royalty.england.lit'>
<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 18. Sender goes offline
<presence
from='northumberland@shakespeare.lit/westminster'
to='kingrichard@royalty.england.lit/throne'
type='unavailable'>
The use case ends unsuccessfully, since the sender did not receive a receipt.
In this scenario the sender sends the message but receives unavailable presence from the recipient before receiving a receipt within the timeout period.
Example 19. A message with receipt requested
<message
from='northumberland@shakespeare.lit'
id='richard2-4.1.247'
to='kingrichard@royalty.england.lit'>
<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 20. Recipient goes offline
<presence
from='kingrichard@royalty.england.lit/throne'
to='northumberland@shakespeare.lit/westminster'
type='unavailable'>
The use case ends unsuccessfully, since the sender did not receive a receipt.
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 Entity Capabilities or directly via Service Discovery.
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 JEP-0079:
Example 21. Initial Service Discovery information request
<iq from='northumberland@shakespeare.lit/westminster'
to='kingrichard@royalty.england.lit/throne'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
Example 22. Service Discovery information response
<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>
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 'http://jabber.org/protocol/amp?condition=receipt' condition:
Example 23. Request for information about individual actions and conditions
<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 24. Response for individual actions and conditions
<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>
Two entities MAY negotiate the use of message receipts for a given session using Chat Session Negotiation. The parameter to be negotiated is named "http://jabber.org/protocol/amp?condition=receipt". Its use is illustrated in the following examples.
Example 25. User requests chat session
<message type='normal'
from='northumberland@shakespeare.lit/westminster'
to='kingrichard@royalty.england.lit'
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 26. Contact accepts offer and specifies parameters
<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>
To follow.
No interaction with the Internet Assigned Numbers Authority (IANA) [7] is necessary as a result of this JEP.
The Jabber Registrar [8] maintains a registry of Advanced Message Processing <rule/> conditions (see <http://www.jabber.org/registrar/amp-actions.html>). The Registrar shall add the following condition to the registry:
<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>JEP-xxxx</doc>
</condition>
Field Standardization for Data Forms [9] defines a process for standardizing the fields used within Data Forms qualified by a particular namespace and the Jabber Registrar maintains a registry of such fields (see <http://www.jabber.org/registrar/formtypes.html>). The Registrar shall add the following field for use in Chat Session Negotiation forms:
Registry Submission
<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 JEP-0184'/>
</form_type>
Thanks to Joe Kemp for his input.
1. JEP-0079: Advanced Message Processing <http://www.jabber.org/jeps/jep-0079.html>.
2. Therefore this specification does not distinguish between delivery and presentation, as was done in Message Events [3].
3. JEP-0022: Message Events <http://www.jabber.org/jeps/jep-0022.html>.
4. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.
5. JEP-0115: Entity Capabilities <http://www.jabber.org/jeps/jep-0115.html>.
6. JEP-0155: Chat Session Negotiation <http://www.jabber.org/jeps/jep-0155.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 Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.
9. JEP-0068: Field Data Standardization for Data Forms <http://www.jabber.org/jeps/jep-0068.html>.
Initial JEP version.
(psa)Added text and examples for service discovery; added text and examples for chat session negotiation; added recommendations regarding message processing, retries, etc.
(psa)First draft.
(psa)END