Spec MSC3773: Threaded notifications

content/client-server-api/modules/push.md

@@ -107,8 +107,10 @@ determined by the push rules which apply to an event.
 
 When the user updates their read receipt (either by using the API or by
 sending an event), notifications prior to and including that event MUST
-be marked as read. Note that users can send both an `m.read` and
+be marked as read. Which specific events are affected can vary depending
-`m.read.private` receipt, both of which are capable of clearing notifications.
+on whether a [threaded read receipt](#threaded-read-receipts) was used.
+Note that users can send both an `m.read` and `m.read.private` receipt,
+both of which are capable of clearing notifications.
 
 If the user has both `m.read` and `m.read.private` set in the room then
 the receipt which is more recent/ahead must be used to determine where
@@ -121,6 +123,17 @@ ahead), however if the `m.read.private` receipt were to be updated to
 event D then the user has read up to D (the `m.read` receipt is now
 behind the `m.read.private` receipt).
 
+{{< added-in v="1.4" >}} When handling threaded read receipts, the server
+is to partition the notification count to each thread (with the main timeline
+being its own thread). To determine if an event is part of a thread the
+server follows the [event relationship](#forming-relationships-between-events)
+until it finds a thread root (as specified by the [threading module](#threading)),
+however it is not recommended that the server traverse infinitely. Instead,
+implementations are encouraged to do a maximum of 3 hops to find a thread
+before deciding that the event does not belong to a thread. This is primarily
+to ensure that future events, like `m.reaction`, are correctly considered
+"part of" a given thread.
+
 ##### Push Rules
 
 A push rule is a single rule that states under what *conditions* an

data/api/client-server/definitions/room_event_filter.yaml

@@ -1,4 +1,5 @@
 # Copyright 2016 OpenMarket Ltd
+# Copyright 2022 The Matrix.org Foundation C.I.C.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,6 +17,12 @@ allOf:
 - type: object
   title: RoomEventFilter
   properties:
+    unread_thread_notifications:
+      type: boolean
+      description: |-
+        If `true`, enables per-[thread](/client-server-api/#threading) notification
+        counts. Only applies to the `/sync` endpoint. Defaults to `false`.
+      x-addedInMatrixVersion: "1.4"
     lazy_load_members:
       type: boolean
       description: |-

data/api/client-server/sync.yaml

@@ -239,17 +239,50 @@ paths:
                             Counts of unread notifications for this room. See the
                             [Receiving notifications](/client-server-api/#receiving-notifications) section
                             for more information on how these are calculated.
+
+                            If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
+                            these counts will only be for the main timeline rather than all events in the room.
+                            See the [threading module](#threading) for more information.
+                          x-changedInMatrixVersion:
+                            1.4: |
+                              Updated to reflect behaviour of having `unread_thread_notifications` as `true` in
+                              the `RoomEventFilter` for `/sync`.
                           properties:
                             highlight_count:
                                 title: Highlighted notification count
                                 type: integer
                                 description: The number of unread notifications
-                                             for this room with the highlight flag set
+                                             for this room with the highlight flag set.
                             notification_count:
                                 title: Total notification count
                                 type: integer
                                 description: The total number of unread notifications
-                                             for this room
+                                             for this room.
+                        unread_thread_notifications:
+                          title: Unread Thread Notification Counts
+                          type: object
+                          description: |-
+                            If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
+                            the notification counts for each [thread](#threading) in this room. The object is
+                            keyed by thread root ID, with values matching `unread_notifications`.
+
+                            If a thread does not have any notifications it can be omitted from this object. If
+                            no threads have notification counts, this whole object can be omitted.
+                          x-addedInMatrixVersion: "1.4"
+                          additionalProperties:
+                            title: ThreadNotificationCounts
+                            type: object
+                            properties:
+                              highlight_count:
+                                title: ThreadedHighlightNotificationCount
+                                type: integer
+                                description: |-
+                                  The number of unread notifications for this *thread* with the highlight flag set.
+                              notification_count:
+                                title: ThreadedTotalNotificationCount
+                                type: integer
+                                description: |-
+                                  The total number of unread notifications for this *thread*.
                   invite:
                     title: Invited Rooms
                     type: object
@@ -424,6 +457,16 @@ paths:
                             }
                           }
                         ]
+                      },
+                      "unread_notifications": {
+                        "highlight_count": 1,
+                        "notification_count": 5
+                      },
+                      "unread_thread_notifications": {
+                        "$threadroot": {
+                          "highlight_count": 3,
+                          "notification_count": 6
+                        }
                       }
                     }
                   },