# MSC3664: Notifications for relations Relations are very powerful and are becoming a platform to build new features like replies, edits, reactions, threads, polls and much more on. On the other hand there is currently no way to control what you are getting notified for. Some people want to get notified when someone replies to their message. Some want to get notified for reactions to their message. Some people explicitly do not want that. You might want to be able to mute a thread and you may want to get notified for poll responeses or not. Some people like getting notified for edits, others prefer to not get notified, when someone fixes typos 20 times in a row for a long message they sent a week ago. We should extend push rules so that a server can provide sane defaults and users can adjust them to their own wishes. ## Proposal ### New push rule condition: `related_event_match` Notifications for relation based features need to distinguish what type of relation was used and potentially match on the content of the related-to event. To do that we introduce a new type of condition: `related_event_match`. This is largely similar to the existing `event_match`, but operates on the related-to event. Such a condition could look like this: ```json5 { "kind": "related_event_match", "rel_type": "m.in_reply_to", "include_fallbacks": false, "key": "sender", "pattern": "@me:my.server" } ``` This condition can be used to notify me whenever someone sends a reply to my messages. - `rel_type` is the relation type. For the sake of compatibility, replies should be matched as if they were sent in the relation format from [MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674) with a `rel_type` of `m.in_reply_to`. If the event has any relation of this type, the related event should be matched using `pattern` and `key`. - `include_fallbacks` decides if the relation should be followed even for fallbacks (i.e. relations with the `is_falling_back` property set to `true` like for threads). Defaults to false so only actual relations are counted. - `key` (optional): The dot-separated field of the event to match, e.g. `content.body` or `sender`. If it is not present, the condition should match all events, that have a relation of type `rel_type`. - `pattern` (optional): The glob-style pattern to match against. `key` and `pattern` have exactly the same meaning as in `event_match` conditions. See https://github.com/matrix-org/matrix-doc/issues/2637 for a clarification of their behaviour. `key` and `pattern` are optional to allow you to enable or suppress all notifications for a specific relation type. For example one could suppress notifications for all events with a relation from [threads](https://github.com/matrix-org/matrix-doc/pull/3440) and all [edits](https://github.com/matrix-org/matrix-doc/pull/2676) with the following two conditions: ```json5 { "kind": "related_event_match", "rel_type": "m.replace" } ``` ```json5 { "kind": "related_event_match", "rel_type": "m.thread" } ``` Without a `key` and `pattern` the push rule can be evaluated without fetching the related to event. If one of those two fields is missing, a server should prevent those rules from being added with the appropriate error code. (A client wouldn't have a choice but to ignore those keys if the server failed to prevent the rule from being added.) A client can check for the `related_event_match` condition being supported by testing for an existing `.m.rule.reply` in the default rules. ### A push rule for replies To enable notifications for replies without relying on the reply fallback, but with similar semantics we also define a new default push rule. The proposed push rule differs slightly from the old behaviour, because it only notifies you for replies to your events, but it does not notify you for replies to events containing your display name or matrix ID. The rule should look like this: ```json5 { "rule_id": ".m.rule.reply", "default": true, "enabled": true, "conditions": [ { "kind": "related_event_match", "rel_type": "m.in_reply_to", "key": "sender", "pattern": "[the user's Matrix ID]" } ], "actions": [ "notify", { "set_tweak": "sound", "value": "default" }, { "set_tweak": "highlight" } ] } ``` This should be an override rule, since it can't be a content rule and should not be overridden when setting a room to mentions only. It should be placed just before `.m.rule.contains_display_name` in the list. This ensures you get notified for replies to all events you sent. The actions are the same as for `.m.rule.contains_display_name` and `.m.rule.contains_user_name`. No other rules are proposed as no other relations are in the specification as of writing this MSC to decrease dependencies. ## Potential issues Most push rules for relations will need a lookup into a second event. This causes additional implementation complexity and can potentially be expensive. Looking up one event shouldn't be that heavy, but it is overhead that wasn't there before and it needs to be evaluated for every event, so it clearly is somewhat performance sensitive. If the related to event is not present on the homeserver, evaluating the push rule may be delayed or fail completely. For most rules this should not be an issue. You can assume the event was not sent by a user on your server if the event is not present on your server. In general clients and servers should do their best to evaluate the condition. If they fail to do so (possibly because they can't look up the event asynchronously) in a timely manner, the condition may be ignored/evaluated to false. This should affect only a subset of events, because in general relations happen to events in close proximity. There is a risk of missing notifications for replies to very old messages and similar relations. [Threads](https://github.com/matrix-org/matrix-doc/pull/3440) use replies [as a fallback](https://github.com/matrix-org/matrix-doc/pull/3440/files#diff-113727ce0257b4dc0ad6f1087b6402f2cfcb6ff93272757b947bf1ce444056aeR82). This would cause a notification with the new `.m.rule.reply` rule. To prevent that this MSC adds the `include_fallbacks` key to the rule, so that reply relations only added as a fallback are ignored. (Currently `is_falling_back` key is in a bit of a weird location. Maybe this can be amended in the threading MSC to be a bit more generic before it is added to the spec.) Adding a new rule that causes notifications will force users to change their notification settings again. In this case, a user who disabled notifications for mentions (or set them to silent) may be surprised to suddenly start receiving noisy notifications for replies. Worse, in the transition period, clients might not have a UI to disable the new notifications. This is a risk with all push rule changes and since it allows for a much better control over what notifies you, the tradeoff should be acceptable. Many users disable mention based pings, because they [can be error prone](https://github.com/matrix-org/matrix-doc/pull/3517), but they may not actually have intended to also disable notifications for replies, which should only trigger for actual replies to your messages. So for a significant chunk of people disabling mentions this should be an improvement. ## Alternatives - One could add an optional `rel_type` key to all existing conditions. This would allow you to also easily match by `contains_display_name`, `sender_notification_permission` and `room_member_count`. Out of those conditions only `contains_display_name` seems to be useful in a related event context. Having a potentially expensive key like `rel_type` available for all conditions would also increase implementation complexity. As such this MSC proposes the minimum amount of conditions to support push rules for most relations, although allowing `rel_type` on `contains_display_name` and `event_match` could be a good alternative. - Beeper has a [similar feature in their synapse](https://gitlab.com/beeper/synapse/-/commit/44a1728b6b021f97900c89e0c00f7d1a23ce0d43), but it does not allow you to filter by relation type. ## Security considerations - These pushrules could be used to increase load on the homeserver. Apart from that there shouldn't be any potential security issues. ## Unstable prefix While this proposal is still in progress, implementations should use the unstable prefix `im.nheko.msc3664` for the `related_event_match` condition. As a result it should be called `im.nheko.msc3664.related_event_match`.