diff --git a/api/client-server/pushrules.yaml b/api/client-server/pushrules.yaml index fc5c7895..e29e5a7e 100644 --- a/api/client-server/pushrules.yaml +++ b/api/client-server/pushrules.yaml @@ -360,7 +360,8 @@ paths: x-example: someRuleId description: |- Use 'before' with a ``rule_id`` as its value to make the new rule the - next-most important rule with respect to the given rule. + next-most important rule with respect to the given user defined rule. + It is not possible to add a rule relative to a predefined server rule. - in: query type: string name: after @@ -368,7 +369,8 @@ paths: x-example: anotherRuleId description: |- This makes the new rule the next-less important rule relative to the - given rule. + given user defined rule. It is not possible to add a rule relative + to a predefined server rule. - in: body name: pushrule description: |- diff --git a/specification/modules/push.rst b/specification/modules/push.rst index ea8cea7b..3bac810c 100644 --- a/specification/modules/push.rst +++ b/specification/modules/push.rst @@ -195,14 +195,73 @@ 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: -``.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):: +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.contains_user_name" + "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): + +.. code:: json + + { + "rule_id": ".m.rule.contains_user_name", + "default": true, + "enabled": true, "pattern": "[the local part of the user's Matrix ID]", "actions": [ "notify", @@ -210,17 +269,58 @@ server-default rules are specified: "set_tweak": "sound", "value": "default" } - ], + ] } -``.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. +Default Underride Rules +^^^^^^^^^^^^^^^^^^^^^^^ - Definition (this rule can only be an ``override`` or ``underride`` rule):: +``.m.rule.call`` +```````````````` +Matches any incoming VOIP call. + +Definition: + +.. code:: json { - "rule_id": ".m.rule.contains_display_name" + "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: + +.. code:: json + + { + "rule_id": ".m.rule.contains_display_name", + "default": true, + "enabled": true, "conditions": [ { "kind": "contains_display_name" @@ -231,21 +331,29 @@ 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. +``````````````````````````` +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_one_to_one", + "default": true, + "enabled": true, "conditions": [ { - "is": "2", - "kind": "room_member_count" + "kind": "room_member_count", + "is": "2" } ], "actions": [ @@ -253,46 +361,83 @@ server-default rules are specified: { "set_tweak": "sound", "value": "default" - } - ], - } - -``.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:: - - { - 'rule_id': '.m.rule.suppress_notices', - 'conditions': [ + }, { - 'kind': 'event_match', - 'key': 'content.msgtype', - 'pattern': 'm.notice', + "set_tweak": "highlight", + "value": false } - ], - 'actions': [ - 'dont-notify', ] } - -``.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.invite_for_me`` +````````````````````````` +Matches any invites to a new room for this user. + +Definition: + +.. code:: json { - "rule_id": ".m.rule.fallback" - "conditions": [], - "actions": [ - "notify" + "rule_id": ".m.rule.invite_for_me", + "default": true, + "enabled": true, + "conditions": [ + { + "key": "type", + "kind": "event_match", + "pattern": "m.room.member" + }, + { + "key": "content.membership", + "kind": "event_match", + "pattern": "invite" + }, + { + "key": "state_key", + "kind": "event_match", + "pattern": "[the user's Matrix ID]" + } ], + "actions": [ + "notify", + { + "set_tweak": "sound", + "value": "default" + }, + { + "set_tweak": "highlight", + "value": false + } + ] } +``.m.rule.message`` +``````````````````` +Matches all chat messages. + +Definition: + +.. code:: json + + { + "rule_id": ".m.rule.message", + "default": true, + "enabled": true, + "conditions": [ + { + "kind": "event_match", + "key": "type", + "pattern": "m.room.message" + } + ], + "actions": [ + "notify", + { + "set_tweak": "highlight", + "value": false + } + ] + } Conditions diff --git a/specification/targets.yaml b/specification/targets.yaml index 2555b36e..d759a7e8 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -54,7 +54,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/event_context.rst -title_styles: ["=", "-", "~", "+", "^", "`", "@"] +title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"] # The templating system doesn't know the right title style to use when generating # RST. These symbols are 'relative' to say "make a sub-title" (-1), "make a title