From b16b850731db504fd825423ab485c36fa3814454 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Wed, 3 May 2023 15:23:19 -0400
Subject: [PATCH] Add information on mentions & replies.

---
 content/client-server-api/modules/mentions.md |  4 +--
 .../client-server-api/modules/rich_replies.md | 32 ++++++++++++++++++-
 2 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/content/client-server-api/modules/mentions.md b/content/client-server-api/modules/mentions.md
index 6ed32894..0bdec931 100644
--- a/content/client-server-api/modules/mentions.md
+++ b/content/client-server-api/modules/mentions.md
@@ -76,12 +76,12 @@ background color to signify to the user that they were mentioned.
 When clicked, the mention should navigate the user to the appropriate
 user or room information.
 
-TODO Behavior with replies.
-
 TODO Behavior with edits.
 
 TODO Always include `m.mentions` property.
 
+TODO Note that users should *never* include their own Matrix ID in `m.mentions`.
+
 {{% boxes/note %}}
 Similar to legacy [matrix.to URLs](/appendices/#matrixto-navigation),
 groups used to be representable by mentions. They follow a similar format
diff --git a/content/client-server-api/modules/rich_replies.md b/content/client-server-api/modules/rich_replies.md
index 5132c36e..a0018630 100644
--- a/content/client-server-api/modules/rich_replies.md
+++ b/content/client-server-api/modules/rich_replies.md
@@ -176,4 +176,34 @@ 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"`.
\ No newline at end of file
+`"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
+}
+```