improve documentation of ephemeral events

content/client-server-api/_index.md

@@ -1521,7 +1521,7 @@ any given point in time:
 
 ### Types of room events
 
-Room events are split into two categories:
+Room events are split into three categories:
 
 * **State events**: These are events which update the metadata state of the room (e.g. room
 topic, room membership etc). State is keyed by a tuple of event `type`
@@ -1532,6 +1532,12 @@ overwritten.
 typically communication such as sending an instant message or setting up
 a VoIP call.
 
+* **Ephemeral events**: These are events which are not persisted in the room's
+timeline. In this version of the spec, these are [typing
+notification](#typing-notifications) and [read receipt](#receipts) events. Note
+that, unlike state events and message events, there is currently no way of
+defining custom ephemeral events.
+
 This specification outlines several events, all with the event type
 prefix `m.`. (See [Room Events](#room-events) for the m. event
 specification.) However, applications may wish to add their own type of
@@ -1559,7 +1565,9 @@ in [room version 1](/rooms/v1#event-format) and [room version
 
 However, it is unusual that a Matrix client would encounter this event
 format. Instead, homeservers are responsible for converting events into the
-format shown below so that they can be easily parsed by clients.
+format shown below so that they can be easily parsed by clients. Note that the
+format below only applies to state and message events; ephemeral events will
+only have the `type` and `content` properties.
 
 {{% boxes/warning %}}
 Event bodies are considered untrusted data. This means that any application using

data/api/client-server/definitions/sync_filter.yaml

@@ -62,8 +62,7 @@ properties:
       ephemeral:
         allOf:
         - $ref: room_event_filter.yaml
-        description: The events that aren't recorded in the room history, e.g. typing
+        description: The ephemeral events to include for rooms.
-          and receipts, to include for rooms.
       include_leave:
         description: Include rooms that the user has left in the sync, default false
         type: boolean

data/api/client-server/sync.yaml

@@ -219,9 +219,7 @@ paths:
                           title: Ephemeral
                           type: object
                           description: |-
-                            The ephemeral events in the room that aren't
+                            The new ephemeral events in the room.
-                            recorded in the timeline or state of the room.
-                            e.g. typing.
                           allOf:
                             - $ref: "definitions/event_batch.yaml"
                         account_data: