wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Use body field as media caption (#1731)

Browse source 
* Use `body` field as media caption

As per MSC2530.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Use `s` HTML tag in example

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Move changed-in annotation

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
This commit is contained in:
Kévin Commaille 2024-02-26 23:15:44 +01:00 • committed by GitHub
parent 9a1f0ad532
commit 4cfe2fbf8d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 140 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -27,10 +27,18 @@ instead.
Some message types support HTML in the event content that clients should
prefer to display if available. Currently `m.text`, `m.emote`, `m.notice`,
and `m.key.verification.request` support an additional `format` parameter of
`org.matrix.custom.html`. When this field is present, a `formatted_body`
with the HTML must be provided. The plain text version of the HTML
should be provided in the `body`.
`m.image`, `m.file`, `m.audio`, `m.video` and `m.key.verification.request`
support an additional `format` parameter of `org.matrix.custom.html`. When this
field is present, a `formatted_body` with the HTML must be provided. The plain
text version of the HTML should be provided in the `body`.
{{% boxes/note %}}
{{% changed-in v="1.10" %}}
In previous versions of the specification, the `format` and `formatted` fields
were limited to `m.text`, `m.emote`, `m.notice`, and
`m.key.verification.request`. This list is expanded to include `m.image`,
`m.file`, `m.audio` and `m.video` for [media captions](#media-captions).
{{% /boxes/note %}}
Clients should limit the HTML they render to avoid Cross-Site Scripting,
HTML injection, and similar attacks. The strongly suggested set of HTML
@ -320,6 +328,49 @@ to the media repository, then reference the `mxc://` URI in a markdown-style lin
Clients SHOULD render spoilers differently with some sort of disclosure. For example, the
client could blur the actual text and ask the user to click on it for it to be revealed.
##### Media captions
{{% added-in v="1.10" %}}
Media messages, comprised of `m.image`, `m.file`, `m.audio` and `m.video`, can
include a caption to convey additional information about the media.
To send captions, clients MUST use the `filename` and the `body`, and optionally
the `formatted_body` with the `org.matrix.custom.html` format, described above.
If the `filename` is present, and its value is different than `body`, then
`body` is considered to be a caption, otherwise `body` is a filename. `format`
and `formatted_body` are only used for captions.
{{% boxes/note %}}
In previous versions of the specification, `body` was usually used to set the
filename of the uploaded file, and `filename` was only present on `m.file` with
the same purpose.
{{% /boxes/note %}}
An example of a media message with a caption is:
```json
{
"msgtype": "m.image",
"url": "mxc://example.org/abc123",
"filename": "dog.jpg",
"body": "this is a ~~cat~~ picture :3",
"format": "org.matrix.custom.html",
"formatted_body": "this is a <s>cat</s> picture :3",
"info": {
"w": 479,
"h": 640,
"mimetype": "image/jpeg",
"size": 27253
},
"m.mentions": {}
}
```
Clients MUST render the caption alongside the media and SHOULD prefer its
formatted representation.
#### Server behaviour
Homeservers SHOULD reject `m.room.message` events which don't have a