From 809adf28112c13d65d5bc82a013e9e16f497ffd0 Mon Sep 17 00:00:00 2001
From: Hubert Chathi <hubertc@matrix.org>
Date: Tue, 18 Oct 2022 11:22:52 -0400
Subject: [PATCH] put canonical list of ephemeral events into /sync
 documentation

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

diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index afa92b8c..dd50f225 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 three categories:
+Room events are split into two 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,12 +1532,6 @@ 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
@@ -1565,9 +1559,7 @@ 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. Note that the
-format below only applies to state and message events; ephemeral events will
-only have the `type` and `content` properties.
+format shown below so that they can be easily parsed by clients.
 
 {{% 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 0167cdd8..0ea6e9c2 100644
--- a/data/api/client-server/definitions/sync_filter.yaml
+++ b/data/api/client-server/definitions/sync_filter.yaml
@@ -62,7 +62,9 @@ properties:
       ephemeral:
         allOf:
         - $ref: room_event_filter.yaml
-        description: The ephemeral events to include for rooms.
+        description: The ephemeral events to include for rooms. These are the
+          events that appear in the `ephemeral` property in the `/sync`
+          response.
       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 091456f5..c2c04d34 100644
--- a/data/api/client-server/sync.yaml
+++ b/data/api/client-server/sync.yaml
@@ -219,7 +219,11 @@ paths:
                           title: Ephemeral
                           type: object
                           description: |-
-                            The new ephemeral events in the room.
+                            The new ephemeral events in the room (events that
+                            aren't recorded in the timeline or state of the
+                            room). In this version of the spec, these are
+                            [typing notification](#typing-notifications) and
+                            [read receipt](#receipts) events.
                           allOf:
                             - $ref: "definitions/event_batch.yaml"
                         account_data: