Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-23 19:44:09 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Commit to show changes to rich replies section

Browse source
This commit is contained in:
Travis Ralston 2022-05-05 17:12:58 -06:00
parent 2997c9089d
commit 1d70a8dbd3
1 changed files with 94 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

131
content/client-server-api/modules/instant_messaging.md
View file

@ -289,77 +289,89 @@ more or less to fit better with their user experience.
##### Rich replies ##### Rich replies
In some cases, events may wish to reference other events. This could be {{% changed-in v="1.3" %}}
to form a thread of messages for the user to follow along with, or to
provide more context as to what a particular event is describing.
Currently, the only kind of relation defined is a "rich reply" where a
user may reference another message to create a thread-like conversation.
Relationships are defined under an `m.relates_to` key in the event's More common on [`m.room.message`](#mroommessage) events, rich replies are a
`content`. If the event is of the type `m.room.encrypted`, the special kind of [relationship](#forming-relationships-between-events) which
`m.relates_to` key MUST NOT be covered by the encryption and instead be effectively quotes the referenced event for the client to render/process how
put alongside the encryption information held in the `content`. it wishes.
A rich reply is formed through use of an `m.relates_to` relation for {{% boxes/note %}}
`m.in_reply_to` where a single key, `event_id`, is used to reference the Until v1.3 of the spec, rich replies were limited to `m.room.message` events
event being replied to. The referenced event ID SHOULD belong to the which could represent an HTML-formatted body. As of v1.3 this is now expanded
same room where the reply is being sent. Clients should be cautious of to *all* event types by dropping the requirement that an HTML-formatted body
the event ID belonging to another room, or being invalid entirely. Rich be included.
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. Rich replies may reference another event which also has
a rich reply, infinitely.
An `m.in_reply_to` relationship looks like the following: Additionally, a rich reply can reference any other event type as of v1.3.
Previously, a rich reply could only reference another `m.room.message` event.
{{% /boxes/note %}}
``` When possible, events SHOULD include a [fallback representation](#fallbacks-for-rich-replies)
to allow clients which do not render rich replies to still see something which
appears to be a quoted reply.
Though rich replies are forming a relationship to another event, they do not
use `rel_type` to create this relationship. Instead, a subkey named `m.in_reply_to`
is used to describe the reply's relationship, leaving the other keys of
`m.relates_to` to describe the primary relationship of the event. This means
that if an event is simply in reply to another event, without further relationship,
the `rel_type` and `event_id` keys of `m.relates_to` become *optional*.
An example reply would be:
```json5
{ {
...
"type": "m.room.message",
"content": { "content": {
"msgtype": "m.text",
"body": "<body including fallback>",
"format": "org.matrix.custom.html",
"formatted_body": "<HTML including fallback>",
"m.relates_to": { "m.relates_to": {
"m.in_reply_to": { "m.in_reply_to": {
"event_id": "$another:event.com" "event_id": "$another_event"
}
}
} }
},
"body": "That sounds like a great idea!"
},
// other fields as required by events
} }
``` ```
Note that the `event_id` of the `m.in_reply_to` object has the same requirements
as if it were to be under `m.relates_to` directly instead.
{{% boxes/note %}}
Some event relationships, like [threads](#threading), describe what it looks like
to both form a relationship *and* still reply to another event.
{{% /boxes/note %}}
##### Fallbacks for rich replies ##### Fallbacks for rich replies
Some clients may not have support for rich replies and therefore need a Some clients may not have support for rich replies and therefore need a
fallback to use instead. Clients that do not support rich replies should fallback to use instead. Clients that do not support rich replies should
render the event as if rich replies were not special. render the event as if rich replies were not special.
Clients that do support rich replies MUST provide the fallback format on Clients that do support rich replies SHOULD provide the fallback format on
replies, and MUST strip the fallback before rendering the reply. Rich replies, and MUST strip the fallback before rendering the reply. The
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 specific fallback text is different for each `msgtype`, however the
general format for the `body` is: general format for the `body` is:
> <@alice:example.org> This is the original body ```
> <@alice:example.org> This is the original body
This is where the reply goes This is where the reply goes
```
The `formatted_body` should use the following template: The `formatted_body`, if present and using an associated `format` of
`org.matrix.custom.html`, should use the following template:
<mx-reply> ```
<mx-reply>
<blockquote> <blockquote>
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a> <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
<a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a> <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
<br /> <br />
<!-- This is where the related event's HTML would be. --> <!-- This is where the related event's HTML would be. -->
</blockquote> </blockquote>
</mx-reply> </mx-reply>
This is where the reply goes. This is where the reply goes.
```
If the related event does not have a `formatted_body`, the event's If the related event does not have a `formatted_body`, the event's
`body` should be considered after encoding any HTML special characters. `body` should be considered after encoding any HTML special characters.
@ -392,10 +404,12 @@ Using the prefix sequence, the first line of the related event's `body`
should be prefixed with the user's ID, followed by each line being should be prefixed with the user's ID, followed by each line being
prefixed with the fallback prefix sequence. For example: prefixed with the fallback prefix sequence. For example:
> <@alice:example.org> This is the first line ```
> This is the second line > <@alice:example.org> This is the first line
> This is the second line
This is the reply This is the reply
```
The `formatted_body` uses the template defined earlier in this section. The `formatted_body` uses the template defined earlier in this section.
@ -405,22 +419,26 @@ Similar to the fallback for `m.text`, each line gets prefixed with the
fallback prefix sequence. However an asterisk should be inserted before fallback prefix sequence. However an asterisk should be inserted before
the user's ID, like so: the user's ID, like so:
> * <@alice:example.org> feels like today is going to be a great day ```
> * <@alice:example.org> feels like today is going to be a great day
This is the reply This is the reply
```
The `formatted_body` has a subtle difference for the template where the The `formatted_body` has a subtle difference for the template where the
asterisk is also inserted ahead of the user's ID: asterisk is also inserted ahead of the user's ID:
<mx-reply> ```
<mx-reply>
<blockquote> <blockquote>
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a> <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
* <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a> * <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
<br /> <br />
<!-- This is where the related event's HTML would be. --> <!-- This is where the related event's HTML would be. -->
</blockquote> </blockquote>
</mx-reply> </mx-reply>
This is where the reply goes. This is where the reply goes.
```
###### Fallback for `m.image`, `m.video`, `m.audio`, and `m.file` ###### Fallback for `m.image`, `m.video`, `m.audio`, and `m.file`
@ -432,19 +450,22 @@ 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 be considered to be `"sent a file."` such that the output looks similar
to the following: to the following:
> <@alice:example.org> sent a file. ```
> <@alice:example.org> sent a file.
This is the reply This is the reply
```
<mx-reply> ```
<mx-reply>
<blockquote> <blockquote>
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a> <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
<a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a> <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
<br /> <br />
sent a file. sent a file.
</blockquote> </blockquote>
</mx-reply> </mx-reply>
This is where the reply goes. This is where the reply goes.
```
For `m.image`, the text should be `"sent an image."`. For `m.video`, the 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 text should be `"sent a video."`. For `m.audio`, the text should be