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 <[email protected]>

* changelog

Signed-off-by: Kévin Commaille <[email protected]>

* Fix missing backtick

* Apply suggestion for error description

Co-authored-by: Travis Ralston <[email protected]>

Signed-off-by: Kévin Commaille <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>

Author: zecakeh

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)

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