Skip to content

Remove legacy mentions #2186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tulir merged 4 commits into from
Sep 21, 2025
Merged

Remove legacy mentions #2186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
271ae6a
Remove legacy mentions
zecakeh Aug 2, 2025
e3db17e
Add changelog
zecakeh Aug 2, 2025
7b5935e
Fix wording
zecakeh Aug 3, 2025
56e89d8
Update spec version
zecakeh Sep 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/2186.removal
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Remove legacy mentions, as per [MSC4210](https://github.com/matrix-org/matrix-spec-proposals/issues/4210).
22 changes: 12 additions & 10 deletions content/client-server-api/modules/mentions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@

{{% changed-in v="1.7" %}}

{{% changed-in v="1.17" %}}: the legacy push rules that looked for mentions in
the `body` of the event were removed.

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.
Expand Down Expand Up @@ -38,19 +41,18 @@ encrypted as normal. To properly process mentions in encrypted rooms, events
must be decrypted first. See [receiving notifications](#receiving-notifications).
{{% /boxes/warning %}}

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 %}}
{{% boxes/note %}}
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 %}}
the event. When the `m.mentions` field was introduced, those push rules were
disabled if the `m.mentions` field was present.

To avoid unintentional notifications with clients and servers that still use
those push rules, **it is recommended that clients still include a `m.mentions`
property on each event**. (If there are no mentions to include it can be an
empty object.)
{{% /boxes/note %}}

#### Client behaviour

Expand Down
112 changes: 6 additions & 106 deletions content/client-server-api/modules/push.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -382,6 +382,9 @@ The following `alt_aliases` values will NOT match:

**`contains_display_name`**

{{% changed-in v="1.17" %}}: this condition is deprecated and **should not be
used in new push rules**.

This matches messages where `content.body` contains the owner's display name in
that room. This is a separate condition because display names may change and as such
it would be hard to maintain a rule that matched the user's display name. This
Expand Down Expand Up @@ -413,6 +416,9 @@ Parameters:

#### Predefined Rules

{{% changed-in v="1.17" %}}: the legacy default push rules that looked for
mentions in the `body` of the event were removed.

Homeservers can specify "server-default rules". They operate at a lower
priority than "user-defined rules", except for the `.m.rule.master` rule
which has always a higher priority than any other rule. The `rule_id`
Expand Down Expand Up @@ -557,41 +563,6 @@ Definition:
}
```

<a id="_m_rule_contains_display_name"></a> **`.m.rule.contains_display_name`**

{{% changed-in v="1.7" %}}

As of `v1.7`, this rule is deprecated and **should only be enabled if the event
does not have an [`m.mentions` property](#definition-mmentions)**.

Matches any message whose content contains the user's current display name
in the room in which it was sent.

Definition:

```json
{
"rule_id": ".m.rule.contains_display_name",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "contains_display_name"
}
],
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
]
}
```

<a id="_m_rule_is_room_mention"></a> **`.m.rule.is_room_mention`**

{{% added-in v="1.7" %}}
Expand Down Expand Up @@ -626,44 +597,6 @@ Definition:
}
```

<a id="_m_rule_roomnotif"></a> **`.m.rule.roomnotif`**

{{% changed-in v="1.7" %}}

As of `v1.7`, this rule is deprecated and **should only be enabled if the event
does not have an [`m.mentions` property](#definition-mmentions)**.

Matches any message from a sender with the proper power level whose content
contains the text `@room`, signifying the whole room should be notified of
the event.

Definition:

```json
{
"rule_id": ".m.rule.roomnotif",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "event_match",
"key": "content.body",
"pattern": "@room"
},
{
"kind": "sender_notification_permission",
"key": "room"
}
],
"actions": [
"notify",
{
"set_tweak": "highlight"
}
]
}
```

**<a id="mruletombstone"></a>`.m.rule.tombstone`**

Matches any state event whose type is `m.room.tombstone`. This is
Expand Down Expand Up @@ -776,39 +709,6 @@ Definition:
}
```

##### Default Content Rules

<a id="_m_rule_contains_user_name"></a> **`.m.rule.contains_user_name`**

{{% changed-in v="1.7" %}}

As of `v1.7`, this rule is deprecated and **should only be enabled if the event
does not have an [`m.mentions` property](#definition-mmentions)**.

Matches any message whose content contains the local part of the user's
Matrix ID, separated by word boundaries.

Definition (as a `content` rule):

```json
{
"rule_id": ".m.rule.contains_user_name",
"default": true,
"enabled": true,
"pattern": "[the local part of the user's Matrix ID]",
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
]
}
```

##### Default Underride Rules

**`.m.rule.call`**
Expand Down
24 changes: 4 additions & 20 deletions data/api/client-server/definitions/push_ruleset.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,24 +34,6 @@ properties:
type: array
type: object
example: {
"content": [
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
],
"default": true,
"enabled": true,
"pattern": "alice",
"rule_id": ".m.rule.contains_user_name"
}
],
"override": [
{
"actions": [],
Expand Down Expand Up @@ -113,12 +95,14 @@ example: {
],
"conditions": [
{
"kind": "contains_display_name"
"kind": "event_property_contains",
"key": "content.m\\.mentions.user_ids",
"value": "@alice:example.com"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.contains_display_name"
"rule_id": ".m.rule.is_user_mention"
},
{
"actions": [
Expand Down
24 changes: 4 additions & 20 deletions data/event-schemas/examples/m.push_rules.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,24 +3,6 @@
"type": "m.push_rules",
"content": {
"global": {
"content": [
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
],
"default": true,
"enabled": true,
"pattern": "alice",
"rule_id": ".m.rule.contains_user_name"
}
],
"override": [
{
"actions": [],
Expand Down Expand Up @@ -82,12 +64,14 @@
],
"conditions": [
{
"kind": "contains_display_name"
"kind": "event_property_contains",
"key": "content.m\\.mentions.user_ids",
"value": "@alice:example.com"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.contains_display_name"
"rule_id": ".m.rule.is_user_mention"
},
{
"actions": [
Expand Down