archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add additional clarity to how rich replies are structured and used

Browse Source
pull/977/head
Travis Ralston 6 years ago
parent 9004be7bda
commit 567843e043
1 changed files with 50 additions and 16 deletions
Show Stats Download Patch File Download Diff File

58
specification/modules/instant_messaging.rst
Unescape Escape View File

@ -366,7 +366,20 @@ thread-like conversation.
Relationships are defined under an ``m.relates_to`` key in the event's ``content``. 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 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 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 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 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". 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`` 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. 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. The referenced event ID SHOULD 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 Clients should be cautious of the event ID belonging to another room, or being invalid
a ``msgtype`` of ``m.text`` or ``m.notice``. Due to the fallback requirements, rich 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 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 Fallbacks and event representation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -393,9 +426,9 @@ to use instead. Clients that do not support rich replies should render the event
as if rich replies were not special. as if rich replies were not special.
Clients that do support rich replies MUST provide the fallback format on replies, 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`` a ``format`` of ``org.matrix.custom.html`` and therefore a ``formatted_body``
alongside the ``body`` and appropriate ``msgtype``. The specific fall back text alongside the ``body`` and appropriate ``msgtype``. The specific fallback text
is different for each ``msgtype``, however the general format for the ``body`` is: is different for each ``msgtype``, however the general format for the ``body`` is:
.. code-block:: text .. code-block:: text
@ -405,7 +438,7 @@ is different for each ``msgtype``, however the general format for the ``body`` i
This is where the reply goes 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 .. 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'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`` 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 in the ``content`` - if the event does have a ``format`` and/or ``formatted_body``,
alone may not be descriptive, the related event's ``body`` should be considered those fields should be ignored. Because the filename alone may not be descriptive,
to be ``"sent a file."`` such that the output looks similar to the following:: 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. > <@alice:example.org> sent a file.

Write Preview
Loading…
Cancel
Save