diff --git a/specification/modules/push.rst b/specification/modules/push.rst index 133b838a9..d0c3968ce 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -202,14 +202,70 @@ than "user-defined rules". The ``rule_id`` for all server-default rules MUST start with a dot (".") to identify them as "server-default". The following server-default rules are specified: + +Default Override Rules +^^^^^^^^^^^^^^^^^^^^^^ + +``m.rule.master`` + 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. + + Definition + +.. code:: json + + { + "rule_id": ".m.rule.master, + "default": true, + "enabled": false, + "conditions": [], + "actions": [ + "dont_notify" + ] + } + +``.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. + + Definition: + +.. code:: json + + { + "rule_id": ".m.rule.suppress_notices", + "default": true, + "enabled": true, + "conditions': [ + { + "kind": "event_match", + "key": "content.msgtype", + "pattern": "m.notice", + } + ], + "actions": [ + "dont_notify", + ] + } + + +Default Content Rules +^^^^^^^^^^^^^^^^^^^^^ + ``.m.rule.contains_user_name`` Matches any message whose content is unencrypted and contains the local part of the user's Matrix ID, separated by word boundaries. - Definition (as a ``content`` rule):: + Definition (as a ``content`` rule): + +.. code:: json { - "rule_id": ".m.rule.contains_user_name" + "rule_id": ".m.rule.contains_user_name", + "default": true, + "enabled": true, "pattern": "[the local part of the user's Matrix ID]", "actions": [ "notify", @@ -217,17 +273,56 @@ server-default rules are specified: "set_tweak": "sound", "value": "default" } - ], + ] } +Default Underride Rules +^^^^^^^^^^^^^^^^^^^^^^^ + +``.m.rule.call`` + Matches any incoming VOIP call. + + Definition: + +.. code:: json + + { + "rule_id": ".m.rule.call", + "default": true, + "enabled": true, + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.call.invite" + } + ], + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "ring" + }, + { + "set_tweak": "highlight", + "value": false + } + ] + }, + + ``.m.rule.contains_display_name`` Matches any message whose content is unencrypted and contains the user's current display name in the room in which it was sent. - Definition (this rule can only be an ``override`` or ``underride`` rule):: + Definition: + +.. code:: json { - "rule_id": ".m.rule.contains_display_name" + "rule_id": ".m.rule.contains_display_name", + "default": true, + "enabled": true, "conditions": [ { "kind": "contains_display_name" @@ -238,21 +333,28 @@ server-default rules are specified: { "set_tweak": "sound", "value": "default" + }, + { + "set_tweak": "highlight" } - ], + ] } ``.m.rule.room_one_to_one`` Matches any message sent in a room with exactly two members. - Definition (this rule can only be an ``override`` or ``underride`` rule):: + Definition: + +.. code:: json { - "rule_id": ".m.rule.room_two_members" + "rule_id": ".m.rule.room_two_members", + "default": true, + "enabled": true, "conditions": [ { - "is": "2", "kind": "room_member_count" + "is": "2", } ], "actions": [ @@ -260,46 +362,108 @@ server-default rules are specified: { "set_tweak": "sound", "value": "default" + }, + { + "set_tweak": "highlight", + "value": false } ], } -``.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. +``.m.rule.invite_for_me`` + Matches any invites to a new room for this user. - Definition:: + Definition: + +.. code:: json { - 'rule_id': '.m.rule.suppress_notices', - 'conditions': [ + "rule_id": ".m.rule.invite_for_me", + "default": true, + "enabled": true, + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + }, { - 'kind': 'event_match', - 'key': 'content.msgtype', - 'pattern': 'm.notice', + "key": "content.membership", + "kind": "event_match", + "pattern": "invite" + }, + { + "key": "state_key", + "kind": "event_match", + "pattern": "@alice:example.com" } ], - 'actions': [ - 'dont-notify', + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } ] } - -``.m.rule.fallback`` - Matches any message. Used to define the behaviour of messages that match no - other rules. If homeservers define this it should be the lowest priority - ``underride`` rule. - Definition:: +``.m.rule.member_event`` + Matches membership change events. - { - "rule_id": ".m.rule.fallback" - "conditions": [], - "actions": [ - "notify" + Definition: + +.. code:: json + + { + "rule_id": ".m.rule.member_event", + "default": true, + "enabled": true, + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + } ], - } + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ] + } +``.m.rule.message`` + Matches all chat messages. + + Definition: + +.. code:: json + + { + "rule_id": ".m.rule.member_event", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" + } + ], + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ] + } Conditions