matrix-spec-proposals/proposals/3930-polls-notifications.md

MSC3930: Polls push rules/notifications

MSC3381 describes how chat polls can work, though deliberately leaves out details on how push rules or notifications could work for such a feature. This proposal aims to address that specific feature gap.

Readers should review MSC3381 to better understand how polls are intended to operate in a room.

Push rules are currently defined here in specification.

Proposal

Polls should behave similar to message events. To achieve this effect, we define the following underride push rules which mimic their m.room.message partners.

Note that order matters for push rules - these underride rules are to be inserted immediately after the .m.rule.encrypted underride push rule, in the order presented by this MSC.

{
  "rule_id": ".m.rule.poll_start_one_to_one",
  "default": true,
  "enabled": true,
  "conditions": [
    {"kind": "room_member_count", "is": "2"},

    // Note: `.` is escaped once, but for valid JSON we need to escape the escape.
    {"kind": "event_property_is", "key": "type", "value": "m\\.poll\\.start"}
  ],
  "actions": [
    "notify",
    {"set_tweak": "sound", "value": "default"}
  ]
}

{
  "rule_id": ".m.rule.poll_start",
  "default": true,
  "enabled": true,
  "conditions": [
    // Note: `.` is escaped once, but for valid JSON we need to escape the escape.
    {"kind": "event_property_is", "key": "type", "value": "m\\.poll\\.start"}
  ],
  "actions": [
    "notify"
  ]
}

{
  "rule_id": ".m.rule.poll_end_one_to_one",
  "default": true,
  "enabled": true,
  "conditions": [
    {"kind": "room_member_count", "is": "2"},

    // Note: `.` is escaped once, but for valid JSON we need to escape the escape.
    {"kind": "event_property_is", "key": "type", "value": "m\\.poll\\.end"}
  ],
  "actions": [
    "notify",
    {"set_tweak": "sound", "value": "default"}
  ]
}

{
  "rule_id": ".m.rule.poll_end",
  "default": true,
  "enabled": true,
  "conditions": [
    // Note: `.` is escaped once, but for valid JSON we need to escape the escape.
    {"kind": "event_property_is", "key": "type", "value": "m\\.poll\\.end"}
  ],
  "actions": [
    "notify"
  ]
}

Additionally, a new override rule is defined to suppress poll responses by default, inserted immediately after the .m.rule.room.server_acl override rule.

{
  "rule_id": ".m.rule.poll_response",
  "default": true,
  "enabled": true,
  "conditions": [
    // Note: `.` is escaped once, but for valid JSON we need to escape the escape.
    {"kind": "event_property_is", "key": "type", "value": "m\\.poll\\.response"}
  ],
  "actions": []
}

Note: Lack of actions means "don't do anything with matching events", or "don't notify".

Typically these rules would be kept in sync with the m.room.message rules they are based upon, however there is no requirement to do so. A client's approach might be to only keep them in sync while setting the values, rather than monitoring for changes to push rules.

Clients might find MSC3934 of value for keeping the rules in sync, though this MSC does not require MSC3934.

For the purposes of MSC3932, the push rules defined in this proposal are not affected by the room version limitations. This is due to polls not inherently being room version-specific, unlike other extensible event structures. For clarity, this means the push rules described here are treated the same as .m.rule.master (for example) - they always apply, regardless of room version.

Potential issues

The push rules for this feature are complex and not ideal. The author believes that it solves a short term need while other MSCs work on improving the notifications system. Most importantly, the author believes future MSCs which aim to fix notifications for extensible events in general will be a more preferred approach over this MSC's (hopefully) short-term solution.

General considerations

While the order within the MSC is deliberate for the new rules, the positioning relative to other rules already in the spec is fairly arbitrary. The new rules are placed at the end of each list (underride and override) for simplicity, but could realistically go anywhere in the list.

See "Dot-separated property paths" for more information on why we escape the event_property_is condition values.

Security considerations

None applicable - no new considerations need to be made with this proposal.

Unstable prefix

While this MSC is not considered stable, implementations should use org.matrix.msc3930.* as a prefix in place of m.* for the push rule IDs. As of writing, polls are only implemented using the legacy org.matrix.msc3381.poll.* prefix rather than the newer v2 prefix - implementations of this MSC should be aware of which version of MSC3381 they plan to support.