Skip to content

Commit

Permalink
Latest
Browse files Browse the repository at this point in the history
  • Loading branch information
@hughns
hughns authored Dec 17, 2024
1 parent 545931d commit 04635eb
Showing 1 changed file with 77 additions and 74 deletions.
151 changes: 77 additions & 74 deletions proposals/4075-call-notify-event.md
View file
Original file line number Diff line number Diff line change
@@ -1,80 +1,89 @@
# MSC4075: MatrixRTC Call Ringing

This comment has been minimized.

Sign in to view

Copy link
@toger5

toger5 Dec 17, 2024

I think there are arguments to both. Making this an rtc scoped event or a call scoped events:

  • A notify an also be used for other sessions. or even in an entirely different context where we need ringing. (so it should be a more broad scope) Especially since we allow to specify custom sessions.
  • The clients need to define some kind of UX and wording around the experience of receiving such an event. They will inevitably end up with a call like experience. So giving RTC session implementers the additional friction of: "Is it actually the right thing to use a call ring event here" could be a good thing. It will end up to be displayed like a call to the user and hence maybe not be a good fit anyways for whatever rtc session they want to use it for so it should not give the false impression that this is what devs should use for all rtc sessions.
# MSC4075: MatrixRTC Ringing

It is important that a call initiated on clientA can make targeted clients ring.
It is important that an RTC session initiated on clientA can make targeted clients ring.
This is of interest in 1:1 Rooms/Calls but also in bigger rooms ringing can be desired.

