Expand description
Types for extensible text message events (MSC1767).
§Extensible events
MSC1767 defines a new structure for events that is made of two parts: a type and zero or more reusable content blocks.
This allows to construct new event types from a list of known content blocks that allows in turn clients to be able to render unknown event types by using the known content blocks as a fallback. When a new type is defined, all the content blocks it can or must contain are defined too.
There are also some content blocks called “mixins” that can apply to any event when they are defined.
§MSCs
This is a list of MSCs defining the extensible events and deprecating the corresponding legacy
types. Note that “primary type” means the type
field at the root of the event and “message
type” means the msgtype
field in the content of the m.room.message
primary type.
- MSC1767: Text messages, where the
m.message
primary type replaces them.text
message type. - MSC3954: Emotes, where the
m.emote
primary type replaces them.emote
message type. - MSC3955: Automated events, where the
m.automated
mixin replaces them.notice
message type. - MSC3956: Encrypted events, where the
m.encrypted
primary type replaces them.room.encrypted
primary type. - MSC3551: Files, where the
m.file
primary type replaces them.file
message type. - MSC3552: Images and Stickers, where the
m.image
primary type replaces them.image
message type and them.sticker
primary type. - MSC3553: Videos, where the
m.video
primary type replaces them.video
message type. - MSC3927: Audio, where the
m.audio
primary type replaces them.audio
message type. - MSC3488: Location, where the
m.location
primary type replaces them.location
message type.
There are also the following MSCs that introduce new features with extensible events:
§How to use them in Matrix
The extensible events types are meant to be used separately than the legacy types. As such, their use is reserved for room versions that support it.
Currently no stable room version supports extensible events so they can only be sent with unstable room versions that support them.
An exception is made for some new extensible events types that don’t have a legacy type. They can be used with stable room versions without support for extensible types, but they might be ignored by clients that have no support for extensible events. The types that support this must advertise it in their MSC.
Note that if a room version supports extensible events, it doesn’t support the legacy types anymore and those should be ignored. There is not yet a definition of the deprecated legacy types in extensible events rooms.
§How to use them in Ruma
First, you can enable the unstable-extensible-events
feature from the ruma
crate, that
will enable all the MSCs for the extensible events that correspond to the legacy types. It
is also possible to enable only the MSCs you want with the unstable-mscXXXX
features (where
XXXX
is the number of the MSC). When enabling an MSC, all MSC dependencies are enabled at the
same time to avoid issues.
Currently the extensible events use the unstable prefixes as defined in the corresponding MSCs.
Structs§
- The payload for an extensible text message.
- Form of
MessageEventContent
without relation. - Redacted form of
MessageEventContent
- A block for text content with optional markup.
- Text content with optional markup.
Type Aliases§
- An
org.matrix.msc1767.message
event. - An
org.matrix.msc1767.message
event. - An
org.matrix.msc1767.message
event from async_events
response. - An
org.matrix.msc1767.message
event that has been redacted. - An
org.matrix.msc1767.message
event from async_events
response that has been redacted. - An
org.matrix.msc1767.message
event from async_events
response.