wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Improve presentation of push rules kinds and actions (#1348)

Browse source
This commit is contained in:
David Robertson 2022-11-22 16:01:23 +00:00 • committed by GitHub
parent 4534124742
commit 07442876ce
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 83 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

98
content/client-server-api/modules/push.md
View file

@ -144,27 +144,27 @@ the value of `kind`.
The different `kind`s of rule, in the order that they are checked, are:
Override Rules `override`
The highest priority rules are user-configured overrides.
1. **Override rules (`override`).**
The highest priority rules are user-configured overrides.
Content-specific Rules `content`
These configure behaviour for (unencrypted) messages that match certain
patterns. Content rules take one parameter: `pattern`, that gives the
glob pattern to match against. This is treated in the same way as
`pattern` for `event_match`.
1. **Content-specific rules (`content`).**
These configure behaviour for (unencrypted) messages that match certain
patterns. Content rules take one parameter: `pattern`, that gives the
glob pattern to match against. This is treated in the same way as
`pattern` for `event_match`.
Room-specific Rules `room`
These rules change the behaviour of all messages for a given room. The
`rule_id` of a room rule is always the ID of the room that it affects.
1. **Room-specific rules (`room`).**
These rules change the behaviour of all messages for a given room. The
`rule_id` of a room rule is always the ID of the room that it affects.
Sender-specific rules `sender`
These rules configure notification behaviour for messages from a
specific Matrix user ID. The `rule_id` of Sender rules is always the
Matrix user ID of the user whose messages they'd apply to.
1. **Sender-specific rules (`sender`).**
These rules configure notification behaviour for messages from a
specific Matrix user ID. The `rule_id` of Sender rules is always the
Matrix user ID of the user whose messages they'd apply to.
Underride rules `underride`
These are identical to `override` rules, but have a lower priority than
`content`, `room` and `sender` rules.
1. **Underride rules (`underride`).**
These are identical to `override` rules, but have a lower priority than
`content`, `room` and `sender` rules.
Rules with the same `kind` can specify an ordering priority. This
determines which rule is selected in the event of multiple matches. For
@ -186,48 +186,56 @@ how a notification is delivered for a matching event. The following
actions are defined:
`notify`
This causes each matching event to generate a notification.
: This causes each matching event to generate a notification.
`dont_notify`
This prevents each matching event from generating a notification
: This prevents each matching event from generating a notification.
`coalesce`
This enables notifications for matching events but activates homeserver
specific behaviour to intelligently coalesce multiple events into a
single notification. Not all homeservers may support this. Those that do
not support it should treat it as the `notify` action.
: This enables notifications for matching events but activates homeserver
specific behaviour to intelligently coalesce multiple events into a
single notification. Not all homeservers may support this. Those that do
not support it should treat it as the `notify` action.
`set_tweak`
Sets an entry in the `tweaks` dictionary key that is sent in the
notification request to the Push Gateway. This takes the form of a
dictionary with a `set_tweak` key whose value is the name of the tweak
to set. It may also have a `value` key which is the value to which it
should be set.
The following tweaks are defined:
: Sets an entry in the `tweaks` dictionary key that is sent in the
notification request to the Push Gateway. This takes the form of a
dictionary with a `set_tweak` key whose value is the name of the tweak
to set. It may also have a `value` key which is the value to which it
should be set.
* `sound`: A string representing the sound to be played when this notification
arrives. A value of `default` means to play a default sound. A device
may choose to alert the user by some other means if appropriate, eg.
vibration.
The following tweaks are defined:
* `highlight`: A boolean representing whether or not this message should be highlighted
in the UI. This will normally take the form of presenting the message in
a different colour and/or style. The UI might also be adjusted to draw
particular attention to the room in which the event occurred. If a
`highlight` tweak is given with no value, its value is defined to be
`true`. If no highlight tweak is given at all then the value of
`highlight` is defined to be false.
`sound`
Tweaks are passed transparently through the homeserver so client
applications and Push Gateways may agree on additional tweaks. For
example, a tweak may be added to specify how to flash the notification
light on a mobile device.
: A string representing the sound to be played when this notification
arrives. A value of `default` means to play a default sound. A device
may choose to alert the user by some other means if appropriate, eg.
vibration.
`highlight`
: A boolean representing whether or not this message should be highlighted
in the UI. This will normally take the form of presenting the message in
a different colour and/or style. The UI might also be adjusted to draw
particular attention to the room in which the event occurred. If a
`highlight` tweak is given with no value, its value is defined to be
`true`. If no highlight tweak is given at all then the value of
`highlight` is defined to be false.
Tweaks are passed transparently through the homeserver so client
applications and Push Gateways may agree on additional tweaks. For
example, a tweak may be added to specify how to flash the notification
light on a mobile device.
Actions that have no parameters are represented as a string. Otherwise,
they are represented as a dictionary with a key equal to their name and
other keys as their parameters, e.g.
`{ "set_tweak": "sound", "value": "default" }`
`{ "set_tweak": "sound", "value": "default" }`.
###### Conditions