diff --git a/content/application-service-api.md b/content/application-service-api.md index a7526e64..7062f7da 100644 --- a/content/application-service-api.md +++ b/content/application-service-api.md @@ -207,6 +207,33 @@ processed the events. {{% http-api spec="application-service" api="transactions" %}} +##### Pushing EDUs + +{{% added-in v="1.13" %}} + +If the `receive_ephemeral` settings is enabled in the [registration](#registration) +file, homeservers MUST send all EDUs that are 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. It means that there are only three event types that can currently occur: +[`m.presence`](/client-server-api/#mpresence), [`m.typing`](/client-server-api/#mtyping), +and [`m.receipt`](/client-server-api/#mreceipt). + +EDUs that can be associated to a particular room (i.e. `m.typing` or `m.receipt`) +MUST also include a `room_id` property to identify the room that they were sent +in. They should 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. +[Private read receipts](/client-server-api/#private-read-receipts) should only +be sent for users matching one of the application service's namespaces. Normal +read receipts and threaded read receipts are always sent. + +EDUs which are not associated with a particular room (i.e. `m.presence`), should +be sent to the application service if the EDU 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. + #### 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 2d65a32c..ef3ef430 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 EDUs](/application-service-api/#pushing-edus). + + 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 a94434cc..5b8d58bd 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,20 @@ 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 events (aka EDUs), 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: `m.presence`, + `m.typing`, and `m.receipt`. Room-scoped EDUs (`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