Users sometimes wish to respond to a message using emojis. When such responses are grouped visually below the message being reacted to, this provides a (visually) light-weight way for users to react to messages.
This proposal was originally part of MSC1849.
As with message edits, support for reactions were landed in the Element clients and Synapse in May 2019, following the proposals of MSC1849 and then presented as being "production-ready", despite them not yet having been adopted into the Matrix specification.
Again as with edits, the current situation is therefore that client or server implementations hoping to interact with Element users must simply follow the examples of that implementation.
To rectify the situation, this MSC therefore seeks primarily to formalise the status quo. Although there is plenty of scope for improvement, we consider that better done in future MSCs, based on a shared understanding of the current implementation.
In short, this MSC prefers fidelity to the current implementations over elegance of design.
On the positive side: this MSC is the last part of the former MSC1849 to be formalised, and is by far the most significant feature implemented by the Element clients which has yet to be specified.
A new event relationship type
with a rel_type of m.annotation.
This relationship type is intended primarily for handling emoji reactions, allowing clients to send an event which annotates an existing event.
Another potential usage of annotations is for bots, which could use them to report the success/failure or progress of a command.
Along with the normal properties event_id and rel_type, the
m.relates_to
property should contains a key that indicates the annotation being
applied. For example, when reacting with emojis, the key contains the emoji
being used.
An event annotating another with the thumbs-up emoji would therefore have the following m.relates_to property:
"m.relates_to": {
"rel_type": "m.annotation",
"event_id": "$some_event_id",
"key": "👍"
}When sending emoji reactions, the key property should include the unicode
emoji presentation
selector
(\uFE0F) for codepoints which allow it (see the emoji variation sequences
list).
Any type of event is eligible for an annotation, including state events.
A new message type m.reaction is proposed to indicate that a user is reacting
to a message. No content properties are defined for this event type: it serves
only to hold a relationship to another event.
For example, an m.reaction event which annotates an existing event with a 👍
looks like:
{
"type": "m.reaction",
"content": {
"m.relates_to": {
"rel_type": "m.annotation",
"event_id": "$some_event_id",
"key": "👍"
}
}
}Since they contain no content other than m.relates_to, m.reaction events
are normally not encrypted, as there would be no benefit in doing so. (However,
see Encrypted reactions below.)
It is not considered valid to send an annotation for a replacement event (i.e., a message edit event): any reactions should refer to the original event. Annotations of replacement events will be ignored according to the rules for counting annotations.
As an aside, note that it is not possible to edit a reaction, since replacement
events do not change m.relates_to (see Applying
m.new_content),
and there is no other meaningful content within m.reaction. If a user wishes
to change their reaction, the original reaction should be redacted and a new
one sent in its place.
The intention of annotations is that they are counted up, rather than being displayed individually.
Clients must keep count of the number of annotations with a given event type
and annotation key they observe for each event; these counts are typically
presented alongside the event in the timeline.
When performing this count:
-
Each event
typeand annotationkeyshould normally be counted separately, though whether to actually do so is an implementation decision. -
Annotation events sent by ignored users should be excluded from the count.
-
Multiple identical annotations (i.e., with the same event
typeand annotationkey) from the same user (i.e., events with the samesender) should be treated as a single annotation. -
It is not considered valid to annotate an event which itself has an
m.relates_towithrel_type: m.annotationorrel_type: m.replace. Implementations should ignore any such annotation events. -
When an annotation is redacted, it is removed from the count.
Since reactions are considered "metadata" that annotate an existing event, they should not by default trigger notifications. Thus a new default override rule is to be added that ignores reaction events:
{
"rule_id": ".m.rule.reaction",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "event_match",
"key": "type",
"pattern": "m.reaction"
}
],
"actions": []
}The rule is added between .m.rule.tombstone and .m.rule.room.server_acl.
(Synapse implementation: base_rules.rs)
Homeservers should prevent users from sending a second annotation for a given
event with identical event type and annotation key (unless the first event
has been redacted).
Attempts to send such an annotation should be rejected with a 400 error and an
error code of M_DUPLICATE_ANNOTATION.
Note that this does not guarantee that duplicate annotations will not arrive over federation. Clients and servers are responsible for deduplicating received annotations when counting annotations.
m.annotation relationships are not aggregated
by the server. In other words, m.annotation is not included in the m.relations property.
matrix-spec#660 discusses the possibility of encrypting message relationships in general.
Given that reactions do not rely on server-side aggregation support, an easier
solution to encrypting reactions might be not to use the relationships
framework at all and instead just use a keys within m.reaction events, which
could then be encrypted. For example, a reaction could instead be formatted as:
{
"type": "m.reaction",
"content": {
"event_id": "$some_event_id",
"key": "👍"
}
}In future it might be useful to be able to annotate events with more information, some examples include:
- Annotate commit/PR notification messages with their associated CI state, e.g. pending/passed/failed.
- If a user issues a command to a bot, e.g.
!deploy-sitethe bot could annotate that event with current state, like "acknowledged", "redeploying...", "success", "failed", etc. - Other use cases...?
However, this doesn't really work with the proposed grouping, as the aggregation key wouldn't contain the right information needed to display it (unlike for reactions).
One way to potentially support this is to include the events (or a subset of the
event) when grouping, so that clients have enough information to render them.
However this dramatically inceases the size of the parent event if we bundle the
full events inside, even if limit the number we bundle in. To reduce the
overhead the annotation event could include a m.result field which gets
included.
This would look something like the following, where the annotation is:
{
"type": "m.bot_command_response",
"content": {
"m.result": {
"state": "success",
},
"m.relates_to": {
"type": "m.annotation",
"key": ""
}
}
}and gets bundled into an event like:
{
"unsigned": {
"m.relations": {
"m.annotation": [
{
"type": "m.bot_command_response",
"key": "",
"count": 1,
"chunk": [
{
"m.result": {
"state": "success",
},
}
],
"limited": false,
}
]
}
}
}This is something that could be added later on. A few issues with this are:
- How does this work with E2EE? How do we encrypt the
m.result? - We would end up including old annotations that had been superseded, should these be done via edits instead?
Clients should render reactions that have a long key field in a sensible
manner. For example, clients can elide overly-long reactions.
If using reactions for upvoting/downvoting purposes we would almost certainly want to anonymise the reactor, at least from other users if not server admins, to avoid retribution problems. This gives an unfair advantage to people who run their own servers however and can cheat and deanonymise (and publish) reactor details. In practice, reactions may not be best used for upvote/downvote as at the unbundled level they are intrinsically private data.
Or in a MSC1228 world... we could let users join the room under an anonymous persona from a big public server in order to vote? However, such anonymous personae would lack any reputation data.