Patrick Cloke
1 year ago
committed by
GitHub
parent
9766b142f1
commit
466acdfc46
@ -0,0 +1,2 @@
|
||||
Document the `m.mentions` property; the `.m.rule.is_user_mention` and `.m.rule.is_room_mention` push rules; and other behaviour from [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952).
|
||||
|
||||
@ -1,61 +1,76 @@
|
||||
|
||||
### 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.
|
||||
{{% changed-in v="1.7" %}}
|
||||
|
||||
Mentions apply 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`.
|
||||
This module allows users to "mention" other users and rooms within a room event.
|
||||
This is primarily used as an indicator that the recipient should receive a notification
|
||||
about the event.
|
||||
This is achieved by including metadata in the `m.mentions` content property of
|
||||
the event to reference the entity being mentioned.
|
||||
|
||||
`m.mentions` is defined as follows:
|
||||
|
||||
{{% definition path="api/client-server/definitions/m.mentions" %}}
|
||||
|
||||
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.
|
||||
Users should not add their own Matrix ID to the `m.mentions` property as outgoing
|
||||
messages cannot self-notify.
|
||||
|
||||
To make a mention, reference the entity being mentioned in the
|
||||
`formatted_body` using an anchor, like so:
|
||||
{{% boxes/warning %}}
|
||||
If an encrypted event contains an `m.mentions` in its payload, it should be
|
||||
encrypted as normal. To properly process mentions in encrypted rooms, events
|
||||
must be decrypted first. See [receiving notifications](#receiving-notifications).
|
||||
{{% /boxes/warning %}}
|
||||
|
||||
```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>!"
|
||||
}
|
||||
```
|
||||
Note that, for backwards compatibility, push rules such as [`.m.rule.contains_display_name`](#_m_rule_contains_display_name),
|
||||
[`.m.rule.contains_user_name`](#_m_rule_contains_user_name), and
|
||||
[`.m.rule.roomnotif`](#_m_rule_roomnotif) continue to match if the `body` of
|
||||
the event contains the user's display name or ID. To avoid unintentional notifications,
|
||||
**it is recommended that clients include a `m.mentions` property on each event**.
|
||||
(If there are no mentions to include it can be an empty object.)
|
||||
|
||||
{{% boxes/rationale %}}
|
||||
In previous versions of the specification, mentioning users was done by
|
||||
including the user's display name or the localpart of their Matrix ID and room
|
||||
mentions were done by including the string "@room" in the plaintext `body` of
|
||||
the event. This was prone to confusing and buggy behaviour.
|
||||
{{% /boxes/rationale %}}
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
In addition to using the appropriate `Matrix URI` for the mention,
|
||||
clients should use the following guidelines when making mentions in
|
||||
events to be sent:
|
||||
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`.
|
||||
|
||||
- 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, 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
|
||||
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
|
||||
anchor's text.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
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
|
||||
user or room information.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Similar to legacy [matrix.to URLs](/appendices/#matrixto-navigation),
|
||||
groups used to be representable by mentions. They follow a similar format
|
||||
to room mentions, though using the group ID in both the link and anchor
|
||||
text.
|
||||
{{% /boxes/note %}}
|
||||
@ -0,0 +1,37 @@
|
||||
# Copyright 2023 The Matrix.org Foundation C.I.C.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
|
||||
type: object
|
||||
title: m.mentions
|
||||
description: |-
|
||||
Describes whether the event mentions other users or the room. This is contained
|
||||
within the event's `content` alongside other fields for the relevant event type.
|
||||
example: {
|
||||
"body": "Hello Alice!",
|
||||
"msgtype": "m.text",
|
||||
"format": "org.matrix.custom.html",
|
||||
"formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!",
|
||||
"m.mentions": {
|
||||
"user_ids": ["@alice:example.org"]
|
||||
}
|
||||
}
|
||||
properties:
|
||||
user_ids:
|
||||
type: string[]
|
||||
description: A list of Matrix IDs of mentioned users.
|
||||
room:
|
||||
type: boolean
|
||||
description: |-
|
||||
A boolean set to `true` to mention the room, for an `@room` notification.
|
||||
(`room` should otherwise not be included on the event.)
|
||||
Loading…
Reference in New Issue