xeps/xep-0430.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
        <!ENTITY ns "urn:xmpp:inbox:1">
        <!ENTITY nsx "urn:example:">
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Inbox</title>
  <abstract>This specification proposes a mechanism by which clients can find a list of ongoing conversations and their state.</abstract>
  &LEGALNOTICE;
  <number>0430</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0313</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>inbox</shortname>
  &dcridland;
  <revision>
    <version>0.2.0</version>
    <date>2020-02-03</date>
    <initials>dwd</initials>
    <remark>Updates from the Summit 24 discussion:
      <ul>
        <li>Remove Marked</li>
        <li>Metadata in sibling</li>
        <li>Ensure the last "mam id" is present in metadata, and describe how that can be used.</li>
        <li>Add options to control unread-only and elide messages.</li>
      </ul>
    </remark>
  </revision>
  <revision>
    <version>0.1.0</version>
    <date>2020-01-29</date>
    <initials>XEP Editor (jsc)</initials>
    <remark>Accepted by vote of Council on 2020-01-22.</remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2019-12-30</date>
    <initials>dwd</initials>
    <remark>
      <ul>
        <li>Initial Revision</li>
      </ul>
    </remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>When initially run, a messaging client typically shows some list of contacts and chatrooms, and whether any new
    messages are present in each.</p>
  <p>The current mechanism for achieving this UX involves a complete synchronization of the server-side archive, and is both
    time-consuming and bandwidth-intensive. This specification proposes a solution to directly obtain such data from
    the server.</p>
  <p>Moreover, the information gathered by the server to support this can be used in support of mobile push notifications.</p>
  <section2 topic="Terminology">
    <p>Nomenclature used for instant messages versus ancillary messages will need to be adjusted to make it consistent
      with &xep0422; et al.</p>
  </section2>
</section1>

<section1 topic='Overview' anchor="overview">
  <section2 topic="Discovering Support" anchor="feature">
    <p>Support for this protocol is advertised by the Service Discovery protocol defined in &xep0030; using a feature
      of <tt>&ns;</tt>.</p>
  </section2>
  <section2 topic="The Inbox">
    <p>The Inbox consists semantically of a list of conversations in order of last activity. Each conversation is
      identified by a jid - for group chats this would be the chatroom, and for individual contacts this would be their
      bare jid.</p>
    <p>Each Inbox entry includes a count of messages considered new, the last MAM stanza-id relating to this conversation,
      and the last MAM result for this conversation, as defined by &xep0313;. In addition, a client-controlled boolean
      marker can be used to indicate a manual "set unread" state.</p>
    <p>Finding more messages from this conversation can be achieved via a MAM query using <tt>with</tt> to specify the
      conversation required.</p>
  </section2>
