wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Spec MSC2285: Private read receipts (#1216)

Browse source 
* Convert `m.receipt.yaml` to traditional YAML

* Spec MSC2285 (private read receipts)

* Add some obvious copyright headers

* Add changelog entries

* Appease the linter

Apparently it hates it when you do this.

* Allow m.fully_read on /receipts

* Apply suggestions from code review

Co-authored-by: Matthew Hodgson <matthew@matrix.org>

Co-authored-by: Matthew Hodgson <matthew@matrix.org>
This commit is contained in:
Travis Ralston 2022-09-12 16:34:51 -06:00 • committed by GitHub
parent a6990ff27c
commit e406bd94f6
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 146 additions and 66 deletions
Download patch file Download diff file Expand all files Collapse all files

39
content/client-server-api/modules/receipts.md
View file

@ -4,10 +4,14 @@ type: module
### Receipts
{{< changed-in v="1.4" >}} Added private read receipts.
This module adds in support for receipts. These receipts are a form of
acknowledgement of an event. This module defines a single
acknowledgement: `m.read` which indicates that the user has read up to a
given event.
acknowledgement of an event. This module defines the `m.read` receipt
for indicating that the user has read up to a given event, and `m.read.private`
to achieve the same purpose without any other user being aware. Primarily,
`m.read.private` is intended to clear [notifications](#receiving-notifications)
without advertising read-up-to status to others.
Sending a receipt for each event can result in sending large amounts of
traffic to a homeserver. To prevent this from becoming a problem,
@ -59,12 +63,36 @@ following HTTP APIs.
{{% http-api spec="client-server" api="receipts" %}}
##### Private read receipts
{{% added-in v="1.4" %}}
Some users would like to mark a room as read, clearing their [notification counts](#receiving-notifications),
but not give away the fact that they've read a particular message yet. To
achieve this, clients can send `m.read.private` receipts instead of `m.read`
to do exactly that: clear notifications and not broadcast the receipt to
other users.
Servers MUST NOT send the `m.read.private` receipt to any other user than the
one which originally sent it.
Between `m.read` and `m.read.private`, the receipt which is more "ahead" or
"recent" is used when determining the highest read-up-to mark. See the
[notifications](#receiving-notifications) section for more information on
how this affects notification counts.
If a client sends an `m.read` receipt which is "behind" the `m.read.private`
receipt, other users will see that change happen but the sending user will
not have their notification counts rewound to that point in time. While
uncommon, it is considered valid to have an `m.read` (public) receipt lag
several messages behind the `m.read.private` receipt, for example.
#### Server behaviour
For efficiency, receipts SHOULD be batched into one event per room
before delivering them to clients.
Receipts are sent across federation as EDUs with type `m.receipt`. The
Some receipts are sent across federation as EDUs with type `m.receipt`. The
format of the EDUs are:
```
@ -80,7 +108,8 @@ format of the EDUs are:
```
These are always sent as deltas to previously sent receipts. Currently
only a single `<receipt_type>` should be used: `m.read`.
only a single `<receipt_type>` should be used: `m.read`. `m.read.private`
MUST NOT appear in this federated `m.receipt` EDU.
#### Security considerations