Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New XEP: Chat Notification Settings #1347

Closed
wants to merge 2 commits into from
Closed

New XEP: Chat Notification Settings #1347

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ce89be8
New XEP: Chat Notification Settings
truenicoco Jun 4, 2024
3ec9783
Update notification settings XEP after community feedback
truenicoco Jun 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 138 additions & 0 deletions xep-notification-filter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY namespace "urn:xmpp:notification-settings:0">
<!ENTITY xep-number "xxxx">
<!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.0.2</version>
<date>2024-02-08</date>
<initials>nc</initials>
<remark><p>Update after discussions on the standards@ mailing list.</p></remark>
<version>0.0.1</version>
<date>2024-02-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>
16 changes: 8 additions & 8 deletions xep.ent
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1158,6 +1158,14 @@ IANA Service Location Protocol, Version 2 (SLPv2) Templates</link></span> <note>
<jid>[email protected]</jid>
</author>
" >
<!ENTITY nicoco "
<author>
<firstname>Nicolas</firstname>
<surname>Cedilnik</surname>
<email>[email protected]</email>
<jid>[email protected]</jid>
</author>
" >
<!ENTITY moparisthebest "
<author>
<firstname>Travis</firstname>
Expand All @@ -1166,14 +1174,6 @@ IANA Service Location Protocol, Version 2 (SLPv2) Templates</link></span> <note>
<jid>[email protected]</jid>
<uri>https://moparisthebest.com/</uri>
</author>
" >
<!ENTITY nicoco "
<author>
<firstname>Nicolas</firstname>
<surname>Cedilnik</surname>
<email>[email protected]</email>
<jid>[email protected]</jid>
</author>
" >

<!-- XMPP Extension Protocols -->
Expand Down
Loading