Message types

Extension of the parrent document.

You can always refer to the matrix documentation: https://matrix.org/docs/spec/client_server/latest#m-room-message-msgtypes

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.

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)

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.

m.text

This message is the most basic message and is used to represent text.

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.

Example:

{
    "content": {
        "body": "This is an example text message",
        "format": "org.matrix.custom.html",
        "formatted_body": "<b>This is an example text message</b>",
        "msgtype": "m.text"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

m.emote

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.

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.

Example:

{
    "content": {
        "body": "thinks this is an example emote",
        "format": "org.matrix.custom.html",
        "formatted_body": "thinks <b>this</b> is an example emote",
        "msgtype": "m.emote"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

m.notice

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.

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.

Example:

{
    "content": {
        "body": "This is an example notice",
        "format": "org.matrix.custom.html",
        "formatted_body": "This is an <strong>example</strong> notice",
        "msgtype": "m.notice"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

m.image

This message represents a single image and an optional thumbnail.

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.

Example:

{
    "content": {
        "body": "filename.jpg",
        "info": {
            "h": 398,
            "mimetype": "image/jpeg",
            "size": 31037,
            "w": 394
        },
        "msgtype": "m.image",
        "url": "mxc://example.org/JWEIFJgwEIhweiWJE"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

m.file

This message represents a generic file.

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.

Example:

{
    "content": {
        "body": "something-important.doc",
        "filename": "something-important.doc",
        "info": {
            "mimetype": "application/msword",
            "size": 46144
        },
        "msgtype": "m.file",
        "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

m.audio

This message represents a single audio clip.

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.

Example:

{
    "content": {
        "body": "Bee Gees - Stayin' Alive",
        "info": {
            "duration": 2140786,
            "mimetype": "audio/mpeg",
            "size": 1563685
        },
        "msgtype": "m.audio",
        "url": "mxc://example.org/ffed755USFFxlgbQYZGtryd"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

m.location

This message represents a real-world location.

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.

Example:

{
    "content": {
        "body": "Big Ben, London, UK",
        "geo_uri": "geo:51.5008,0.1247",
        "info": {
            "thumbnail_info": {
                "h": 300,
                "mimetype": "image/jpeg",
                "size": 46144,
                "w": 300
            },
            "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
        },
        "msgtype": "m.location"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}

m.video

This message represents a single video clip.

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.

Example:

{
    "content": {
        "body": "Gangnam Style",
        "info": {
            "duration": 2140786,
            "h": 320,
            "mimetype": "video/mp4",
            "size": 1563685,
            "thumbnail_info": {
                "h": 300,
                "mimetype": "image/jpeg",
                "size": 46144,
                "w": 300
            },
            "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
            "w": 480
        },
        "msgtype": "m.video",
        "url": "mxc://example.org/a526eYUSFFxlgbQYZmo442"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
        "age": 1234
    }
}