matrix-org / matrix-org/matrix-spec

Document room-specific push rules

Open
#1,603 0 comments 0 reactions 0 assignees View on GitHub
improvement
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

Element includes room-specific push rules (labeled "All messages", "Mentions & keywords", and "Mute" in the UI). The way these are implemented isn't documented, but it seems likely that other clients would want to be compatible in order to give a good user experience. As part of my recent work in notifications I dug quite a bit into how push rules work and documented these.

Note that for all of these the `rule_id` is set to the room ID.

## All messages

[Implemented](https://github.com/matrix-org/matrix-react-sdk/blob/22f83e7917ba4c3ea420f26a854fc3b687c61d1e/src/RoomNotifs.ts#L157-L165) as a room-specific rule with a notify action:

```json
{
"rule_id" : "!abcdef:example.com",
"default" : false,
"enabled" : true,
"actions" : ["notify"]
}
```

## Mentions & keywords

[Implemented](https://github.com/matrix-org/matrix-react-sdk/blob/22f83e7917ba4c3ea420f26a854fc3b687c61d1e/src/RoomNotifs.ts#L151-L153) as a room-specific rule with no actions[^1]:

```json
{
"rule_id" : "!abcdef:example.com",
"default" : false,
"enabled" : true,
"actions" : []
}
```

## Mute

[Implemented](https://github.com/matrix-org/matrix-react-sdk/blob/22f83e7917ba4c3ea420f26a854fc3b687c61d1e/src/RoomNotifs.ts#L121-L130) as an override rule to match the room ID with no actions[^2]:

```json
{
"rule_id" : "!abcdef:example.com",
"conditions" : [
{
"key" : "room_id",
"kind" : "event_match",
"pattern" : "!abcdef:example.com"
}
],
"default" : false,
"enabled" : true,
"actions" : []
}
```

[^1]: Older versions of this would have included the `"dont_notify"` action instead, see MSC3987.

[^2]: The [`.m.rule.master`](https://spec.matrix.org/v1.6/client-server-api/#default-override-rules) is *always* first, so this rule gets created right after it.

Contributor guide

Open the contributing guide

Research direction

Start with the linked src/RoomNotifs.ts references to verify how Element creates the three room-specific rules. Then find the corresponding push-rule documentation in the Matrix specification and add the examples, rule IDs, actions, and footnotes described in the issue. Done means other clients can use the documented behavior for All messages, Mentions & keywords, and Mute.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
Half a day
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.