Matrix Push Rules & Notifications

Getting notifications

As some background, clients receive notifications in one of two ways, via polling /sync and/or via push notifications.

Web-based clients often receive events via polling:

The sync response (both initial and incremental) include the count of unread notifications and unread highlight notifications per room.

Mobile applications often receive events via push [3]:

Push notifications include the event information (or just the event ID) and whether the event was a highlight notification. (The event being pushed implies it increased the notification count.)

Getting events which generated notifications

There’s an API to retrieve a list of events which the user has been notified about. This powers the “notification panel” on Element Web and is meant to help users catch-up on missed notifications.

It is fairly underspecified and the Synapse implementation has limitations:

• Highlight notifications are only kept for 30 days
• Non-highlight notifications are only kept for 72 hours

Additionally it works poorly for encrypted rooms.

Getting the configured push rules?

There’s a set of APIs to fetch or modify push rules, they let you:

• Fetch all push rules
• Create or delete an individual push rule
• Fetch or update an individual push rule’s actions
• Fetch or enable/disable an individual push rule

An initial sync includes all of a user’s push rules under the user’s account data.

Any changes to push rules are included in incremental syncs. Except for newly added rules to the specification (this is likely a homeserver bug).

Note that you cannot use the account data APIs to configure push rules. [4]

What makes up a push rule?

A push rule is a JSON object with the following fields:

• rule_id: Unique (per-user) ID for the rule.
  • The rule_id for default rules have a special form (they start with a dot: .).
• default: Whether the rule is part of the predefined set of rules.
• enabled: Whether the rule is enabled.
• conditions: an array of 0 or more conditions to match.
• actions: 0 or more actions to take if the rule matches.

All conditions must match for a push rule to match. If there are no conditions, then the push rule always matches. Possible conditions include:

• Check event properties against patterns or exact values
  • Strings can be compared via globbing or exact values.
  • The globbing behavior changes if you’re checking the body property or not.
• Check against the number of room members
  • Used to (incorrectly) check if a room is a direct message.
• Check if a user can perform an action via power rules
  • The only defined option is whether a user can send @room.

Push rule actions define what to do once a push rule matches an event.

• notify: increment the notification count and send a push notification. Uses “tweaks” to optionally:
  • Play a sound.
  • Create a highlight notification, this causes the highlight count to be incremented (in addition to the notification count).
• Can be an empty list to do nothing.

There are other undefined or no-op actions (dont_notify, coalesce) which will be removed in the next version of the spec. [5]

Types of push rules

Push rules have a type associated with them, these are executed in order:

• Override: generic high priority rules
• Content-specific: applies to messages which have a body that matches a pattern
• Room-specific: applies to messages of a room
• Sender-specific: applies to messages from a sender
• Underride: generic low priority rules

The previously discussed shape of push rules is not the full story! There are special cases which do not accept conditions, but can be mapped to them.

• Content-specific: has a pattern field which maps to a pattern against the body property.
• Room-specific: the rule_id is re-used to match against the room ID.
• Sender-specific: the rule_id is re-used to match against the event sender.

Other “standard” rules

Element creates custom push rules based on a known form. [8]

• Keywords (implemented as a content-specific rule with a pattern)
• Per-room overrides:
  • All messages (implemented as a room-specific rule with a notify action)
  • Mentions & keywords (implemented as a room-specific rule with no actions)
  • Mute (implemented as an override rule to match the room ID with no actions)

Matrix also allows defining arbitrary rules (e.g. to change behavior for particular rooms, senders, message types, etc.)

What about unread rooms?

The unread (“bold”) rooms logic in Element Web is completely custom and outside of the Matrix specification.

• Will the event be shown ?
• Is it not an ignored event type ?
• Is it not redacted ?
• Does a renderer exist for the event ?

Note that if you enable hidden events (or tweak other options to show events) then the behavior changes!