Proposal for typed typing notifications
parent
09e50157b4
commit
86071fafad
@ -0,0 +1,137 @@
|
|||||||
|
# MSC3038: Typed Typing Notifications
|
||||||
|
|
||||||
|
Typing notifications in Matrix currently support a single boolean value of typing or not typing. While
|
||||||
|
this works for most use cases (text chat specifically), it is not always applicable when sending more
|
||||||
|
complicated data types like voice messages.
|
||||||
|
|
||||||
|
This MSC extends the existing typing notification structure to support metadata about the event the
|
||||||
|
user is sending. All of the metadata is optional.
|
||||||
|
|
||||||
|
For reference, a typing notification currently looks something like this:
|
||||||
|
|
||||||
|
```json5
|
||||||
|
{
|
||||||
|
"content": {
|
||||||
|
"user_ids": [
|
||||||
|
"@alice:matrix.org",
|
||||||
|
"@bob:example.com"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
|
||||||
|
"type": "m.typing"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Proposal
|
||||||
|
|
||||||
|
A new, optional, `event` field is added to the `PUT` body of
|
||||||
|
[`/rooms/:roomId/typing/:userId`](https://matrix.org/docs/spec/client_server/r0.6.1#put-matrix-client-r0-rooms-roomid-typing-userid)
|
||||||
|
which represents the event the user is working on sending. A new `PUT` body may look like:
|
||||||
|
|
||||||
|
```json5
|
||||||
|
{
|
||||||
|
"typing": true,
|
||||||
|
"timeout": 33038,
|
||||||
|
"event": {
|
||||||
|
"type": "m.room.message",
|
||||||
|
"content": {
|
||||||
|
"msgtype": "m.text"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `event` is a stripped-down version of a real event, indicating the `type` and relevant parts of
|
||||||
|
the `content` to be included. This does technically allow a client to also send partial events such
|
||||||
|
as the event body, however this MSC strongly advises that clients do not send or render that information
|
||||||
|
due to the privacy implications. See the "Security Considerations" section for more information.
|
||||||
|
|
||||||
|
For a `type` of `m.room.message`, The default `content.msgtype` is `m.text`. Similarly, when no
|
||||||
|
`event` information is supplied, the user can be assumed to be sending a `m.text` `m.room.message`
|
||||||
|
event. The server should reject any invalid fields (wrong data types, unexpected locations, etc),
|
||||||
|
though clients are ultimately responsible for parsing the data safely.
|
||||||
|
|
||||||
|
The ephemeral event a client would receive could look something like this:
|
||||||
|
|
||||||
|
```json5
|
||||||
|
{
|
||||||
|
"content": {
|
||||||
|
"user_ids": [
|
||||||
|
"@alice:matrix.org",
|
||||||
|
"@bob:example.com"
|
||||||
|
],
|
||||||
|
"events": {
|
||||||
|
"@alice:matrix.org": {
|
||||||
|
"type": "m.room.message",
|
||||||
|
"content": {
|
||||||
|
"msgtype": "m.voice"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
|
||||||
|
"type": "m.typing"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
In this example, `@alice:matrix.org` is recording a theoretical voice message while `@bob:example.com`
|
||||||
|
is typing a regular text event (the default). If the receiving client doesn't recognize the event
|
||||||
|
Alice is trying to send, for example, then the client would assume that they are sending a regular
|
||||||
|
text event or use generic language like "Alice is sending something...".
|
||||||
|
|
||||||
|
The `events` object is not required. Clients should interpret invalid data (wrong data types, missing
|
||||||
|
fields, etc) as though users are typing text messages. Users who are *not* listed in `user_ids`
|
||||||
|
should not show up in the `events` object, and clients should ignore any updates for users who are
|
||||||
|
not in the `user_ids` array.
|
||||||
|
|
||||||
|
Like with typing notifications currently, a user can send `typing: false` at any time to stop typing.
|
||||||
|
Changing the `event` information being sent replaces any previous state, including removal of `event`
|
||||||
|
from the `PUT` body.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
1. User hits `PUT /typing` with `{"typing": true, "event": {"type": "m.room.message"}}`
|
||||||
|
2. Other users see them as typing a text message.
|
||||||
|
3. The same user hits `PUT /typing` with `{"typing": true, "event": {"type": "org.example.msg"}}` this time.
|
||||||
|
4. Other users see them as typing an `org.example.msg` event.
|
||||||
|
5. The same user once again hits `PUT /typing` with `{"typing": true}`
|
||||||
|
6. Other users now see them as typing a text message again
|
||||||
|
7. Finally, the user sends `{"typing": false}` to clear their typing status for other users.
|
||||||
|
|
||||||
|
## Potential issues
|
||||||
|
|
||||||
|
This MSC is potentially far too generic for what it aims to achieve, which is a "User is recording a
|
||||||
|
voice message..." line in clients. This approach feels suitable for other applications in the future,
|
||||||
|
such as potentially streaming uploads or other lengthy message sending stats (as this approach could
|
||||||
|
send progress information too).
|
||||||
|
|
||||||
|
## Alternatives
|
||||||
|
|
||||||
|
Not really considered at the moment, but there is an option of a whole other `m.recording` EDU and partner
|
||||||
|
API to cover the use case of "show user as recording a voice message". This feels like overkill for such
|
||||||
|
a feature, however.
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
As already mentioned, because the `content` the client sends to `/typing` is sent verbatim over federation
|
||||||
|
it could be a way to expose far more information than the user intended to send, such as their draft of
|
||||||
|
the message they are typing. Clients are strongly discouraged from using this practice, and servers should
|
||||||
|
enforce strong rate limits to help discourage the behaviour. Servers could even optionally reject `body`
|
||||||
|
being included in `content`, for example.
|
||||||
|
|
||||||
|
If a client does decide to render `body` (or `formatted_body`) information from the typing notification,
|
||||||
|
it should consider the security risks associated with using unsafe user input, like HTML injection.
|
||||||
|
|
||||||
|
Clients could also abuse this feature for custom status, presence, or other similar functionality where it
|
||||||
|
might otherwise be disabled/non-functional on their homeserver. Again, servers should use rate limits to
|
||||||
|
avoid this sort of behaviour and room administrators/moderators should consider banning/kicking the users
|
||||||
|
from the room for doing this. Servers could also use pattern-detecting behaviour if appropriate for their
|
||||||
|
deployment to determine if a user is abusing typing notifications (for example, a user is unlikely to be
|
||||||
|
typing a message for 4 solid hours).
|
||||||
|
|
||||||
|
## Unstable prefix
|
||||||
|
|
||||||
|
While this MSC is not considered stable, implementations should use `org.matrix.msc3038.events` in place
|
||||||
|
of `events` - both in the `PUT` body and in the resulting `m.typing` ephemeral event. Note that servers
|
||||||
|
which do not support this functionality will end up ignoring any mention of `events`, thus leaving the
|
||||||
|
user as typing a text message in existing client implementations.
|
Loading…
Reference in New Issue