matrix-spec/content/client-server-api/modules/mentions.md

User and room mentions

{{< changed-in v="1.7" >}}

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. The m.mentions property consists of an object with two fields:

• user_ids: A list of Matrix IDs of mentioned users.
• room: A boolean set to true to mention the room, for an @room notification. (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 in the HTML body of an m.room.message event. This applies only to m.room.message 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 m.mentions property, like so:

{
    "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"]
    }
}

Similarly, the entire room can be mentioned:

{
    "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. Users should not add their own Matrix ID to the m.mentions property as outgoing messages cannot self-notify.

To disable legacy behaviour of notifications occurring due to matching against the localpart of Matrix IDs and display names 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.

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:

• When mentioning 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 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 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, 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.