Legacy calls are using room events to negotiate the call.
A client could use the initial steps in the negotiation to also make the phone ring.
The existing "legacy" [1:1 VoIP calling in Matrix](https://spec.matrix.org/v1.11/client-server-api/#voice-over-ip)
uses room events to negotiate the call.
A client can use the initial steps in the negotiation to also make the phone ring.

With MatrixRTC based calls this signalling is done over state events.
Also MatrixRTC enables large group calls which makes it very
With [MSC4143: MatrixRTC](https://github.com/matrix-org/matrix-spec-proposals/pull/4143)
this signalling is done over state events. Furthermore, [MatrixRTC](https://github.com/matrix-org/matrix-spec-proposals/pull/4143)
allows for large group calls (not just 1:1) which makes it very
desirable to have more configurations over the ringing process.

## Proposal

A new event `m.call.notify` is proposed which can be sent by a client that
wants to start a call. This event is added to the push rules for clients which
support calling so they get push notifications. The push rules for intentional
A new event `m.rtc.notify` is proposed which can be sent by a client that
wants to notify others about the existence of an session for an MatrixRTC application.
This event is added to the push rules for clients which
support the application type so they receive push notifications. The push rules for intentional
mentions make sure no unnecessary push notification is sent.

This event contains the following fields including intentional mentions and extensible events.
This event contains the following fields by leveraging intentional mentions.

```json5
{
"type": "m.call.notify",
"content": {
"application": "m.call | m.other_matrix_session_type | ...",
"m.mentions": {"user_ids": [], "room": true | false},
"notify_type": "ring | notification",
"session": {
// session content from the corresponding m.rtc.member event
"application": "m.call | m.other_matrix_session_type | ...",
},
// Application specific data,
// optional fields to disambiguate which session
// this notify event belongs to:

// for application = "m.call":
"call_id": "some_id",
// Extensible events fallback
"m.text": "<@room|@user1, @user2 and @user3>
<notify_type == 'ring' ? 'RingRing!!' : ''> Join the call in this room with a supported client."
}
}
}
```

The fields are defined as follows:

- `m.mentions` optional:\
Has the structure as defined for `m.mentions` in the [Client-Server API](https://spec.matrix.org/v1.11/client-server-api/#definition-mmentions).
- `notify_type` required string:\
The type of notification to send.\
`ring`: The client should ring.\
`notification`: The client should show a notification.
- `session` required object: the `session` content from the corresponding `m.rtc.member` event.

In the following we define **call** as any MatrixRTC session with the
same `"application"` and the same application specific data.
In the case of `"m.call"`, the same `"call_id"`.
same `"session"` contents.

If it does support the event it should not be rendered in the timeline.
(Call timeline elements are done using the `m.call.member` state events.)
### Client behaviour on receiving a `m.rtc.notify` event

But, if the notify conditions (listed below) apply,
the client has to inform the user about the **call** with an appropriate user experience.
For `notify_by == "ring"` some kind of sound is required
On retrieval, the client should not render the event in the timeline.
If the notify conditions (listed below) apply,
the client has to inform the user about the **call** with an appropriate user flow.
For `notify_type == "ring"` some kind of sound is required
(except if overwritten by another client specific setting),
for `notify_by == "notification"` a visual indication is enough.
for `notify_type == "notification"` a visual indication is enough.
This visual indication should be more than an unread indicator
and similar to a notification banner.
This is not enforced by the spec however and ultimately a client choice.

Ringing (or notifying) should happen only if all these conditions apply:
The client should only inform the user if all of the following conditions apply:

- `m.call.notify` content:\
If the user is not part of the `m.mentions` section as defined in
[MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952)
this event can be ignored. (Push notifications are automatically filtered
- `m.rtc.notify` content:\
If the user is *not* listed in the `m.mentions` section as defined in the\
[Client-Server API](https://spec.matrix.org/v1.11/client-server-api/#definition-mmentions),\
the event should be ignored. (Push notifications are automatically filtered
so this only is important for events received via a sync)
- Local notification settings:\
If the room is set to silent, it will never play a ring sound. A `m.call.notify`
event will at most be used to mark the room as unread or update the rooms
If the room is set to silent, the client should never play a ring sound.
In this scenario, a `m.rtc.notify`
event should at most be used to mark the room as unread or update the rooms
"has active **call** icon". (the exact behavior is up to the client)
- Currently playing a ring sound (room timeline):\
If the user already received a ring event for this **call** and is playing
the ring sound any incoming `m.call.notify` for the same **call**
should be ignored. If the user failed to pick up and a new `m.call.notify`
the ring sound any incoming `m.rtc.notify` for the same **call**
should be ignored. If the user failed to pick up and a new `m.rtc.notify`
arrives for the same room the device should ring again.
- Current user is a member of the the **call** (room state):\
None of the devices should ring if they receive a `m.call.notify` if the
rooms state `m.call.member` event of the user contains a membership for
the **call** in the `m.call.notify` event.
None of the devices should ring if they receive a `m.rtc.notify` if the
rooms state `m.rtc.member` event of the user contains a membership for
the **call** in the `m.rtc.notify` event.
This includes stopping the current ring sound if the room state updates so
this condition is true.
- If a notify event is received in "real time":\
Expand All @@ -85,77 +94,72 @@ Ringing (or notifying) should happen only if all these conditions apply:
is allowed. Any client which is not able to receive the event in this period should
not ring to prohibit (annoying/misleading/irrelevant) outdated rings.

Sending a `m.call.notify` should happen only if all of these conditions apply:
### Client behaviour when sending a `m.rtc.notify` event

Sending a `m.rtc.notify` should happen only if all of these conditions apply:

- If the user deliberately wants to send a new notify event
(It is possible to send a `m.call.notify` for an ongoing call if that
(It is possible to send a `m.rtc.notify` for an ongoing call if that
makes sense. Starting a call ahead of time, planning in a small group,
ringing another set of users at a specific time so they don't forget to join.
Ringing one specific user again who missed joining during the first ring.)
- If the user has not yet received a `m.call.notify` for the **call** they want to
- If the user has not yet received a `m.rtc.notify` for the **call** they want to
participate but the other condition applies. (So the obvious case is, that this
is the first user in a new call session).

### Fallback with extensible events

If clients do not support `m.call.notify` events, they will however draw the extensible event fallback.
The exact content is up the the sending client and can contain more detailed instructions on how to get
access to a supporting client. It has to include the `@room` or the mentioned user list and has
to communicate the message that those users are invited to participate in a call.

### Limitations and recommendations

- Encrypted rooms configured as `mentions only` are currently not sending push
notifications for encrypted events. Hence the client would not ring even though
the ring event contains `m.mentions`.
- As a stop gap, it is recommended, that the client sends unencrypted `m.call.notify`
- As a stop gat, it is recommended, that the client sends unencrypted `m.rtc.notify`
events in such rooms.
- As soon as [MSC3996: Encrypted mentions-only rooms](https://github.com/matrix-org/matrix-spec-proposals/pull/3996)
is supported `m.has_mentions` should be used instead of unencrypted call
notify events.
- Ringing a user who you do not have a shared room with is not supported
by this MSC.
- Wanting to ring a user who you do not have a shared room with is not possible.
It might be an undesired capability that your device can be started to ring
by users you have not yet interacted on matrix.
On the other hand this might be desired to mimic what people expect from using
On the other hand this might be desired to mimic what ppl expect from using
the telephone network.
(It should be possible to disable/configure this on the receiving
Entering a matrix userId allows to call someone (Ring their phone).
(It would be possible to disable/configure this on the receiving
device)
- The location to put this information would be the invite event.
This would be an edge case and only required for the specific use case
This would be an edge case and only required for the specific usecase
of being able to ring without a shared DM/Room.
It should be discussed in an additional MSC and is not part of this proposal.

## Alternatives

It could be possible to use the call member room state events to determine a call
### Use call member room state events

It would be possible to use the call member room state events to determine a call
start.
The logic would be as following:
_If we receive an event we check if there are already other members
_If we receive an event we check if are already other members
(call.member events) for the call. In case there is not we make the phone ring._

Pros:

- This would not require any new event.
- The clients can not "forget" to ring the others when they
start a new call, because they would automatically send an event by joining.
- There would be less traffic. With the proposed solution in this MSC, the first
client who joins needs to send a `m.call.notify` event and a `m.call.member`
state event.
- The clients can not "forget" to ring the others about the when they
start a new call. Because they would automatically send an event by joining.
- There would be less traffic. With the proposed solution the first one who joins
needs to send a `m.rtc.notify` event and a `m.rtc.member` state event.

Cons

- All the ringing conditions run on the receiving user. There is no way for the
user who starts the call to decide if it should ring the other participants.
user who start the call to decide if it should ring the other participants.
(Consider a very large room where I want to start a call only for the interested
ones who want to discuss a side project. It would be very annoying if the
initiator could not control how and who is going to be informed about that call.)

- Additionally, it is not as flexible as the proposed separate event.
Which allows an external instance (a meeting organizer bot) to
just ring all the users which are invited to a meeting without needing to
participate in the call with a `m.call.member` event of the call.
- Push notifications would need to be sent for EVERY `m.call.member` state event
participate in the call with a `m.rtc.member` event of the call.
- Push notifications would need to be sent for EVERY `m.rtc.member` state event
update. For each joining and leaving user and for each membership update during
a call (due to a SFU (single forwarding unit) change, changing devices
(could even happen for screen shares if the screen share is implemented as a
Expand All @@ -178,13 +182,13 @@ Cons
## Security considerations

This is another timeline event where any room participant can send a push
notification to others. Since this will make clients ring this has a high
impact on the receiver. However, since ringing has to obey the mute settings, it is
very easy for the targeted users to mitigate unwanted ringing. It can be very
notification to others. Since this will make clients ring this has a higher
effect on the receiver. Since ringing has to obey the mute settings, it is
very easy for the targeted users to mitigate the "attack". It can be very
much compared to spamming a room with "@room" messages.

The default power level for `m.call.notify` is `50` and equivalent to the default
power level required for `m.call.member` state events.
The default power level for `m.rtc.notify` is `50` and equivalent to the default
power level required for `m.rtc.member` state events.

Additional control is provided indirectly with the use of intentional mentions.
Setting `"notifications":{"room":X}` allows to choose `X` for the power required
Expand All @@ -194,9 +198,8 @@ level to ring the whole room.

While this MSC is not present in the spec, clients and widgets should:

- Use `org.matrix.msc4075.` in place of `m.` in all new identifiers of this MSC.
(`m.call.notify`)
- Use `org.matrix.msc4075.call.notify` in place of `m.rtc.notify` as the event type

## Dependencies

This MSC builds on Intentional Mentions [MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952).
This MSC builds on [MSC4143: MatrixRTC](https://github.com/matrix-org/matrix-spec-proposals/pull/4143).

0 comments on commit 04635eb

Please sign in to comment.