From 3b036aefbb9458bb717e5ad032b3100494a16020 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 2 May 2023 13:04:39 -0400
Subject: [PATCH] Update push rule definitions.

---
 content/client-server-api/modules/push.md | 73 +++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md
index 9a2a671f..63e760c7 100644
--- a/content/client-server-api/modules/push.md
+++ b/content/client-server-api/modules/push.md
@@ -521,8 +521,43 @@ Definition:
 }
 ```
 
+**`.m.rule.is_user_mention`**
+
+Matches any message which contains the user's Matrix ID in the list of `user_ids`
+under the `m.mentions` property.
+
+Definition:
+
+```json
+{
+    "rule_id": ".m.rule.is_user_mention",
+    "default": true,
+    "enabled": true,
+    "conditions": [
+        {
+            "kind": "event_property_contains",
+            "key": "content.m\\.mentions.user_ids",
+            "value": "[the user's Matrix ID]"
+        }
+    ],
+    "actions": [
+        "notify",
+        {
+            "set_tweak": "sound",
+            "value": "default"
+        },
+        {
+            "set_tweak": "highlight"
+        }
+    ]
+}
+```
+
 **`.m.rule.contains_display_name`**
 
+As of `v1.7`, this rule is deprecated and should only be enabled if the event
+does not have an `m.mentions` property.
+
 Matches any message whose content contains the user's current display name
 in the room in which it was sent.
 
@@ -551,8 +586,43 @@ Definition:
 }
 ```
 
+**`.m.rule.is_room_mention`**
+
+Matches any message from a sender with the proper power level with the `room`
+property of the `m.mentions` property set to `true`.
+
+Definition:
+
+```json
+{
+    "rule_id": ".m.rule.is_room_mention",
+    "default": true,
+    "enabled": true,
+    "conditions": [
+        {
+            "kind": "event_property_is",
+            "key": "content.m\\.mentions.room",
+            "value": true
+        },
+        {
+            "kind": "sender_notification_permission",
+            "key": "room"
+        }
+    ],
+    "actions": [
+        "notify",
+        {
+            "set_tweak": "highlight"
+        }
+    ]
+}
+```
+
 **`.m.rule.roomnotif`**
 
+As of `v1.7`, this rule is deprecated and should only be enabled if the event
+does not have an `m.mentions` property.
+
 Matches any message from a sender with the proper power level whose content
 contains the text `@room`, signifying the whole room should be notified of
 the event.
@@ -676,6 +746,9 @@ Definition:
 
 **`.m.rule.contains_user_name`**
 
+As of `v1.7`, this rule is deprecated and should only be enabled if the event
+does not have an `m.mentions` property.
+
 Matches any message whose content contains the local part of the user's
 Matrix ID, separated by word boundaries.