xep-0492.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY namespace "urn:xmpp:notification-settings:0">
  <!ENTITY xep-number "0492">
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Chat notification settings</title>
  <abstract>This document defines an XMPP protocol extension to synchronise per-chat notification settings across different clients.</abstract>
  &LEGALNOTICE;
  <number>&xep-number;</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
    <spec>XEP-0163</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>notification-settings</shortname>
  &nicoco;
  <revision>
    <version>0.1.0</version>
    <date>2024-07-01</date>
    <initials>XEP Editor: dg</initials>
    <remark>
      <ul>
        <li>Promoted to Experimental</li>
      </ul>
    </remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2024-06-08</date>
    <initials>nc</initials>
    <remark><p>Update after discussions on the standards@ mailing list.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2024-06-06</date>
    <initials>nc</initials>
    <remark><p>Initial version.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>"Notifications" are (usually) pop-up windows that appear in a visible area of the screen even when the emitting application is in the background, often triggering a sound alert. <em>Instant</em> messaging clients expectedly use notifications to inform users when they receive a message.</p>
  <p>Users may want to customise which conversations should trigger notifications and under which conditions. In practice, this is already implemented in many instant messaging clients, including XMPP clients. This specification proposes a mechanism to synchronise per-discussion notification settings across different XMPP clients.</p>
</section1>
<section1 topic='Protocol' anchor='protocol'>
  <section2 topic='The notify element' anchor='notify'>
  <p>Notification settings are represented by the &lt;notify&gt; element. This element MUST be a child of an element identifying a specific chat by its JID, such as a &xep0402; &lt;extensions&gt;.</p>
  <p>This protocol specifies three children for the &lt;notify&gt; element, each corresponding to a notification setting: &lt;always&gt; &lt;on-mention&gt; and &lt;never&gt;.</p>
<example caption='Most basic example'><![CDATA[
<notify xmlns=']]>&namespace;<![CDATA['>
  <never />
</notify>
]]></example>
  </section2>
  <section2 topic='Client types' anchor='client-types'>
    <p>One might want to choose different notification settings depending on the client type. In this case, a "client-type" attribute can be added to the notification setting, using registered Service Discovery Identities.</p>
<example caption='An example of notification settings by client type'><![CDATA[
<notify xmlns=']]>&namespace;<![CDATA['>
  <never client-type="pc" />
  <on-mention client-type="mobile" />
</notify>
]]></example>
  </section2>
  <section2 topic='Advanced notification settings' anchor='advanced'>
  <p>Finally, clients can use this specification to synchronise finer-grained notification settings using custom namespaces.</p>
<example caption='An example of notification settings by client type'><![CDATA[
<notify xmlns=']]>&namespace;<![CDATA['>
  <never client-type="pc" />
  <on-mention client-type="mobile" />
  <advanced>
    <custom-extension xmlns="custom:ns-1">
      <when day-of-week="monday">night-time-only</day-of-week>
      ...
    </custom-extension">
    <custom-extension-2 xmlns="custom:ns-2">
      <weather>raining</weather>
      ...
    </custom-extension-2">
  </advanced>
</notify>
]]></example>
  </section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
  <p>Entities implementing this specification MUST NOT delete or alter the advanced notification settings they do not support when updating the notification settings for a given chat.</p>
  <p>If there is more than one notification setting for a given chat, entities implementing this specification MUST specify which client type they apply to. The (notification setting, client-type) pairs MUST be unique.</p>
  <p>Entities using advanced notification settings SHOULD attempt to provide the basic notification setting which is the closest to what they offer as a fallback for other entities.</p>
  <p>The "on-mention" notification MAY rely on the user's nickname being spelled out in an incoming message in a group chat, but SHOULD rely on mechanisms to explicitly "ping" the user, such as a &xep0461; element referring a user's previous message or a specific mention, such as a &xep0372; mention.</p>
  <p>In the absence of a notification settings for a given chat, "always" SHOULD be assumed for direct chats and private group chats, and "on-mention" for public group chats.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>See considerations in &xep0402;.</p>
</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='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>&namespace;</li>
    </ul>
    <p>The &REGISTRAR; includes this namespace in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </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=']]>&namespace;<![CDATA['
    xmlns=']]>&namespace;<![CDATA['
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-]]>&xep-number;<![CDATA[: http://www.xmpp.org/extensions/xep-]]>&xep-number;<![CDATA[.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='notify'>
    <xs:complexType>
      <xs:attribute name='when' default='always'>
        <xs:restriction base='xs:NCName'>
          <xs:enumeration value='always'/>
          <xs:enumeration value='never'/>
          <xs:enumeration value='on-mention'/>
        </xs:restriction>
      </xs:attribute>
    </xs:complexType>
  </xs:element>
</xs:schema>
]]></code>
</section1>
</xep>