Receipts: Add thread_id to the /receipt endpoint (#1261)

* Receipts: Add thread_id to the /receipt endpoint

It seems to have been omitted in #1255

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Fix missing backtick

* Apply suggestion for error description

Co-authored-by: Travis Ralston <travpc@gmail.com>

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
Co-authored-by: Travis Ralston <travpc@gmail.com>

changelogs/client_server/newsfragments/1261.clarification

@@ -0,0 +1 @@
+Add `thread_id` to the `/receipt` endpoint, as per [MSC3771](https://github.com/matrix-org/matrix-spec-proposals/pull/3771)

changelogs/client_server/newsfragments/1263.clarification

@@ -0,0 +1 @@
+Fix various typos throughout the specification.

content/client-server-api/_index.md

@@ -1988,11 +1988,6 @@ of times that `key` was used by child events.
 
 The actual aggregation format depends on the `rel_type`.
 
-{{% boxes/note %}}
-This specification does not currently describe any `rel_type`s which require
-aggregation. This functionality forms a framework for future extensions.
-{{% /boxes/note %}}
-
 Aggregations are sometimes automatically included by a server alongside the parent
 event. This is known as a "bundled aggregation" or "bundle" for simplicity. The
 act of doing this is "bundling".
@@ -2644,4 +2639,4 @@ systems.
 {{< cs-module name="moderation_policies" >}}
 {{< cs-module name="spaces" >}}
 {{< cs-module name="event_replacements" >}}
-{{< cs-module name="threading" >}}
+{{< cs-module name="threading" >}}

data/api/client-server/receipts.yaml

@@ -74,8 +74,18 @@ paths:
           required: true
           schema:
             type: object
+            properties:
+              thread_id:
+                type: string
+                x-addedInMatrixVersion: "1.4"
+                description: |-
+                    The root thread event's ID (or `main`) for which
+                    thread this receipt is intended to be under. If
+                    not specified, the read receipt is *unthreaded*
+                    (default).
             example: {
-              }
+              "thread_id": "main"
+            }
       responses:
         200:
           description: The receipt was sent.
@@ -88,5 +98,19 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/errors/rate_limited.yaml"
+        400:
+          description: |-
+            The `thread_id` is invalid in some way. For example:
+            * It is not a string.
+            * It is empty.
+            * It is provided for an incompatible receipt type.
+            * The `event_id` is not related to the `thread_id`.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_INVALID_PARAM",
+              "error": "thread_id field must be a non-empty string"
+            }
       tags:
         - Room participation