diff --git a/proposals/4310-matrixRTC-call-decline-realtions.svg b/proposals/4310-matrixRTC-call-decline-realtions.svg new file mode 100644 index 00000000000..91c147e0a29 --- /dev/null +++ b/proposals/4310-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/4310-matrixRTC-call-decline.md b/proposals/4310-matrixRTC-call-decline.md new file mode 100644 index 00000000000..a7c9956753b --- /dev/null +++ b/proposals/4310-matrixRTC-call-decline.md @@ -0,0 +1,109 @@ +# 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 +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.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.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" ...) + +### 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.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 + 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.rtc.notification` with a new `notification_type`, a new relation and a new `decline_reason` +field. + +- relation: `"m.relates_to": {"rel_type":"m.rtc.decline", "eventId":"$call_notify_event_id"}` +- reason: + + ```json + "decline_reason"?: "decline description" + ``` + +- 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 `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. + +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.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.rtc.notification`, `m.rtc.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.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 + +This MSC builds on [MSC4075](https://github.com/matrix-org/matrix-spec-proposals/pull/4075) \ No newline at end of file