From 4f79ebe6090a78ee8653ea2f6a8d48626c432abc Mon Sep 17 00:00:00 2001 From: Timo K Date: Wed, 21 Jan 2026 17:13:22 +0100 Subject: [PATCH 1/7] initial commit "Sticky-events for the widget api" --- proposals/XXXX-sticky-events-widget-api.md | 50 ++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 proposals/XXXX-sticky-events-widget-api.md diff --git a/proposals/XXXX-sticky-events-widget-api.md b/proposals/XXXX-sticky-events-widget-api.md new file mode 100644 index 00000000000..289a16efed5 --- /dev/null +++ b/proposals/XXXX-sticky-events-widget-api.md @@ -0,0 +1,50 @@ +# Sticky-events for the widget api + +With [MSC4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354) a way to sticky events is introduced. +Sticky events are room events with a time limited delivery guarantee. They will be synced by participating clients even with gappy syncs. +(For the duration of the sticky duration `sticky_duration_ms`) + +This msc only specifies how the widget api uses this concept. [MSC4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354) +gives more details about the sticky events themselves. + +Exposing sticky events to the widget is required for widgets implementing MatrixRTC. +Sticky events are needed for encrypted MatrixRTC memberships that get reliably delivered. + +Since ElementCall (EC) is a widget and based on MatrixRTC this widget api proposal is required for EC to work. + +## Proposal + +### Sending Sticky events + +We extend the `"send_event"` request defined by [MSC2762](https://github.com/matrix-org/matrix-spec-proposals/pull/2762) +as follows: + +```jsonc +{ + state_key?: string; + type: string; + content: unknown; + room_id?: string; + delay?: number; // from https://github.com/matrix-org/matrix-spec-proposals/pull/4157 + sticky_duration_ms?: number; +} +``` + + +### Capabilities + +Two new capabilities will be introduces: + +- `m.send_receive_sticky_events`\ + allows to send sticky events by using the optional `sticky_duration_ms` property in a `fromWidget send_event` widget action. + All other `m.send.*` capabilities still apply. This capability allows sending sticky events of those types. + + +## Alternatives + +## Unstable prefix + +The following strings will have unstable prefixes: + +- The send delayed event capability:\ + `m.send_receive_sticky_events` -> `org.matrix.mscXXXX.send_receive_sticky_events` From de990406cad835c0256c05c7e913c073f986fb13 Mon Sep 17 00:00:00 2001 From: Timo K Date: Wed, 21 Jan 2026 17:14:31 +0100 Subject: [PATCH 2/7] update to correct MSC number --- ...ky-events-widget-api.md => 4407-sticky-events-widget-api.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{XXXX-sticky-events-widget-api.md => 4407-sticky-events-widget-api.md} (96%) diff --git a/proposals/XXXX-sticky-events-widget-api.md b/proposals/4407-sticky-events-widget-api.md similarity index 96% rename from proposals/XXXX-sticky-events-widget-api.md rename to proposals/4407-sticky-events-widget-api.md index 289a16efed5..2af16e97bed 100644 --- a/proposals/XXXX-sticky-events-widget-api.md +++ b/proposals/4407-sticky-events-widget-api.md @@ -47,4 +47,4 @@ Two new capabilities will be introduces: The following strings will have unstable prefixes: - The send delayed event capability:\ - `m.send_receive_sticky_events` -> `org.matrix.mscXXXX.send_receive_sticky_events` + `m.send_receive_sticky_events` -> `org.matrix.msc4407.send_receive_sticky_events` From 820e91557ec60bb28bc484d01860eec8108feaa8 Mon Sep 17 00:00:00 2001 From: Timo K Date: Wed, 21 Jan 2026 17:18:10 +0100 Subject: [PATCH 3/7] rename --- proposals/4407-sticky-events-widget-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4407-sticky-events-widget-api.md b/proposals/4407-sticky-events-widget-api.md index 2af16e97bed..c7a1274937d 100644 --- a/proposals/4407-sticky-events-widget-api.md +++ b/proposals/4407-sticky-events-widget-api.md @@ -1,4 +1,4 @@ -# Sticky-events for the widget api +# Sticky Events (widget-api) With [MSC4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354) a way to sticky events is introduced. Sticky events are room events with a time limited delivery guarantee. They will be synced by participating clients even with gappy syncs. From 22f8bb3c90402a10926b62590098d452d6381c42 Mon Sep 17 00:00:00 2001 From: Timo K Date: Wed, 21 Jan 2026 17:45:06 +0100 Subject: [PATCH 4/7] update --- proposals/4407-sticky-events-widget-api.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/proposals/4407-sticky-events-widget-api.md b/proposals/4407-sticky-events-widget-api.md index c7a1274937d..cb1f800c28c 100644 --- a/proposals/4407-sticky-events-widget-api.md +++ b/proposals/4407-sticky-events-widget-api.md @@ -35,9 +35,17 @@ as follows: Two new capabilities will be introduces: -- `m.send_receive_sticky_events`\ +- `m.send.sticky_event`\ allows to send sticky events by using the optional `sticky_duration_ms` property in a `fromWidget send_event` widget action. All other `m.send.*` capabilities still apply. This capability allows sending sticky events of those types. +- `m.receive.sticky_event`\ + If this capability is allowed the client will make sure the widget is aware about events that are currently sticky. + All events that are currently stikcy of types that are allowed by `m.send.*` capabilities will be included. + +### Widget Client Implementation +This has the following behavior impact in the widget client implementation: + - on widget startup the client will send all sticky events the widget is allowed to see. + - on capability negotiation where the widget gets granted `m.receive.sticky_event` the client will send all sticky events the widget is allowed to see. ## Alternatives @@ -46,5 +54,7 @@ Two new capabilities will be introduces: The following strings will have unstable prefixes: -- The send delayed event capability:\ - `m.send_receive_sticky_events` -> `org.matrix.msc4407.send_receive_sticky_events` +- The send sticky event capability:\ + `m.send.sticky_event` -> `org.matrix.msc4407.send.sticky_event` +- The send sticky event capability:\ + `m.receive.sticky_event` -> `org.matrix.msc4407.receive.sticky_event` From cac893e32e1bc5e6cca5b03e8947b0976aeb3e34 Mon Sep 17 00:00:00 2001 From: Timo K Date: Wed, 21 Jan 2026 17:57:09 +0100 Subject: [PATCH 5/7] Update 4407-sticky-events-widget-api.md --- proposals/4407-sticky-events-widget-api.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/proposals/4407-sticky-events-widget-api.md b/proposals/4407-sticky-events-widget-api.md index cb1f800c28c..95b0716aa78 100644 --- a/proposals/4407-sticky-events-widget-api.md +++ b/proposals/4407-sticky-events-widget-api.md @@ -21,12 +21,14 @@ as follows: ```jsonc { + // new + sticky_duration_ms?: number; + // other fields state_key?: string; type: string; content: unknown; room_id?: string; delay?: number; // from https://github.com/matrix-org/matrix-spec-proposals/pull/4157 - sticky_duration_ms?: number; } ``` @@ -47,6 +49,8 @@ This has the following behavior impact in the widget client implementation: - on widget startup the client will send all sticky events the widget is allowed to see. - on capability negotiation where the widget gets granted `m.receive.sticky_event` the client will send all sticky events the widget is allowed to see. + If the capability `m.send.sticky_event` is granted and the client receives a send event with `sticky_duration_ms` set, the client has to send a sticky event + as described in the [Sticky Events Widget API 4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354) using the `sticky_duration_ms`. ## Alternatives From e5184f8ad883f901969e61e123e8ae8102f98248 Mon Sep 17 00:00:00 2001 From: Timo K Date: Wed, 21 Jan 2026 18:20:27 +0100 Subject: [PATCH 6/7] Update 4407-sticky-events-widget-api.md --- proposals/4407-sticky-events-widget-api.md | 45 +++++++++++----------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/proposals/4407-sticky-events-widget-api.md b/proposals/4407-sticky-events-widget-api.md index 95b0716aa78..3bcd074d1ef 100644 --- a/proposals/4407-sticky-events-widget-api.md +++ b/proposals/4407-sticky-events-widget-api.md @@ -1,22 +1,21 @@ -# Sticky Events (widget-api) +# Sticky Events (Widget API) -With [MSC4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354) a way to sticky events is introduced. -Sticky events are room events with a time limited delivery guarantee. They will be synced by participating clients even with gappy syncs. -(For the duration of the sticky duration `sticky_duration_ms`) +With [MSC4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354), a way to send sticky events is introduced. +Sticky events are room events with a time-limited delivery guarantee. They will be synced by participating clients even across gappy syncs, for the duration specified by `sticky_duration_ms`. -This msc only specifies how the widget api uses this concept. [MSC4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354) -gives more details about the sticky events themselves. +This MSC only specifies how the Widget API uses this concept. [MSC4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354) +gives more details about sticky events themselves. -Exposing sticky events to the widget is required for widgets implementing MatrixRTC. -Sticky events are needed for encrypted MatrixRTC memberships that get reliably delivered. +Exposing sticky events to widgets is required for widgets implementing MatrixRTC. +Sticky events are needed for encrypted MatrixRTC membership events to be reliably delivered. -Since ElementCall (EC) is a widget and based on MatrixRTC this widget api proposal is required for EC to work. +Since ElementCall (EC) is a widget and is based on MatrixRTC, this Widget API proposal is required for EC to work. ## Proposal -### Sending Sticky events +### Sending sticky events -We extend the `"send_event"` request defined by [MSC2762](https://github.com/matrix-org/matrix-spec-proposals/pull/2762) +We extend the "send_event" request defined by [MSC2762](https://github.com/matrix-org/matrix-spec-proposals/pull/2762) as follows: ```jsonc @@ -32,25 +31,25 @@ as follows: } ``` - ### Capabilities -Two new capabilities will be introduces: +Two new capabilities will be introduced: - `m.send.sticky_event`\ - allows to send sticky events by using the optional `sticky_duration_ms` property in a `fromWidget send_event` widget action. - All other `m.send.*` capabilities still apply. This capability allows sending sticky events of those types. + Allows sending sticky events by using the optional `sticky_duration_ms` property in a `fromWidget send_event` widget action. + All other `m.send.*` capabilities still apply. This capability allows sending sticky events for those types. - `m.receive.sticky_event`\ - If this capability is allowed the client will make sure the widget is aware about events that are currently sticky. - All events that are currently stikcy of types that are allowed by `m.send.*` capabilities will be included. + If this capability is allowed, the client will make sure the widget is aware of events that are currently sticky. + All events that are currently sticky, of types that are allowed by `m.send.*` capabilities, will be included. ### Widget Client Implementation -This has the following behavior impact in the widget client implementation: - - on widget startup the client will send all sticky events the widget is allowed to see. - - on capability negotiation where the widget gets granted `m.receive.sticky_event` the client will send all sticky events the widget is allowed to see. - If the capability `m.send.sticky_event` is granted and the client receives a send event with `sticky_duration_ms` set, the client has to send a sticky event - as described in the [Sticky Events Widget API 4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354) using the `sticky_duration_ms`. +This has the following behavioral impact on the widget client implementation: +- On widget startup, the client will send all sticky events that the widget is allowed to see. +- After capability re-negotiation, when the widget is granted `m.receive.sticky_event`, the client will send all currently sticky events that the widget is allowed to see. + +If the capability `m.send.sticky_event` is granted and the client receives a send event with `sticky_duration_ms` set, the client must send a sticky event +as described in [MSC4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354), using the `sticky_duration_ms`. ## Alternatives @@ -60,5 +59,5 @@ The following strings will have unstable prefixes: - The send sticky event capability:\ `m.send.sticky_event` -> `org.matrix.msc4407.send.sticky_event` -- The send sticky event capability:\ +- The receive sticky event capability:\ `m.receive.sticky_event` -> `org.matrix.msc4407.receive.sticky_event` From 75dfeadbbb8fa4725dd976defc197333a2471bb8 Mon Sep 17 00:00:00 2001 From: Timo K Date: Fri, 23 Jan 2026 11:15:19 +0100 Subject: [PATCH 7/7] simplify and make receive client bahviour more explicit --- proposals/4407-sticky-events-widget-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/4407-sticky-events-widget-api.md b/proposals/4407-sticky-events-widget-api.md index 3bcd074d1ef..ac08989cb45 100644 --- a/proposals/4407-sticky-events-widget-api.md +++ b/proposals/4407-sticky-events-widget-api.md @@ -44,9 +44,9 @@ Two new capabilities will be introduced: ### Widget Client Implementation -This has the following behavioral impact on the widget client implementation: +If a widget is granted the `m.receive.sticky_event` capability, the host client must do the following: - On widget startup, the client will send all sticky events that the widget is allowed to see. -- After capability re-negotiation, when the widget is granted `m.receive.sticky_event`, the client will send all currently sticky events that the widget is allowed to see. +- After capability re-negotiation, when the widget is now granted `m.receive.sticky_event` and was not before, the client will send all currently sticky events that the widget is allowed to see. If the capability `m.send.sticky_event` is granted and the client receives a send event with `sticky_duration_ms` set, the client must send a sticky event as described in [MSC4354](https://github.com/matrix-org/matrix-spec-proposals/pull/4354), using the `sticky_duration_ms`.