</section1>

  <section1 topic="Protocol Elements">
    <section2 topic="Querying">
      <p>An &IQ; of type "get" is used, containing a single element <tt>&lt;inbox/></tt>, containing an optional RSM
        filter as specified by &xep0059;. This will typically be sent only to the user's own bare jid. If a client
        requests the inbox without RSM, the server MAY limit the number of conversations arbitrarily by either time or number. This element has a number of attributes:</p>
      <ul>
        <li><tt>unread-only</tt> - Defaults to false. If true, the server will list only conversations with at least one unread message.</li>
        <li><tt>messages</tt> - Defaults to true. If true, the server includes the last message; if false, this is elided.</li>
      </ul>
      <p>The server
        responds with a sequence of &MESSAGE; stanzas, each containing an <tt>&lt;entry/></tt> element qualified by the
        <tt>&ns;</tt> namespace with a number of attributes:</p>
      <ul>
        <li><tt>jid</tt> - contains the Jid of the conversation for this entry.</li>
        <li><tt>unread</tt> - contains a count of messages which are deemed to be unread by the server. Clients may use this to indicate unread messages to the user.</li>
        <li><tt>id</tt> - contains the last id in the MAM archive for this conversation. Clients may use this as a marker to fetch additional messages (or collated fastenings, see &xep0427;) about the conversation via MAM.</li>
      </ul>
      <p>If the <tt>messages</tt> attribute is missing or set to <tt>true</tt>, the <tt>&lt;entry/></tt> element is followed by the latest instant message, if any, which is encapsulated as a
        <tt>&lt;result/></tt> element as defined by &xep0313;. This contains collated fastenings if supported by the
        server.</p>
      <p>After all entries required have been returned, the server then responds with an &IQ; result containing a
        <tt>&lt;fin/></tt> element qualified by <tt>&ns;</tt>. This contains the RSM data, a total count of conversation
        entries within the inbox, a count of conversations with unread messages, and a total count of unread messages.</p>
    </section2>
  </section1>

  <section1 topic="Unread Messages">
    <p>Servers MUST track which instant messages sent to clients remain unread.</p>
    <ul>
      <li>An instant message is always read if it is followed by an instant message which is read.</li>
      <li>An instant message always starts unread.</li>
      <li>A Chat Marker (see &xep0333;) of "displayed" or "acknowledged" causes the message to be read (and also causes
      all prior messages to be read by implication).</li>
      <li>A Message Receipt (see &xep0184;) does not cause messages to be considered unread.</li>
      <li>Unmarking a conversation always sets the unread counter to zero, and by implication sets all messages to be
        read.</li>
    </ul>
  </section1>

  <section1 topic="Examples">
    <p>Let us assume a user has only three jids they have exchanged messages with. Asking for their inbox is simple:</p>
    <example><![CDATA[
    <iq type='get' id='iq_stanza_id'>
      <inbox xmlns=']]>&ns;<![CDATA['/>
    </iq>
    ]]></example>
    <p>The server responds with a list of conversations:</p>
    <example><![CDATA[
    <message>
      <entry xmlns=']]>&ns;<![CDATA[' unread='5' jid='first_contact@example.net' id='uuid-1'/>
      <result xmlns='urn:xmpp:mam:2' queryid='iq_stanza_id' id='uuid-1'>
        <forwarded xmlns='urn:xmpp:forward:0'>
          <message xmlns='jabber:client' from='first_contact@example.net' to='user@example.org' type='chat'>
            <body>Greetings from Alpha Centauri!</body>
          </message>
        </forwarded>
      </result>
    </message>

    <message>
      <entry xmlns=']]>&ns;<![CDATA[' unread='0' jid='second_contact@example.net' id='uuid-5'/>
      <result xmlns='urn:xmpp:mam:2' queryid='iq_stanza_id' id='uuid-5'>
        <forwarded xmlns='urn:xmpp:forward:0'>
          <message xmlns='jabber:client' from='second_contact@example.net' to='user@example.org' type='chat'>
            <body>Greetings from Mars!</body>
          </message>
        </forwarded>
      </result>
    </message>

    <message>
      <entry xmlns=']]>&ns;<![CDATA[' unread='1' jid='third_contact@example.net' id='uuid-8'/>
      <result xmlns='urn:xmpp:mam:2' queryid='iq_stanza_id' id='uuid-8'>
        <forwarded xmlns='urn:xmpp:forward:0'>
          <message xmlns='jabber:client' from='third_contact@example.net' to='user@example.org' type='chat'>
            <body>Greetings from Somewhere Else!</body>
          </message>
        </forwarded>
      </result>
    </message>
    ]]></example>
    <p>If the <tt>id</tt> of a conversation has changed, a client might fetch the missing messages and metadata by requesting the MAM archive <tt>with</tt> the <tt>jid</tt> of the entry, and <tt>after</tt> the previous known <tt>id</tt> for the conversation.</p>
    <p>After the list of conversations, the server completes its response with a the reply to the original IQ.</p>
    <example><![CDATA[
      <iq type='result' id='iq_stanza_id'>
        <fin xmlns=']]>&ns;<![CDATA[' total='3' unread='2' all-unread='6'>
          <!-- RSM -->
        </fin>
    ]]></example>
  </section1>

  <section1 topic="Schema">
    <p>TODO - Hopefully roughly given by the examples.</p>
  </section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>TODO</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This XEP requires no interaction with &IANA;. </p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <p>None.</p>
</section1>

<section1 topic='Acknowledgements' anchor='ack'>
  <p>The author notes that this protocol is heavily based on the <tt>mod_inbox</tt> system of MongooseIM. In addition, Kevin Smith and several others at the XMPP Summit 24 provided useful feedback which has shaped this specification.</p>
</section1>

</xep>