Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-04-29 22:04:08 +02:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Clean-up client behavior section.

Browse source
This commit is contained in:
Patrick Cloke 2023-05-16 12:45:13 -04:00
parent ff51aa4b1d
commit 451886dd30
1 changed files with 14 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -13,26 +13,6 @@ the event to reference the entity being mentioned.
{{% definition path="api/client-server/definitions/m.mentions" %}} {{% definition path="api/client-server/definitions/m.mentions" %}}
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`.
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`](#_m_rule_is_user_mention) and Additionally, see the [`.m.rule.is_user_mention`](#_m_rule_is_user_mention) and
[`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules. [`.m.rule.is_room_mention`](#_m_rule_is_room_mention) push rules.
Users should not add their own Matrix ID to the `m.mentions` property as outgoing Users should not add their own Matrix ID to the `m.mentions` property as outgoing
@ -54,21 +34,26 @@ the event. This was prone to confusing and buggy behaviour.
#### Client behaviour #### Client behaviour
In addition to using the appropriate `Matrix URI` for the mention, Although it is possible to silently mention users, it is recommended to include a
clients should use the following guidelines when making mentions in [Matrix URI](/appendices/#uris) in the HTML body of an [m.room.message](#mroommessage)
events to be sent: 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`.
- When mentioning users, use the user's potentially ambiguous display Clients should use the following guidelines when adding a `Matrix URI`
representing a mention to events to be sent:
- When linking to users, use the user's potentially ambiguous display
name for the anchor's text. If the user does not have a display name for the anchor's text. If the user does not have a display
name, use the user's ID. name, use the user's ID.
- When mentioning rooms, use the canonical alias for the room. If the - When linking to rooms, use the canonical alias for the room. If the
room does not have a canonical alias, prefer one of the aliases room does not have a canonical alias, prefer one of the aliases
listed on the room. If no alias can be found, fall back to the room listed on the room. If no alias can be found, fall back to the room
ID. In all cases, use the alias/room ID being linked to as the ID. In all cases, use the alias/room ID being linked to as the
anchor's text. anchor's text.
The text component of the anchor should be used in the event's `body` The text component of the anchor should be used in the event's `body`
where the mention would normally be represented, as shown in the example where the link would normally be represented, as shown in the example
above. above.
Clients should display mentions differently from other elements. For Clients should display mentions differently from other elements. For
@ -77,7 +62,9 @@ mention to indicate that it is different from a normal link.
If the current user is mentioned in a message, 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 mention differently from other mentions, such as by using a red
background color to signify to the user that they were mentioned. background color to signify to the user that they were mentioned. Note that
it is possible for a user to be mentioned without including their `Matrix URI`
in the event.
When clicked, the mention should navigate the user to the appropriate When clicked, the mention should navigate the user to the appropriate
user or room information. user or room information.