From d3d4afdbfde3f2763ed832227469dbcb6b4371f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 4 Oct 2022 16:09:23 +0200
Subject: [PATCH] Receipts: Add `thread_id` to the `/receipt` endpoint (#1261)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* 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>
---
 .../newsfragments/1261.clarification          |  1 +
 data/api/client-server/receipts.yaml          | 26 ++++++++++++++++++-
 2 files changed, 26 insertions(+), 1 deletion(-)
 create mode 100644 changelogs/client_server/newsfragments/1261.clarification

diff --git a/changelogs/client_server/newsfragments/1261.clarification b/changelogs/client_server/newsfragments/1261.clarification
new file mode 100644
index 000000000..a973a1592
--- /dev/null
+++ 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)
\ No newline at end of file
diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml
index a4dabdd2a..7a8dc2798 100644
--- 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