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>
matrix-org · Oct 4, 2022 · d3d4afd · d3d4afd
1 parent 098aabd
commit d3d4afd
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 1 deletion.
diff --git a/changelogs/client_server/newsfragments/1261.clarification b/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)
diff --git a/data/api/client-server/receipts.yaml b/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