Add additional clarity to how rich replies are structured and used

6 years ago · 567843e043
parent 9004be7bda
commit 567843e043
1 changed files with 50 additions and 16 deletions
--- a/specification/modules/instant_messaging.rst
+++ b/specification/modules/instant_messaging.rst
@ -366,7 +366,20 @@ thread-like conversation.
 Relationships are defined under an ``m.relates_to`` key in the event's ``content``.
 If the event is of the type ``m.room.encrypted``, the ``m.relates_to`` key MUST NOT
 be covered by the encryption and instead be put alongside the encryption information
-held in the ``content``.
+held in the ``content``, like in the following example::
+
+  {
+    ...
+    "content": {
+      ...
+      "m.relates_to": {
+        "m.in_reply_to": {
+          ...
+        }
+      }
+    }
+  }
+

 Rich replies
 ++++++++++++
@ -376,14 +389,34 @@ clients may wish to better embed the referenced message for the user to have a
 better context for the conversation being had. This sort of embedding another
 message in a message is known as a "rich reply", or occasionally just a "reply".

-Rich replies may reference another event which also has a rich reply, infinitely.
 A rich reply is formed through use of an ``m.relates_to`` relation for ``m.in_reply_to``
 where a single key, ``event_id``, is used to reference the event being replied to.
-The referenced event ID MUST belong to the same room where the reply is being sent.
-Rich replies can only be constructed in the form of ``m.room.message`` events with
-a ``msgtype`` of ``m.text`` or ``m.notice``. Due to the fallback requirements, rich
+The referenced event ID SHOULD belong to the same room where the reply is being sent.
+Clients should be cautious of the event ID belonging to another room, or being invalid
+entirely. Rich replies can only be constructed in the form of ``m.room.message`` events
+with a ``msgtype`` of ``m.text`` or ``m.notice``. Due to the fallback requirements, rich
 replies cannot be constructed for types of ``m.emote``, ``m.file``, etc. Rich replies
-may reference any other ``m.room.message`` event, however.
+may reference any other ``m.room.message`` event, however. Rich replies may reference
+another event which also has a rich reply, infinitely.
+
+An ``m.in_reply_to`` relationship looks like the following::
+
+  {
+    ...
+    "type": "m.room.message",
+    "content": {
+      "msgtype": "m.text",
+      "body": "<body including fallback>",
+      "format": "org.matrix.custom.html",
+      "formatted_body": "<HTML including fallback>",
+      "m.relates_to": {
+        "m.in_reply_to": {
+          "event_id": "$another:event.com"
+        }
+      }
+    }
+  }
+

 Fallbacks and event representation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -393,7 +426,7 @@ to use instead. Clients that do not support rich replies should render the event
 as if rich replies were not special.

 Clients that do support rich replies MUST provide the fallback format on replies,
-and MUST strip the fallback before rendering the reply. Rich replies MUST supply
+and MUST strip the fallback before rendering the reply. Rich replies MUST have
 a ``format`` of ``org.matrix.custom.html`` and therefore a ``formatted_body``
 alongside the ``body`` and appropriate ``msgtype``. The specific fallback text
 is different for each ``msgtype``, however the general format for the ``body`` is:
@ -405,7 +438,7 @@ is different for each ``msgtype``, however the general format for the ``body`` i
  This is where the reply goes


-The ``formatted_body`` ends up using the following template:
+The ``formatted_body`` should use the following template:

 .. code-block:: html

@ -491,9 +524,10 @@ Fallback for ``m.image``, ``m.video``, ``m.audio``, and ``m.file``

 The related event's ``body`` would be a file name, which may not be very descriptive.
 The related event should additionally not have a ``format`` or ``formatted_body``
-in the ``content`` - if the event does, it should be ignored. Because the filename
-alone may not be descriptive, the related event's ``body`` should be considered 
-to be ``"sent a file."`` such that the output looks similar to the following::
+in the ``content`` - if the event does have a ``format`` and/or ``formatted_body``,
+those fields should be ignored. Because the filename alone may not be descriptive,
+the related event's ``body`` should be considered to be ``"sent a file."`` such that
+the output looks similar to the following::

  > <@alice:example.org> sent a file.