Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-26 04:54:10 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Start fleshing our the mentions section.

Browse source
This commit is contained in:
Patrick Cloke 2023-05-02 14:37:03 -04:00
parent 3b036aefbb
commit 23f82cca0b
1 changed files with 37 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
content/client-server-api/modules/mentions.md
View file

@ -2,26 +2,50 @@
### User and room mentions
This module allows users to mention other users and rooms within a room message.
This is achieved by including a [Matrix URI](/appendices/#uris) in the HTML body of
an [m.room.message](#mroommessage) event. This module does not have any server-specific
behaviour to it.
This is achieved by including metadata in the `m.mentions` content property of
the event. The `m.mentions` propert consists of an object with two fields:
Mentions apply only to [m.room.message](#mroommessage) events where the `msgtype` is
* `user_ids`: A list of Matrix IDs of mentioned users.
* `room`: A boolean set to `true` to mention the room. (`room` should otherwise
not be included on the event.)
Although it is possible to silently mention users, it is recommended to include a
[Matrix URI](/appendices/#uris) in the HTML body of an [m.room.message](#mroommessage)
event. This applies only to [m.room.message](#mroommessage) events where the `msgtype` is
`m.text`, `m.emote`, or `m.notice`. The `format` for the event must be
`org.matrix.custom.html` and therefore requires a `formatted_body`.
To make a mention, reference the entity being mentioned in the
`formatted_body` using an anchor, like so:
`m.mentions` property, like so:
```json
{
"body": "Hello Alice!",
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!"
"formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!",
"m.mentions": {
"user_ids": ["@alice:example.org"]
}
}
```
Similarly, the entire room can be mentioned:
```json
{
"body": "Hello @room!",
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"formatted_body": "Hello @room!",
"m.mentions": {
"room": true
}
}
```
Additionally, see [the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules](#predefined-rules).
#### Client behaviour
In addition to using the appropriate `Matrix URI` for the mention,
@ -45,14 +69,19 @@ Clients should display mentions differently from other elements. For
example, this may be done by changing the background color of the
mention to indicate that it is different from a normal link.
If the current user is mentioned in a message (either by a mention as
defined in this module or by a push rule), the client should show that
If the current user is mentioned in a message, the client should show that
mention differently from other mentions, such as by using a red
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.
{{% boxes/note %}}
Similar to legacy [matrix.to URLs](/appendices/#matrixto-navigation),
groups used to be representable by mentions. They follow a similar format