matrix-org / matrix-org/matrix-spec
Document room-specific push rules
- 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
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