diff --git a/changelogs/client_server/newsfragments/2634.clarification b/changelogs/client_server/newsfragments/2634.clarification new file mode 100644 index 00000000..64d9f142 --- /dev/null +++ b/changelogs/client_server/newsfragments/2634.clarification @@ -0,0 +1 @@ +Minor clarifications to the "Push Notifications" module. diff --git a/specification/modules/push.rst b/specification/modules/push.rst index ebf1aef2..37b149bc 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -33,13 +33,13 @@ Push Notifications Matrix | | | | | | Client/Server API + | | | | | | | +--------------------+ +-------------------+ - | +--+-+ | - | | <-------------------------------------------+ - +---+ | - | | Provider Push Protocol - +----+ - - Mobile Device or Client + | +--+-+ | + | | <-------------------------------------------+ + +---+ | + | | Provider Push Protocol + +----+ + + Mobile Device or Client This module adds support for push notifications. Homeservers send notifications @@ -135,8 +135,9 @@ There are different "kinds" of push rules and each rule has an associated priority. Every push rule MUST have a ``kind`` and ``rule_id``. The ``rule_id`` is a unique string within the kind of rule and its' scope: ``rule_ids`` do not need to be unique between rules of the same kind on different devices. Rules may -have extra keys depending on the value of ``kind``. The different kinds of rule -in descending order of priority are: +have extra keys depending on the value of ``kind``. + +The different ``kind``\ s of rule, in the order that they are checked, are: Override Rules ``override`` The highest priority rules are user-configured overrides. @@ -156,15 +157,6 @@ Underride rules ``underride`` These are identical to ``override`` rules, but have a lower priority than ``content``, ``room`` and ``sender`` rules. -This means that the full list of rule kinds, in descending priority order, is -as follows: - -* Global Override -* Global Content -* Global Room -* Global Sender -* Global Underride - Rules with the same ``kind`` can specify an ordering priority. This determines which rule is selected in the event of multiple matches. For example, a rule matching "tea" and a separate rule matching "time" would both match the sentence @@ -224,6 +216,55 @@ Tweaks are passed transparently through the homeserver so client applications and Push Gateways may agree on additional tweaks. For example, a tweak may be added to specify how to flash the notification light on a mobile device. +Conditions +++++++++++ + +``override`` and ``underride`` rules MAY have a list of 'conditions'. +All conditions must hold true for an event in order for the rule to match. +A rule with no conditions always matches. The following conditions are defined: + +``event_match`` + This is a glob pattern match on a field of the event. Parameters: + + * ``key``: The dot-separated field of the event to match, e.g. ``content.body`` + * ``pattern``: The glob-style pattern to match against. Patterns with no + special glob characters should be treated as having asterisks + prepended and appended when testing the condition. + +``contains_display_name`` + This matches unencrypted messages where ``content.body`` contains the owner's + display name in that room. This is a separate rule because display names may + change and as such it would be hard to maintain a rule that matched the user's + display name. This condition has no parameters. + +``room_member_count`` + This matches the current number of members in the room. Parameters: + + * ``is``: A decimal integer optionally prefixed by one of, ``==``, ``<``, + ``>``, ``>=`` or ``<=``. A prefix of ``<`` matches rooms where the member + count is strictly less than the given number and so forth. If no prefix is + present, this parameter defaults to ``==``. + +``sender_notification_permission`` + This takes into account the current power levels in the room, ensuring the + sender of the event has high enough power to trigger the notification. + + Parameters: + + * ``key``: A string that determines the power level the sender must have to trigger + notifications of a given type, such as ``room``. Refer to the `m.room.power_levels`_ + event schema for information about what the defaults are and how to interpret the event. + The ``key`` is used to look up the power level required to send a notification type + from the ``notifications`` object in the power level event content. + +Unrecognised conditions MUST NOT match any events, effectively making the push +rule disabled. + +``room``, ``sender`` and ``content`` rules do not have conditions in the same +way, but instead have predefined conditions. In the cases of ``room`` and +``sender`` rules, the ``rule_id`` of the rule determines its behaviour. + + Predefined Rules ++++++++++++++++ Homeservers can specify "server-default rules" which operate at a lower priority @@ -237,7 +278,7 @@ Default Override Rules ``.m.rule.master`` `````````````````` -Matches all events, this can be enabled to turn off all push notifications +Matches all events. This can be enabled to turn off all push notifications other than those generated by override rules set by the user. By default this rule is disabled. @@ -257,9 +298,7 @@ Definition ``.m.rule.suppress_notices`` ```````````````````````````` -Matches messages with a ``msgtype`` of ``notice``. This should be an -``override`` rule so that it takes priority over ``content`` / ``sender`` / -``room`` rules. +Matches messages with a ``msgtype`` of ``notice``. Definition: @@ -650,55 +689,6 @@ Definition: ] } - -Conditions -++++++++++ - -Override, Underride and Default Rules MAY have a list of 'conditions'. -All conditions must hold true for an event in order to apply the ``action`` for -the event. A rule with no conditions always matches. Room, Sender, User and -Content rules do not have conditions in the same way, but instead have -predefined conditions. These conditions can be configured using the parameters -outlined below. In the cases of room and sender rules, the ``rule_id`` of the -rule determines its behaviour. The following conditions are defined: - -``event_match`` - This is a glob pattern match on a field of the event. Parameters: - - * ``key``: The dot-separated field of the event to match, e.g. ``content.body`` - * ``pattern``: The glob-style pattern to match against. Patterns with no - special glob characters should be treated as having asterisks - prepended and appended when testing the condition. - -``contains_display_name`` - This matches unencrypted messages where ``content.body`` contains the owner's - display name in that room. This is a separate rule because display names may - change and as such it would be hard to maintain a rule that matched the user's - display name. This condition has no parameters. - -``room_member_count`` - This matches the current number of members in the room. Parameters: - - * ``is``: A decimal integer optionally prefixed by one of, ``==``, ``<``, - ``>``, ``>=`` or ``<=``. A prefix of ``<`` matches rooms where the member - count is strictly less than the given number and so forth. If no prefix is - present, this parameter defaults to ``==``. - -``sender_notification_permission`` - This takes into account the current power levels in the room, ensuring the - sender of the event has high enough power to trigger the notification. - - Parameters: - - * ``key``: A string that determines the power level the sender must have to trigger - notifications of a given type, such as ``room``. Refer to the `m.room.power_levels`_ - event schema for information about what the defaults are and how to interpret the event. - The ``key`` is used to look up the power level required to send a notification type - from the ``notifications`` object in the power level event content. - -Unrecognised conditions MUST NOT match any events, effectively making the push -rule disabled. - Push Rules: API ~~~~~~~~~~~~~~~