Update spec for MSC3952: intentional mentions (#1508)

See MSC3952.

changelogs/client_server/newsfragments/1508.feature

@@ -0,0 +1,2 @@
+Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other behaviour from [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952).
+

content/client-server-api/modules/event_replacements.md

@@ -293,6 +293,73 @@ events will not be included in the aggregation bundled with the original
 event. Note that the subsequent edits are not actually redacted themselves:
 they simply serve no purpose within the visible timeline.
 
+#### Edits of events with mentions
+
+When editing an event with [user and room mentions](#user-and-room-mentions) the
+replacement event will have two `m.mentions` properties:
+
+* One at the top-level of the `content`, which should contain mentions due to
+  this edit revision.
+* One inside the `m.new_content` property, which should contain the resolved mentions
+  for the final version of the event.
+
+The difference between these properties ensures that users will not be notified
+for each edit revision of an event, but allows for new users to be mentioned (or
+for re-notifying if the sending client feels a large enough revision was made).
+
+For example, if there is an event mentioning Alice:
+
+```json5
+{
+    "event_id": "$original_event",
+    "type": "m.room.message",
+    "content": {
+        "body": "Hello Alice!",
+        "m.mentions": {
+            "user_ids": ["@alice:example.org"]
+        }
+    }
+}
+```
+
+And an edit to also mention Bob:
+
+```json5
+{
+  "content": {
+    "body": "* Hello Alice & Bob!",
+    "m.mentions": {
+      "user_ids": [
+        // Include only the newly mentioned user.
+        "@bob:example.org"
+      ]
+    },
+    "m.new_content": {
+      "body": "Hello Alice & Bob!",
+      "m.mentions": {
+        "user_ids": [
+          // Include all of the mentioned users.
+          "@alice:example.org",
+          "@bob:example.org"
+        ]
+      },
+    },
+    "m.relates_to": {
+      "rel_type": "m.replace",
+      "event_id": "$original_event"
+    }
+  },
+  // other fields as required by events
+}
+```
+
+If an edit revision removes a user's mention then that user's Matrix ID should be
+included in neither `m.mentions` property.
+
+Clients may also wish to modify the [client behaviour](#user-and-room-mentions) of
+determining if an event mentions the current user by checking the `m.mentions`
+property under `m.new_content`.
+
 #### Edits of replies
 
 Some particular constraints apply to events which replace a

content/client-server-api/modules/mentions.md

@@ -1,61 +1,76 @@
 
 ### User and room mentions
 
-This module allows users to mention other users and rooms within a room message.
+{{% changed-in v="1.7" %}}
-This is achieved by including a [Matrix URI](/appendices/#uris) in the HTML body of
-an [m.room.message](#mroommessage) event. This module does not have any server-specific
-behaviour to it.
 
-Mentions apply only to [m.room.message](#mroommessage) events where the `msgtype` is
+This module allows users to "mention" other users and rooms within a room event.
-`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
+This is primarily used as an indicator that the recipient should receive a notification
-`org.matrix.custom.html` and therefore requires a `formatted_body`.
+about the event.
+This is achieved by including metadata in the `m.mentions` content property of
+the event to reference the entity being mentioned.
+
+`m.mentions` is defined as follows:
+
+{{% definition path="api/client-server/definitions/m.mentions" %}}
+
+Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and
+[`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules.
+Users should not add their own Matrix ID to the `m.mentions` property as outgoing
+messages cannot self-notify.
 
-To make a mention, reference the entity being mentioned in the
+{{% boxes/warning %}}
-`formatted_body` using an anchor, like so:
+If an encrypted event contains an `m.mentions` in its payload, it should be
+encrypted as normal. To properly process mentions in encrypted rooms, events
+must be decrypted first. See [receiving notifications](#receiving-notifications).
+{{% /boxes/warning %}}
 
-```json
+Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
-{
+[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
-    "body": "Hello Alice!",
+[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to  match if the `body` of
-    "msgtype": "m.text",
+the event contains the user's display name or ID. To avoid unintentional notifications,
-    "format": "org.matrix.custom.html",
+**it is recommended that clients include a `m.mentions` property on each event**.
-    "formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!"
+(If there are no mentions to include it can be an empty object.)
-}
+
-```
+{{% boxes/rationale %}}
+In previous versions of the specification, mentioning users was done by
+including the user's display name or the localpart of their Matrix ID and room
+mentions were done by including the string "@room" in the plaintext `body` of
+the event. This was prone to confusing and buggy behaviour.
+{{% /boxes/rationale %}}
 
 #### Client behaviour
 
-In addition to using the appropriate `Matrix URI` for the mention,
+Although it is possible to silently mention users, it is recommended to include a
-clients should use the following guidelines when making mentions in
+[Matrix URI](/appendices/#uris) in the HTML body of  an [m.room.message](#mroommessage)
-events to be sent:
+event. This applies only to [m.room.message](#mroommessage) events where the `msgtype` is
+`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
+`org.matrix.custom.html` and therefore requires a `formatted_body`.
 
--   When mentioning users, use the user's potentially ambiguous display
+Clients should use the following guidelines when adding a `Matrix URI`
+representing a mention to events to be sent:
+
+-   When linking to users, use the user's potentially ambiguous display
     name for the anchor's text. If the user does not have a display
     name, use the user's ID.
--   When mentioning rooms, use the canonical alias for the room. If the
+-   When linking to rooms, use the canonical alias for the room. If the
     room does not have a canonical alias, prefer one of the aliases
     listed on the room. If no alias can be found, fall back to the room
     ID. In all cases, use the alias/room ID being linked to as the
     anchor's text.
 
 The text component of the anchor should be used in the event's `body`
-where the mention would normally be represented, as shown in the example
+where the link would normally be represented, as shown in the example
 above.
 
 Clients should display mentions differently from other elements. For
 example, this may be done by changing the background color of the
 mention to indicate that it is different from a normal link.
 
-If the current user is mentioned in a message (either by a mention as
+If the current user is mentioned in a message, the client should show that
-defined in this module or by a push rule), the client should show that
 mention differently from other mentions, such as by using a red
-background color to signify to the user that they were mentioned.
+background color to signify to the user that they were mentioned. Note that
+it is possible for a user to be mentioned without including their `Matrix URI`
+in the event.
 
 When clicked, the mention should navigate the user to the appropriate
 user or room information.
-
-{{% boxes/note %}}
-Similar to legacy [matrix.to URLs](/appendices/#matrixto-navigation),
-groups used to be representable by mentions. They follow a similar format
-to room mentions, though using the group ID in both the link and anchor
-text.
-{{% /boxes/note %}}

content/client-server-api/modules/push.md

@@ -521,7 +521,46 @@ Definition:
 }
 ```
 
-**`.m.rule.contains_display_name`**
+<a id="_m_rule_is_user_mention"/> **`.m.rule.is_user_mention`**
+
+{{< added-in v="1.7" >}}
+
+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"
+        }
+    ]
+}
+```
+
+<a id="_m_rule_contains_display_name"/> **`.m.rule.contains_display_name`**
+
+{{% changed-in v="1.7" %}}
+
+As of `v1.7`, this rule is deprecated and **should only be enabled if the event
+does not have an [`m.mentions` property](#definition-mmentions)**.
 
 Matches any message whose content contains the user's current display name
 in the room in which it was sent.
@@ -551,7 +590,46 @@ Definition:
 }
 ```
 
-**`.m.rule.roomnotif`**
+<a id="_m_rule_is_room_mention"/> **`.m.rule.is_room_mention`**
+
+{{< added-in v="1.7" >}}
+
+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"
+        }
+    ]
+}
+```
+
+<a id="_m_rule_roomnotif"/> **`.m.rule.roomnotif`**
+
+{{% changed-in v="1.7" %}}
+
+As of `v1.7`, this rule is deprecated and **should only be enabled if the event
+does not have an [`m.mentions` property](#definition-mmentions)**.
 
 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
@@ -674,7 +752,12 @@ Definition:
 
 ##### Default Content Rules
 
-**`.m.rule.contains_user_name`**
+<a id="_m_rule_contains_user_name"/> **`.m.rule.contains_user_name`**
+
+{{% changed-in v="1.7" %}}
+
+As of `v1.7`, this rule is deprecated and **should only be enabled if the event
+does not have an [`m.mentions` property](#definition-mmentions)**.
 
 Matches any message whose content contains the local part of the user's
 Matrix ID, separated by word boundaries.

content/client-server-api/modules/rich_replies.md

@@ -177,3 +177,33 @@ This is where the reply goes.
 For `m.image`, the text should be `"sent an image."`. For `m.video`, the
 text should be `"sent a video."`. For `m.audio`, the text should be
 `"sent an audio file"`.
+
+#### Mentioning the replied to user
+
+In order to notify users of the reply, it may be desirable to include the `sender`
+of the replied to event and any users mentioned in that event. See
+[user and room mentions](#user-and-room-mentions) for additional information.
+
+An example including mentioning the original sender and other users:
+
+```json5
+{
+  "content": {
+    "m.relates_to": {
+      "m.in_reply_to": {
+        "event_id": "$another_event"
+      }
+    },
+    "body": "That sounds like a great idea!",
+    "m.mentions": {
+      "user_ids": [
+        // The sender of $another_event.
+        "@alice:example.org",
+        // Another Matrix ID copied from the m.mentions property of $another_event.
+        "@bob:example.org"
+      ]
+    }
+  },
+  // other fields as required by events
+}
+```

data/api/client-server/definitions/m.mentions.yaml

@@ -0,0 +1,37 @@
+# Copyright 2023 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+title: m.mentions
+description: |-
+  Describes whether the event mentions other users or the room. This is contained
+  within the event's `content` alongside other fields for the relevant event type.
+example: {
+    "body": "Hello Alice!",
+    "msgtype": "m.text",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!",
+    "m.mentions": {
+        "user_ids": ["@alice:example.org"]
+    }
+}
+properties:
+  user_ids:
+    type: string[]
+    description: A list of Matrix IDs of mentioned users.
+  room:
+    type: boolean
+    description: |-
+      A boolean set to `true` to mention the room, for an `@room` notification.
+      (`room` should otherwise not be included on the event.)