Message types
Extension of the parrent document.
Last updated
Extension of the parrent document.
Last updated
You can always refer to the matrix documentation: https://matrix.org/docs/spec/client_server/latest#m-room-message-msgtypes
Each m.room.message MUST have a msgtype key which identifies the type of message being sent. Each type has their own required and optional keys, as outlined below. If a client cannot display the given msgtype then it SHOULD display the fallback plain text body key instead.
Some message types support HTML in the event content that clients should prefer to display if available. Currently m.text, m.emote, and m.notice support an additional format parameter of org.matrix.custom.html. When this field is present, a formatted_body with the HTML must be provided. The plain text version of the HTML should be provided in the body.
Clients should limit the HTML they render to avoid Cross-Site Scripting, HTML injection, and similar attacks. The strongly suggested set of HTML tags to permit, denying the use and rendering of anything else, is: font, del, h1, h2, h3, h4, h5, h6, blockquote, p, a, ul, ol, sup, sub, li, b, i, u, strong, em, strike, code, hr, br, div, table, thead, tbody, tr, th, td, caption, pre, span, img.
Not all attributes on those tags should be permitted as they may be avenues for other disruption attempts, such as adding onclick handlers or excessively large text. Clients should only permit the attributes listed for the tags below. Where data-mx-bg-color and data-mx-color are listed, clients should translate the value (a 6-character hex color code) to the appropriate CSS/attributes for the tag.
Additionally, web clients should ensure that all a tags get a rel="noopener" to prevent the target page from referencing the client's tab/window.
Tags must not be nested more than 100 levels deep. Clients should only support the subset of tags they can render, falling back to other representations of the tags where possible. For example, a client may not be able to render tables correctly and instead could fall back to rendering tab-delimited text.
In addition to not rendering unsafe HTML, clients should not emit unsafe HTML in events. Likewise, clients should not generate HTML that is not needed, such as extra paragraph tags surrounding text due to Rich Text Editors. HTML included in events should otherwise be valid, such as having appropriate closing tags, appropriate attributes (considering the custom ones defined in this specification), and generally valid structure.
A special tag, mx-reply, may appear on rich replies (described below) and should be allowed if, and only if, the tag appears as the very first tag in the formatted_body. The tag cannot be nested and cannot be located after another tag in the tree. Because the tag contains HTML, an mx-reply is expected to have a partner closing tag and should be treated similar to a div. Clients that support rich replies will end up stripping the tag and its contents and therefore may wish to exclude the tag entirely.
Note
A future iteration of the specification will support more powerful and extensible message formatting options, such as the proposal MSC1225.
This message is the most basic message and is used to represent text.
Example:
This message is similar to m.text except that the sender is 'performing' the action contained in the body key, similar to /me in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular m.text messages.
Example:
The m.notice type is primarily intended for responses from automated clients. An m.notice message must be treated the same way as a regular m.text message with two exceptions. Firstly, clients should present m.notice messages to users in a distinct manner, and secondly, m.notice messages must never be automatically responded to. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages.
Example:
This message represents a single image and an optional thumbnail.
Example:
This message represents a generic file.
Example:
This message represents a single audio clip.
Example:
This message represents a real-world location.
Example:
This message represents a single video clip.
Example:
font:
data-mx-bg-color, data-mx-color
span:
data-mx-bg-color, data-mx-color
a:
name, target, href (provided the value is not relative and has a scheme matching one of: https, http, ftp, mailto, magnet)
img:
width, height, alt, title, src (provided it is a Matrix Content (MXC) URI)
ol:
start
code:
class (only classes which start with language- for syntax highlighting)
Content Key
Type
Description
body
string
Required. The body of the message.
msgtype
enum
Required. Must be 'm.text'.
format
string
The format used in the formatted_body. Currently only org.matrix.custom.html is supported.
formatted_body
string
The formatted version of the body. This is required if format is specified.
Content Key
Type
Description
body
string
Required. The emote action to perform.
msgtype
enum
Required. Must be 'm.emote'.
format
string
The format used in the formatted_body. Currently only org.matrix.custom.html is supported.
formatted_body
string
The formatted version of the body. This is required if format is specified.
Content Key
Type
Description
body
string
Required. The notice text to send.
msgtype
enum
Required. Must be 'm.notice'.
format
string
The format used in the formatted_body. Currently only org.matrix.custom.html is supported.
formatted_body
string
The formatted version of the body. This is required if format is specified.
Content Key
Type
Description
body
string
Required. A textual representation of the image. This could be the alt text of the image, the filename of the image, or some kind of content description for accessibility e.g. 'image attachment'.
info
ImageInfo
Metadata about the image referred to in url.
msgtype
enum
Required. Must be 'm.image'.
url
string
Required if the file is unencrypted. The URL (typically MXC URI) to the image.
file
EncryptedFile
Required if the file is encrypted. Information on the encrypted file, as specified in End-to-end encryption.
ImageInfo
ImageInfo Key
Type
Description
h
integer
The intended display height of the image in pixels. This may differ from the intrinsic dimensions of the image file.
w
integer
The intended display width of the image in pixels. This may differ from the intrinsic dimensions of the image file.
mimetype
string
The mimetype of the image, e.g. image/jpeg.
size
integer
Size of the image in bytes.
thumbnail_url
string
The URL (typically MXC URI) to a thumbnail of the image. Only present if the thumbnail is unencrypted.
thumbnail_file
EncryptedFile
Information on the encrypted thumbnail file, as specified in End-to-end encryption. Only present if the thumbnail is encrypted.
thumbnail_info
ThumbnailInfo
Metadata about the image referred to in thumbnail_url.
ThumbnailInfo
ThumbnailInfo Key
Type
Description
h
integer
The intended display height of the image in pixels. This may differ from the intrinsic dimensions of the image file.
w
integer
The intended display width of the image in pixels. This may differ from the intrinsic dimensions of the image file.
mimetype
string
The mimetype of the image, e.g. image/jpeg.
size
integer
Size of the image in bytes.
Content Key
Type
Description
body
string
Required. A human-readable description of the file. This is recommended to be the filename of the original upload.
filename
string
The original filename of the uploaded file.
info
FileInfo
Information about the file referred to in url.
msgtype
enum
Required. Must be 'm.file'.
url
string
Required if the file is unencrypted. The URL (typically MXC URI) to the file.
file
EncryptedFile
Required if the file is encrypted. Information on the encrypted file, as specified in End-to-end encryption.
FileInfo
FileInfo Key
Type
Description
mimetype
string
The mimetype of the file e.g. application/msword.
size
integer
The size of the file in bytes.
thumbnail_url
string
The URL to the thumbnail of the file. Only present if the thumbnail is unencrypted.
thumbnail_file
EncryptedFile
Information on the encrypted thumbnail file, as specified in End-to-end encryption. Only present if the thumbnail is encrypted.
thumbnail_info
ThumbnailInfo
Metadata about the image referred to in thumbnail_url.
ThumbnailInfo
ThumbnailInfo Key
Type
Description
h
integer
The intended display height of the image in pixels. This may differ from the intrinsic dimensions of the image file.
w
integer
The intended display width of the image in pixels. This may differ from the intrinsic dimensions of the image file.
mimetype
string
The mimetype of the image, e.g. image/jpeg.
size
integer
Size of the image in bytes.
Content Key
Type
Description
body
string
Required. A description of the audio e.g. 'Bee Gees - Stayin' Alive', or some kind of content description for accessibility e.g. 'audio attachment'.
info
AudioInfo
Metadata for the audio clip referred to in url.
msgtype
enum
Required. Must be 'm.audio'.
url
string
Required if the file is unencrypted. The URL (typically MXC URI) to the audio clip.
file
EncryptedFile
Required if the file is encrypted. Information on the encrypted file, as specified in End-to-end encryption.
AudioInfo
AudioInfo Key
Type
Description
duration
integer
The duration of the audio in milliseconds.
mimetype
string
The mimetype of the audio e.g. audio/aac.
size
integer
The size of the audio clip in bytes.
Content Key
Type
Description
body
string
Required. A description of the location e.g. 'Big Ben, London, UK', or some kind of content description for accessibility e.g. 'location attachment'.
geo_uri
string
Required. A geo URI representing this location.
msgtype
enum
Required. Must be 'm.location'.
info
LocationInfo
LocationInfo
LocationInfo Key
Type
Description
thumbnail_url
string
The URL to the thumbnail of the file. Only present if the thumbnail is unencrypted.
thumbnail_file
EncryptedFile
Information on the encrypted thumbnail file, as specified in End-to-end encryption. Only present if the thumbnail is encrypted.
thumbnail_info
ThumbnailInfo
Metadata about the image referred to in thumbnail_url.
ThumbnailInfo
ThumbnailInfo Key
Type
Description
h
integer
The intended display height of the image in pixels. This may differ from the intrinsic dimensions of the image file.
w
integer
The intended display width of the image in pixels. This may differ from the intrinsic dimensions of the image file.
mimetype
string
The mimetype of the image, e.g. image/jpeg.
size
integer
Size of the image in bytes.
Content Key
Type
Description
body
string
Required. A description of the video e.g. 'Gangnam style', or some kind of content description for accessibility e.g. 'video attachment'.
info
VideoInfo
Metadata about the video clip referred to in url.
msgtype
enum
Required. Must be 'm.video'.
url
string
Required if the file is unencrypted. The URL (typically MXC URI) to the video clip.
file
EncryptedFile
Required if the file is encrypted. Information on the encrypted file, as specified in End-to-end encryption.
VideoInfo
VideoInfo Key
Type
Description
duration
integer
The duration of the video in milliseconds.
h
integer
The height of the video in pixels.
w
integer
The width of the video in pixels.
mimetype
string
The mimetype of the video e.g. video/mp4.
size
integer
The size of the video in bytes.
thumbnail_url
string
The URL (typically MXC URI) to an image thumbnail of the video clip. Only present if the thumbnail is unencrypted.
thumbnail_file
EncryptedFile
Information on the encrypted thumbnail file, as specified in End-to-end encryption. Only present if the thumbnail is encrypted.
thumbnail_info
ThumbnailInfo
Metadata about the image referred to in thumbnail_url.
ThumbnailInfo
ThumbnailInfo Key
Type
Description
h
integer
The intended display height of the image in pixels. This may differ from the intrinsic dimensions of the image file.
w
integer
The intended display width of the image in pixels. This may differ from the intrinsic dimensions of the image file.
mimetype
string
The mimetype of the image, e.g. image/jpeg.
size
integer
Size of the image in bytes.