Document receipts

specification/46_receipts.rst

@@ -0,0 +1,64 @@
+Receipts
+========
+
+Receipts are used to publish which events in a room the user or their devices
+have interacted with. For example, which events the user has read.
+
+For efficiency this is done as "up to" markers, i.e. marking a particular event
+as, e.g., read indicates the user has read all events *up to* that event.
+
+Client-Server API
+-----------------
+
+Clients will receive receipts in the following format::
+
+    {
+        "type": "m.receipt",
+        "room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org"
+        "content": {
+            "$1435641916114394fHBLK:matrix.org": {
+                "read": {
+                    "@erikj:jki.re": { "ts": 1436451550453 },
+                    ...
+                }
+            },
+            ...
+        }
+    }
+
+For efficiency, receipts are batched into one event per room. In the initialSync
+and v2 sync APIs the receipts are listed in a seperate top level receipts key.
+
+Each ``user_id``, ``receipt_type`` pair must be associated with only a single
+``event_id``.
+
+New receipts that come down the event streams are deltas. Deltas update
+existing mappings, clobbering based on ``user_id``, ``receipt_type`` pairs.
+
+
+A client can update the markers for its user by issuing a request::
+
+    POST /_matrix/client/v2_alpha/rooms/<room_id>/receipt/read/<event_id>
+
+Where the contents will of the POST will be included in the content sent to
+other users. The server will automatically set the ``ts`` field.
+
+
+Server-Server API
+-----------------
+
+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 reciepts.
+