From 99366b90adad9dfb14e0f5a88e7d05a04dc2682b Mon Sep 17 00:00:00 2001 From: Timo Date: Thu, 10 Jul 2025 16:43:26 +0200 Subject: [PATCH 1/4] Initial draft --- .../XXXX-matrixRTC-call-decline-realtions.svg | 180 ++++++++++++++++++ proposals/XXXX-matrixRTC-call-decline.md | 107 +++++++++++ 2 files changed, 287 insertions(+) create mode 100644 proposals/XXXX-matrixRTC-call-decline-realtions.svg create mode 100644 proposals/XXXX-matrixRTC-call-decline.md diff --git a/proposals/XXXX-matrixRTC-call-decline-realtions.svg b/proposals/XXXX-matrixRTC-call-decline-realtions.svg new file mode 100644 index 00000000000..91c147e0a29 --- /dev/null +++ b/proposals/XXXX-matrixRTC-call-decline-realtions.svg @@ -0,0 +1,180 @@ + + + + + + + + + + + + + + + m.rtc.member + m.call.notify{ "notify_type": "ring" "m.relates_to": { "rel_type": "m.call.notification", "event_id": "$state_event_id", } ...} + m.call.notify{ "notify_type": "decline" "m.relates_to": { "rel_type": "m.call.notification", "event_id": "$initial_ring_event_id", } ...} + + + + + + diff --git a/proposals/XXXX-matrixRTC-call-decline.md b/proposals/XXXX-matrixRTC-call-decline.md new file mode 100644 index 00000000000..4552192bb0c --- /dev/null +++ b/proposals/XXXX-matrixRTC-call-decline.md @@ -0,0 +1,107 @@ +# MSXXXX: MatrixRTC decline `m.rtc.notify` + +MatrixRTC is the base layer that defines how devices participate in a call. For the specific +usecase of a voice/video call we need additional signalling (outside of MatrixRTC) to provide +the expected user experience. + +It is important to understand that this (and related) proposals intentionally detangle rtc specific +signalling and general purpose MatrixRTC session state. + +## Context + +This proposal builds on the concept of [MSC4075: MatrixRTC Call Ringing](https://github.com/matrix-org/matrix-spec-proposals/pull/4075) +introducint the `m.call.notify` event. +This event lives in parallel with the MatrixRTC session and uses intentional mentions to make the receiving clients ring. +The receiving clients will then monitor the room state and stop ringing once the user joined with one of their devices. + +## Proposal + +Conceptually this MSC will introduce a new event that will be sent as a relation to the `m.call.notify` event +which communicates a decline from one or more parties. It can be used on the clients to provide a good UX around +a call decline (stop ringing, play a decline sound, prompt the user with: "the call has been declined" ...) + +### Introduction + +While the concept of this proposal is simple it is important to outline what needs to be achievable with +the proposed solution. + +- A client needs to easily react to such an event and needs to be able to **correlate the decline** with a + `m.call.notify` event and best case even the **MatrixRTC session** to check if the declien is relevant. +- It needs to be **flexible for 1:1 calls and group calls**. It should be possible to design a group ring + and per group participant decline flow with this proposal even if some products might not need this feature. +- Clients have two possible ways of displaying **historic calls in the timeline**. They can compute the exact call + history using the `m.rtc.member` events which contain the information at what time, which device joined. + Alternatively they can use the notify and decline events only to render when a person tried to start a call + and if that got declined. This is much simpler and therefore desired for very simple client implementations. + +### Proposal (Changes) + +This MSC Proposes to extend the `m.call.notify` event with two more properties and a new `notify_type` : + +- relation: `"m.relates_to": {"rel_type":"m.decline", "eventId":"$call_notify_event_id"}` +- reason: + + ```json + "decline_reason"?: "decline description" + ``` + +- decline type: `notify_type: "decline" | "ring" | "notify"` + +The `m.relates_to` field allows to reference the original notify event. The optional reason +allows to provide a message to the user receiving the decline. +the `notify_type` from the `m.call.notify` event gets a new case. The decline case. + +This results in a tree of notify events on `m.rtc.member` events. + +matrixRTC-call-decline-relations + +Fetching the `m.rtc.member` events to compute a timeline item summarizing the call allows to easily get all the +related elements and provide additional context in the timeline tile. If a call was declined, who (can be multiple) started +the call by ringing others ... + +## Potential issues + +Since this is reusing the `m.call.notify` event type which did not have this usecase in mind, +the event type name might be a bit off: +Instead of calling it`m.call.notify`, `m.call.signalling` might be more approprita. + +### Alternatives + +There are other formats in which the decline relation could be formatted: + +#### Reaction + +Use already existing reactions to the notify event. This makes it extremely trivial to implement: + +- Pros ✅ + - All clients already have support. + - The timeline rendering already has access to the reaction and can incorporate this into the custom tile rendering. +- Cons ❌ + - Feels hacky + - Will be unencrypted as reactions + - Does not allow for more custom fields (decline call later, decline ooo, decline in meeting) + - Might collide with already existing reaction logic in clients + - Hard to include into an rtc member based timeline rendering + +#### Custom Event + +Introduce a new custom event and a new reaction type. +This custom event will be sent as a reaction to the initial notify event: + +- Pros ✅ + - clear separation and usecase +- Cons ❌ + - new event needs new widget permissions and more event types introduced in js-sdk and rust sdk + +## Security considerations + +Relations are unencrypted and the custom relation type will leak metadata about call notify and deline events. + +## Unstable prefix + +While this is an open proposal the prefix `org.matrix.mscXXXX.decline` needs to be used for the new relation type +(and the `m.call.notify` event type will use the `org.matrix.msc4075.call.notify` prefixed version as described in [MSC4075](https://github.com/matrix-org/matrix-spec-proposals/pull/4075)) + +## Dependencies + +This MSC builds on [MSC4075](https://github.com/matrix-org/matrix-spec-proposals/pull/4075) \ No newline at end of file From 11f77f93ae5e996ee764921d94e614150c2c8752 Mon Sep 17 00:00:00 2001 From: Timo Date: Thu, 10 Jul 2025 16:44:18 +0200 Subject: [PATCH 2/4] update msc number --- ...-realtions.svg => 4310-matrixRTC-call-decline-realtions.svg} | 0 ...matrixRTC-call-decline.md => 4310-matrixRTC-call-decline.md} | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename proposals/{XXXX-matrixRTC-call-decline-realtions.svg => 4310-matrixRTC-call-decline-realtions.svg} (100%) rename proposals/{XXXX-matrixRTC-call-decline.md => 4310-matrixRTC-call-decline.md} (99%) diff --git a/proposals/XXXX-matrixRTC-call-decline-realtions.svg b/proposals/4310-matrixRTC-call-decline-realtions.svg similarity index 100% rename from proposals/XXXX-matrixRTC-call-decline-realtions.svg rename to proposals/4310-matrixRTC-call-decline-realtions.svg diff --git a/proposals/XXXX-matrixRTC-call-decline.md b/proposals/4310-matrixRTC-call-decline.md similarity index 99% rename from proposals/XXXX-matrixRTC-call-decline.md rename to proposals/4310-matrixRTC-call-decline.md index 4552192bb0c..7f575c3c675 100644 --- a/proposals/XXXX-matrixRTC-call-decline.md +++ b/proposals/4310-matrixRTC-call-decline.md @@ -1,4 +1,4 @@ -# MSXXXX: MatrixRTC decline `m.rtc.notify` +# MSC4310: MatrixRTC decline `m.rtc.notify` MatrixRTC is the base layer that defines how devices participate in a call. For the specific usecase of a voice/video call we need additional signalling (outside of MatrixRTC) to provide From 68a75ab82827edd7e6c35fb2d8b19a5e7b689139 Mon Sep 17 00:00:00 2001 From: Timo Date: Tue, 15 Jul 2025 12:18:03 +0200 Subject: [PATCH 3/4] fix image link --- proposals/4310-matrixRTC-call-decline.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/4310-matrixRTC-call-decline.md b/proposals/4310-matrixRTC-call-decline.md index 7f575c3c675..4d0dfc88134 100644 --- a/proposals/4310-matrixRTC-call-decline.md +++ b/proposals/4310-matrixRTC-call-decline.md @@ -1,4 +1,4 @@ -# MSC4310: MatrixRTC decline `m.rtc.notify` +# MSC4310: MatrixRTC decline `m.call.notify` MatrixRTC is the base layer that defines how devices participate in a call. For the specific usecase of a voice/video call we need additional signalling (outside of MatrixRTC) to provide @@ -16,7 +16,7 @@ The receiving clients will then monitor the room state and stop ringing once the ## Proposal -Conceptually this MSC will introduce a new event that will be sent as a relation to the `m.call.notify` event +Conceptually this MSC will introduce a new notify type, that will be sent as a relation to the `m.call.notify` event which communicates a decline from one or more parties. It can be used on the clients to provide a good UX around a call decline (stop ringing, play a decline sound, prompt the user with: "the call has been declined" ...) @@ -53,7 +53,7 @@ the `notify_type` from the `m.call.notify` event gets a new case. The decline ca This results in a tree of notify events on `m.rtc.member` events. -matrixRTC-call-decline-relations +matrixRTC-call-decline-relations Fetching the `m.rtc.member` events to compute a timeline item summarizing the call allows to easily get all the related elements and provide additional context in the timeline tile. If a call was declined, who (can be multiple) started From a2d86366b7ad5e61f884fa762ac44985f2d5521b Mon Sep 17 00:00:00 2001 From: Timo Date: Tue, 15 Jul 2025 14:18:47 +0200 Subject: [PATCH 4/4] adapt msc to updates on m.rtc.noticiation msc (MSC4075) --- proposals/4310-matrixRTC-call-decline.md | 26 +++++++++++++----------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/proposals/4310-matrixRTC-call-decline.md b/proposals/4310-matrixRTC-call-decline.md index 4d0dfc88134..a7c9956753b 100644 --- a/proposals/4310-matrixRTC-call-decline.md +++ b/proposals/4310-matrixRTC-call-decline.md @@ -1,4 +1,4 @@ -# MSC4310: MatrixRTC decline `m.call.notify` +# MSC4310: MatrixRTC decline `m.rtc.notification` MatrixRTC is the base layer that defines how devices participate in a call. For the specific usecase of a voice/video call we need additional signalling (outside of MatrixRTC) to provide @@ -10,13 +10,13 @@ signalling and general purpose MatrixRTC session state. ## Context This proposal builds on the concept of [MSC4075: MatrixRTC Call Ringing](https://github.com/matrix-org/matrix-spec-proposals/pull/4075) -introducint the `m.call.notify` event. +introducint the `m.rtc.notification` event. This event lives in parallel with the MatrixRTC session and uses intentional mentions to make the receiving clients ring. The receiving clients will then monitor the room state and stop ringing once the user joined with one of their devices. ## Proposal -Conceptually this MSC will introduce a new notify type, that will be sent as a relation to the `m.call.notify` event +Conceptually this MSC will introduce a new notify type, that will be sent as a relation to the `m.rtc.notification` event which communicates a decline from one or more parties. It can be used on the clients to provide a good UX around a call decline (stop ringing, play a decline sound, prompt the user with: "the call has been declined" ...) @@ -26,7 +26,7 @@ While the concept of this proposal is simple it is important to outline what nee the proposed solution. - A client needs to easily react to such an event and needs to be able to **correlate the decline** with a - `m.call.notify` event and best case even the **MatrixRTC session** to check if the declien is relevant. + `m.rtc.notification` event and best case even the **MatrixRTC session** to check if the declien is relevant. - It needs to be **flexible for 1:1 calls and group calls**. It should be possible to design a group ring and per group participant decline flow with this proposal even if some products might not need this feature. - Clients have two possible ways of displaying **historic calls in the timeline**. They can compute the exact call @@ -36,20 +36,21 @@ the proposed solution. ### Proposal (Changes) -This MSC Proposes to extend the `m.call.notify` event with two more properties and a new `notify_type` : +This MSC Proposes to extend the `m.rtc.notification` with a new `notification_type`, a new relation and a new `decline_reason` +field. -- relation: `"m.relates_to": {"rel_type":"m.decline", "eventId":"$call_notify_event_id"}` +- relation: `"m.relates_to": {"rel_type":"m.rtc.decline", "eventId":"$call_notify_event_id"}` - reason: ```json "decline_reason"?: "decline description" ``` -- decline type: `notify_type: "decline" | "ring" | "notify"` +- decline type: `notification_type: "decline" | "ring" | "notify"` The `m.relates_to` field allows to reference the original notify event. The optional reason allows to provide a message to the user receiving the decline. -the `notify_type` from the `m.call.notify` event gets a new case. The decline case. +the `notification_type` from the `m.rtc.notification` event gets a new case. The decline case. This results in a tree of notify events on `m.rtc.member` events. @@ -61,9 +62,9 @@ the call by ringing others ... ## Potential issues -Since this is reusing the `m.call.notify` event type which did not have this usecase in mind, +Since this is reusing the `m.rtc.notification` event type which did not have this usecase in mind, the event type name might be a bit off: -Instead of calling it`m.call.notify`, `m.call.signalling` might be more approprita. +Instead of calling it`m.rtc.notification`, `m.rtc.signalling` might be more approprita. ### Alternatives @@ -99,8 +100,9 @@ Relations are unencrypted and the custom relation type will leak metadata about ## Unstable prefix -While this is an open proposal the prefix `org.matrix.mscXXXX.decline` needs to be used for the new relation type -(and the `m.call.notify` event type will use the `org.matrix.msc4075.call.notify` prefixed version as described in [MSC4075](https://github.com/matrix-org/matrix-spec-proposals/pull/4075)) +While this is an open proposal the prefix `org.matrix.msc4310.rtc.decline` needs to be used for the new relation type +(and the `m.rtc.notification` event type will use the `org.matrix.msc4075.rtc.notification` prefixed version +as described in [MSC4075](https://github.com/matrix-org/matrix-spec-proposals/pull/4075)) ## Dependencies