From 38290cfc32ebf8188c18b3a30db8c99ab5d83f76 Mon Sep 17 00:00:00 2001
From: Hubert Chathi <hubertc@matrix.org>
Date: Wed, 12 Oct 2022 16:59:06 -0400
Subject: [PATCH] improve documentation of ephemeral events

---
 content/client-server-api/_index.md                 | 12 ++++++++++--
 data/api/client-server/definitions/sync_filter.yaml |  3 +--
 data/api/client-server/sync.yaml                    |  4 +---
 3 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index dd50f225..afa92b8c 100644
--- a/content/client-server-api/_index.md
+++ b/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
diff --git a/data/api/client-server/definitions/sync_filter.yaml b/data/api/client-server/definitions/sync_filter.yaml
index 0b4a8dca..0167cdd8 100644
--- a/data/api/client-server/definitions/sync_filter.yaml
+++ b/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
-          and receipts, to include for rooms.
+        description: The ephemeral events to include for rooms.
       include_leave:
         description: Include rooms that the user has left in the sync, default false
         type: boolean
diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml
index 93265cae..091456f5 100644
--- a/data/api/client-server/sync.yaml
+++ b/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
-                            recorded in the timeline or state of the room.
-                            e.g. typing.
+                            The new ephemeral events in the room.
                           allOf:
                             - $ref: "definitions/event_batch.yaml"
                         account_data: