99 lines
3.4 KiB
ReStructuredText
99 lines
3.4 KiB
ReStructuredText
.. Copyright 2016 OpenMarket Ltd
|
|
..
|
|
.. Licensed under the Apache License, Version 2.0 (the "License");
|
|
.. you may not use this file except in compliance with the License.
|
|
.. You may obtain a copy of the License at
|
|
..
|
|
.. http://www.apache.org/licenses/LICENSE-2.0
|
|
..
|
|
.. Unless required by applicable law or agreed to in writing, software
|
|
.. distributed under the License is distributed on an "AS IS" BASIS,
|
|
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
.. See the License for the specific language governing permissions and
|
|
.. limitations under the License.
|
|
|
|
Receipts
|
|
========
|
|
|
|
.. _module: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.
|
|
|
|
Sending a receipt for each event can result in sending large amounts of traffic
|
|
to a homeserver. To prevent this from becoming a problem, receipts are implemented
|
|
using "up to" markers. This marker indicates that the acknowledgement applies
|
|
to all events "up to and including" the event specified. For example, marking
|
|
an event as "read" would indicate that the user had read all events *up to* the
|
|
referenced event. See the `Receiving notifications <#receiving-notifications>`_
|
|
section for more information on how read receipts affect notification counts.
|
|
|
|
Events
|
|
------
|
|
Each ``user_id``, ``receipt_type`` pair must be associated with only a
|
|
single ``event_id``.
|
|
|
|
{{m_receipt_event}}
|
|
|
|
Client behaviour
|
|
----------------
|
|
|
|
In ``/sync``, receipts are listed under the ``ephemeral`` array of events
|
|
for a given room. New receipts that come down the event streams are deltas
|
|
which update existing mappings. Clients should replace older receipt acknowledgements
|
|
based on ``user_id`` and ``receipt_type`` pairs. For example::
|
|
|
|
Client receives m.receipt:
|
|
user = @alice:example.com
|
|
receipt_type = m.read
|
|
event_id = $aaa:example.com
|
|
|
|
Client receives another m.receipt:
|
|
user = @alice:example.com
|
|
receipt_type = m.read
|
|
event_id = $bbb:example.com
|
|
|
|
The client should replace the older acknowledgement for $aaa:example.com with
|
|
this one for $bbb:example.com
|
|
|
|
Clients should send read receipts when there is some certainty that the event in
|
|
question has been **displayed** to the user. Simply receiving an event does not
|
|
provide enough certainty that the user has seen the event. The user SHOULD need
|
|
to *take some action* such as viewing the room that the event was sent to or
|
|
dismissing a notification in order for the event to count as "read". Clients
|
|
SHOULD NOT send read receipts for events sent by their own user.
|
|
|
|
A client can update the markers for its user by interacting with the following
|
|
HTTP APIs.
|
|
|
|
{{receipts_cs_http_api}}
|
|
|
|
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
|
|
format of the EDUs are::
|
|
|
|
{
|
|
<room_id>: {
|
|
<receipt_type>: {
|
|
<user_id>: { <content> }
|
|
},
|
|
...
|
|
},
|
|
...
|
|
}
|
|
|
|
These are always sent as deltas to previously sent receipts. Currently only a
|
|
single ``<receipt_type>`` should be used: ``m.read``.
|
|
|
|
Security considerations
|
|
-----------------------
|
|
|
|
As receipts are sent outside the context of the event graph, there are no
|
|
integrity checks performed on the contents of ``m.receipt`` events.
|