From 96b32f68f924b3df7ef735f013e8062df93639cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Wed, 11 Dec 2024 23:38:59 +0100 Subject: [PATCH] Allow sending ephemeral data to application services (#2018) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit As per MSC2409. Signed-off-by: Kévin Commaille --- .../newsfragments/2018.feature | 1 + content/application-service-api.md | 33 +++++++++++++++++++ .../definitions/registration.yaml | 7 ++++ .../api/application-service/transactions.yaml | 24 ++++++++++++++ 4 files changed, 65 insertions(+) create mode 100644 changelogs/application_service/newsfragments/2018.feature diff --git a/changelogs/application_service/newsfragments/2018.feature b/changelogs/application_service/newsfragments/2018.feature new file mode 100644 index 000000000..07d6e62a6 --- /dev/null +++ b/changelogs/application_service/newsfragments/2018.feature @@ -0,0 +1 @@ +Allow sending ephemeral data to application services, as per [MSC2409](https://github.com/matrix-org/matrix-spec-proposals/pull/2409). diff --git a/content/application-service-api.md b/content/application-service-api.md index a7526e640..2882f3d97 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -207,6 +207,39 @@ processed the events. {{% http-api spec="application-service" api="transactions" %}} +##### Pushing ephemeral data + +{{% added-in v="1.13" %}} + +If the `receive_ephemeral` settings is enabled in the [registration](#registration) +file, homeservers MUST send ephemeral data that is relevant to the application +service via the transaction API, using the `ephemeral` property of the request's +body. This property is an array that is effectively a combination of the +`presence` and `ephemeral` sections of the client-server [`/sync`](/client-server-api/#get_matrixclientv3sync) +API. + +There are currently three event types that can be delivered to an application +service: + +- **[`m.presence`](/client-server-api/#mpresence)**: MUST be sent to the +application service if the data would apply contextually. For example, a +presence update for a user an application service shares a room with, or +matching one of the application service's namespaces. +- **[`m.typing`](/client-server-api/#mtyping)**: MUST be sent to the application +service under the same rules as regular events, meaning that the application +service must have registered interest in the room itself, or in a user that is +in the room. The data MUST use the same format as the client-server API, with +the addition of a `room_id` property at the top level to identify the room that +they were sent in. +- **[`m.receipt`](/client-server-api/#mreceipt)**: MUST be sent to the +application service under the same rules as regular events, meaning that the +application service must have registered interest in the room itself, or in a +user that is in the room. The data MUST use the same format as the client-server +API, with the addition of a `room_id` property at the top level to identify the +room that they were sent in. [Private read receipts](/client-server-api/#private-read-receipts) +MUST only be sent for users matching one of the application service's +namespaces. Normal read receipts and threaded read receipts are always sent. + #### Pinging {{% added-in v="1.7" %}} diff --git a/data/api/application-service/definitions/registration.yaml b/data/api/application-service/definitions/registration.yaml index 2d65a32c1..ce702df0e 100644 --- a/data/api/application-service/definitions/registration.yaml +++ b/data/api/application-service/definitions/registration.yaml @@ -32,6 +32,13 @@ properties: description: |- The localpart of the user associated with the application service. Events will be sent to the AS if this user is the target of the event, or is a joined member of the room where the event occurred. + receive_ephemeral: + type: boolean + x-addedInMatrixVersion: "1.13" + description: |- + Whether the application service wants to [receive ephemeral data](/application-service-api/#pushing-ephemeral-data). + + Defaults to `false` if not present. namespaces: type: object title: Namespaces diff --git a/data/api/application-service/transactions.yaml b/data/api/application-service/transactions.yaml index a94434ccc..295129739 100644 --- a/data/api/application-service/transactions.yaml +++ b/data/api/application-service/transactions.yaml @@ -46,6 +46,15 @@ paths: schema: type: object example: { + "ephemeral": [ + { + "$ref": "../../event-schemas/examples/m.receipt.yaml", + "room_id": "!jEsUZKDJdhlrceRyVU:example.org" + }, + { + "$ref": "../../event-schemas/examples/m.presence.yaml" + }, + ], "events": [ { "$ref": "../../event-schemas/examples/m.room.member.yaml" @@ -61,6 +70,21 @@ paths: description: A list of events, formatted as per the Client-Server API. items: $ref: ../client-server/definitions/client_event.yaml + ephemeral: + type: array + x-addedInMatrixVersion: "1.13" + description: |- + A list of ephemeral data, if the `receive_ephemeral` setting was enabled in the + [registration](/application-service-api/#registration) file. + + There are only three event types that can currently occur in this list: `m.presence`, + `m.typing`, and `m.receipt`. Room-scoped ephemeral data (`m.typing` and + `m.receipt`) MUST include a `room_id` property to identify the room that they + were sent in. + + This property can be omitted if it would be empty. + items: + $ref: ../../event-schemas/schema/core-event-schema/event.yaml required: - events description: Transaction information