Matrix Events Reference

How Matrix Events Work

Every event in Matrix is a JSON object with a common envelope:

{
  "type": "m.room.message",
  "event_id": "$143273582443PhrSn:example.org",
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@alice:example.org",
  "origin_server_ts": 1432735824653,
  "content": { ... },
  "unsigned": { "age": 1234 }
}

State events additionally have a state_key field and represent persistent room configuration (name, topic, membership, power levels, etc.). The same (type, state_key) pair is overwritten rather than appended.

Message events (no state_key) represent transient activity: messages sent, reactions, redactions, stickers, calls.

Ephemeral events are not persisted and are delivered via /sync only (typing indicators, read receipts, presence).

The type field determines what kind of event it is. For m.room.message events, the content.msgtype sub-field further specifies the message type (text, image, file, etc.).

Application Service Transaction Format

An appservice receives events as HTTP PUT requests to /_matrix/app/v1/transactions/{txnId} with a body like:

{
  "events": [ ... array of event objects ... ]
}

Table of Contents

• Room State Events

  • m.room.avatar
  • m.room.canonical_alias
  • m.room.create
  • m.room.encryption
  • m.room.guest_access
  • m.room.history_visibility
  • m.room.join_rules
  • m.room.member
  • m.room.name
  • m.room.pinned_events
  • m.room.policy
  • m.room.power_levels
  • m.room.server_acl
  • m.room.third_party_invite
  • m.room.tombstone
  • m.room.topic

• Room Message Events

  • m.reaction
  • m.room.message
    • m.audio
    • m.emote
    • m.file
    • m.image
    • m.key.verification.request
    • m.location
    • m.notice
    • m.server_notice
    • m.text
    • m.video
  • m.room.redaction
  • m.sticker

• Ephemeral Events

  • m.presence
  • m.receipt
  • m.typing

• Space Events

  • m.space.child
  • m.space.parent

• VoIP Events

  • m.call.answer
  • m.call.candidates
  • m.call.hangup
  • m.call.invite
  • m.call.negotiate
  • m.call.reject
  • m.call.sdp_stream_metadata_changed
  • m.call.select_answer

• Moderation Policy Events

  • m.policy.rule.room
  • m.policy.rule.server
  • m.policy.rule.user

• Account Data & Other Events

  • m.accepted_terms
  • m.direct
  • m.fully_read
  • m.identity_server
  • m.ignored_user_list
  • m.invite_permission_config
  • m.marked_unread
  • m.push_rules
  • m.recent_emoji
  • m.room.encrypted
  • m.tag

• Key Verification Events

  • m.key.verification.accept
  • m.key.verification.cancel
  • m.key.verification.done
  • m.key.verification.key
  • m.key.verification.m.relates_to
  • m.key.verification.mac
  • m.key.verification.ready
  • m.key.verification.request
  • m.key.verification.start
    • m.reciprocate.v1
    • m.sas.v1

• E2E & Key Management Events

  • m.dummy
  • m.forwarded_room_key
  • m.key_backup
  • m.room_key
  • m.room_key.withheld
  • m.room_key_request
  • m.secret.request
  • m.secret.send

Event Type Reference

Room State Events

m.room.avatar

A picture that is associated with the room. This can be displayed alongside the room information.

• Kind: State event

Content Fields

{
  "type": "m.room.avatar",
  "state_key": "",
  "content": {
    "info": {
      "h": 398,
      "w": 394,
      "mimetype": "image/jpeg",
      "size": 31037
    },
    "url": "mxc://example.org/JWEIFJgwEIhweiWJE"
  }
}

m.room.canonical_alias

This event is used to inform the room about which alias should be considered the canonical one, and which other aliases point to the room. This could be for display purposes or as suggestion to users which alias to use to advertise and access the room.

• Kind: State event

Content Fields

{
  "type": "m.room.canonical_alias",
  "state_key": "",
  "content": {
    "alias": "#somewhere:localhost",
    "alt_aliases": [
      "#somewhere:example.org",
      "#myroom:example.com"
    ]
  }
}

m.room.create

This is the first event in a room and cannot be changed. It acts as the root of all other events.

• Kind: State event

Content Fields

{
  "type": "m.room.create",
  "state_key": "",
  "content": {
    "room_version": "11",
    "m.federate": true,
    "predecessor": {
      "event_id": "$something:example.org",
      "room_id": "!oldroom:example.org"
    }
  }
}

m.room.encryption

Defines how messages sent in this room should be encrypted.

• Kind: State event

Content Fields

{
  "type": "m.room.encryption",
  "state_key": "",
  "content": {
    "algorithm": "m.megolm.v1.aes-sha2",
    "rotation_period_ms": 604800000,
    "rotation_period_msgs": 100
  }
}

m.room.guest_access

This event controls whether guest users are allowed to join rooms. If this event is absent, servers should act as if it is present and has the guest_access value "forbidden".

• Kind: State event

Content Fields

{
  "type": "m.room.guest_access",
  "state_key": "",
  "content": {
    "guest_access": "can_join"
  }
}

m.room.history_visibility

This event controls whether a user can see the events that happened in a room from before they joined.

• Kind: State event

Content Fields

{
  "type": "m.room.history_visibility",
  "state_key": "",
  "content": {
    "history_visibility": "shared"
  }
}

m.room.join_rules

A room may have one of the following designations:

• public - anyone can join the room without any prior action.
• invite - a user must first receive an invite from someone already in the room in order to join.
• knock - a user can request an invite to the room. They can be allowed (invited) or denied (kicked/banned) access. Otherwise, users need to be invited in. Only available in rooms which support knocking.
• restricted - anyone able to satisfy at least one of the allow conditions is able to join the room without prior action. Otherwise, an invite is required. Only available in rooms which support the join rule.
• knock_restricted - a user can request an invite using the same functions offered by the knock join rule, or can attempt to join having satisfied an allow condition per the restricted join rule. Only available in rooms which support the join rule.
• private - reserved without implementation. No significant meaning.

• Kind: State event

Content Fields

{
  "type": "m.room.join_rules",
  "state_key": "",
  "content": {
    "join_rule": "public"
  }
}

m.room.member

Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (/rooms/<room id>/invite etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.

The following membership states are specified:

• invite - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.
• join - The user has joined the room (possibly after accepting an invite), and may participate in it.
• leave - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).
• ban - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than ban).
• knock - The user has knocked on the room, requesting permission to participate. They may not participate in the room until they join.

The third_party_invite property will be set if this invite is an invite event and is the successor of an m.room.third_party_invite event, and absent otherwise.

This event may also include an invite_room_state key inside the event's unsigned data. If present, this contains an array of stripped state events to assist the receiver in identifying the room.

The user for which a membership applies is represented by the state_key. Under some conditions, the sender and state_key may not match - this may be interpreted as the sender affecting the membership state of the state_key user.

The membership for a given user can change over time. The table below represents the various changes over time and how clients and servers must interpret those changes. Previous membership can be retrieved from the prev_content object on an event. If not present, the user's previous membership must be assumed as leave.

• Kind: State event

Content Fields

{
  "state_key": "@alice:example.org",
  "sender": "@alice:example.org",
  "type": "m.room.member",
  "content": {
    "membership": "join",
    "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
    "displayname": "Alice Margatroid",
    "reason": "Looking for support"
  }
}

m.room.name

A room has an opaque room ID which is not human-friendly to read. A room alias is human-friendly, but not all rooms have room aliases. The room name is a human-friendly string designed to be displayed to the end-user. The room name is not unique, as multiple rooms can have the same room name set.

If a room has an m.room.name event with an absent, null, or empty name field, it should be treated the same as a room with no m.room.name event.

An event of this type is automatically created when creating a room using /createRoom with the name key.

• Kind: State event

Content Fields

{
  "type": "m.room.name",
  "state_key": "",
  "content": {
    "name": "The room name"
  }
}

m.room.pinned_events

This event is used to "pin" particular events in a room for other participants to review later. The order of the pinned events is guaranteed and based upon the order supplied in the event. Clients should be aware that the current user may not be able to see some of the events pinned due to visibility settings in the room. Clients are responsible for determining if a particular event in the pinned list is displayable, and have the option to not display it if it cannot be pinned in the client.

• Kind: State event

Content Fields

{
  "type": "m.room.pinned_events",
  "state_key": "",
  "content": {
    "pinned": [
      "$someevent:example.org"
    ]
  }
}

m.room.policy

A Policy Server configuration. If invalid or not set, the room does not use a Policy Server.

• Kind: State event

Content Fields

{
  "type": "m.room.policy",
  "state_key": "",
  "content": {
    "via": "policy.example.org",
    "public_keys": {
      "ed25519": "6yhHGKhCiXTSEN2ksjV7kX_N6rBQZ3Xb-M7LlC6NS-s"
    }
  }
}

m.room.power_levels

This event specifies the minimum level a user must have in order to perform a certain action. It also specifies the levels of each user in the room.

If a user_id is in the users list, then that user_id has the associated power level. Otherwise they have the default level users_default. If users_default is not supplied, it is assumed to be 0. If the room contains no m.room.power_levels event, the room's creator has a power level of 100, and all other users have a power level of 0.

Except for membership events and redactions, the level required to send a certain event is governed purely by events, state_default and events_default. If an event type is specified in events, then the user must have at least the level specified in order to send that event. If the event type is not supplied, it defaults to events_default for message events and state_default for state events.

If there is no state_default in the m.room.power_levels event, or there is no m.room.power_levels event, the state_default is 50. If there is no events_default in the m.room.power_levels event, or there is no m.room.power_levels event, the events_default is 0.

Membership events are not subject to events, events_default, or state_default. Instead, the power level required to invite a user to the room, kick a user from the room, or ban a user from the room is defined by invite, kick, and ban, respectively. The levels for kick and ban default to 50 if they are not specified in the m.room.power_levels event, or if the room contains no m.room.power_levels event. invite defaults to 0 in either case. Other membership values are handled during event authorization. See the authorization rules in room versions for further details.

For redactions of a user's own events, the required power level is determined by the m.room.redaction event power level, as per events and events_default. The power level required to redact an event sent by another user is additionally governed by redact. The level for redact defaults to 50 if it is not specified in the m.room.power_levels event, or if the room contains no m.room.power_levels event.

Note:

The allowed range for power level values is [-(2**53)+1, (2**53)-1], as required by the Canonical JSON specification.

• Kind: State event

Content Fields

{
  "type": "m.room.power_levels",
  "state_key": "",
  "content": {
    "ban": 50,
    "events": {
      "m.room.name": 100,
      "m.room.power_levels": 100
    },
    "events_default": 0,
    "invite": 50,
    "kick": 50,
    "redact": 50,
    "state_default": 50,
    "users": {
      "@example:localhost": 100
    },
    "users_default": 0,
    "notifications": {
      "room": 20
    }
  }
}

m.room.server_acl

An event to indicate which servers are permitted to participate in the room. Server ACLs may allow or deny groups of hosts. All servers participating in the room, including those that are denied, are expected to uphold the server ACL. Servers that do not uphold the ACLs MUST be added to the denied hosts list in order for the ACLs to remain effective.

The allow and deny lists are lists of glob-style patterns. When comparing against the server ACLs, the suspect server's port number must not be considered. Therefore evil.com, evil.com:8448, and evil.com:1234 would all match rules that apply to evil.com, for example.

The ACLs are applied to servers when they make requests, and are applied in the following order:

1. If there is no m.room.server_acl event in the room state, allow.
2. If the server name is an IP address (v4 or v6) literal, and allow_ip_literals is present and false, deny.
3. If the server name matches an entry in the deny list, deny.
4. If the server name matches an entry in the allow list, allow.
5. Otherwise, deny.

Note: Server ACLs do not restrict the events relative to the room DAG via authorisation rules, but instead act purely at the network layer to determine which servers are allowed to connect and interact with a given room.

Warning: Failing to provide an allow rule of some kind will prevent all servers from participating in the room, including the sender. This renders the room unusable. A common allow rule is [ "*" ] which would still permit the use of the deny list without losing the room.

Warning: All compliant servers must implement server ACLs. However, legacy or noncompliant servers exist which do not uphold ACLs, and these MUST be manually appended to the denied hosts list when setting an ACL to prevent them from leaking events from banned servers into a room. Currently, the only way to determine noncompliant hosts is to check the prev_events of leaked events, therefore detecting servers which are not upholding the ACLs. Server versions can also be used to try to detect hosts that will not uphold the ACLs, although this is not comprehensive. Server ACLs were added in Synapse v0.32.0, although other server implementations and versions exist in the world.

• Kind: State event

Content Fields

{
  "type": "m.room.server_acl",
  "state_key": "",
  "content": {
    "allow_ip_literals": false,
    "allow": [
      "*"
    ],
    "deny": [
      "*.evil.com",
      "evil.com"
    ]
  }
}

m.room.third_party_invite

Acts as an m.room.member invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room.

• Kind: State event

Content Fields

{
  "type": "m.room.third_party_invite",
  "state_key": "pc98",
  "content": {
    "display_name": "Alice Margatroid",
    "key_validity_url": "https://magic.forest/verifykey",
    "public_key": "abc123",
    "public_keys": [
      {
        "public_key": "def456",
        "key_validity_url": "https://magic.forest/verifykey"
      }
    ]
  }
}

m.room.tombstone

A state event signifying that a room has been upgraded to a different room version, and that clients should go there.

• Kind: State event

Content Fields

{
  "type": "m.room.tombstone",
  "state_key": "",
  "content": {
    "body": "This room has been replaced",
    "replacement_room": "!newroom:example.org"
  }
}

m.room.topic

A topic is a short message detailing what is currently being discussed in the room. It can also be used as a way to display extra information about the room, which may not be suitable for the room name. The room topic can also be set when creating a room using /createRoom, either with the topic key or by specifying a full event in initial_state.

If the topic property is absent, null, or empty then the topic is unset. In other words, an empty topic property effectively resets the room to having no topic.

In order to prevent formatting abuse in room topics, clients SHOULD limit the length of topics during both entry and display, for instance, by capping the number of displayed lines. Additionally, clients SHOULD ignore things like headings and enumerations (or format them as regular text).

• Kind: State event

Content Fields

{
  "type": "m.room.topic",
  "state_key": "",
  "content": {
    "m.topic": {
      "m.text": [
        {
          "mimetype": "text/html",
          "body": "An <em>interesting</em> room topic"
        },
        {
          "body": "An interesting room topic"
        }
      ]
    },
    "topic": "An interesting room topic"
  }
}

Room Message Events

m.reaction

Indicates a reaction to a previous event.

Has no defined content properties of its own. Its only purpose is to hold an m.relates_to property.

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.

• Kind: Room message event

Content Fields

{
  "type": "m.reaction",
  "content": {
    "m.relates_to": {
      "rel_type": "m.annotation",
      "event_id": "$some_event_id",
      "key": "👍"
    }
  }
}

m.room.message

This event is used when sending messages in a room. Messages are not limited to be text. The msgtype key outlines the type of message, e.g. text, audio, image, video, etc. The body key is text and MUST be used with every kind of msgtype as a fallback mechanism for when a client cannot render a message. This allows clients to display something even if it is just plain text.

• Kind: Room message event

Content Fields

Message Types (content.msgtype)

m.audio

This message represents a single audio clip.

{
  "type": "m.room.message",
  "content": {
    "body": "Bee Gees - Stayin' Alive",
    "url": "mxc://example.org/ffed755USFFxlgbQYZGtryd",
    "info": {
      "duration": 2140786,
      "size": 1563685,
      "mimetype": "audio/mpeg"
    },
    "msgtype": "m.audio"
  }
}

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.

{
  "type": "m.room.message",
  "content": {
    "body": "thinks this is an example emote",
    "msgtype": "m.emote",
    "format": "org.matrix.custom.html",
    "formatted_body": "thinks <b>this</b> is an example emote"
  }
}

m.file

This message represents a generic file.

{
  "type": "m.room.message",
  "content": {
    "body": "something-important.doc",
    "filename": "something-important.doc",
    "info": {
      "mimetype": "application/msword",
      "size": 46144
    },
    "msgtype": "m.file",
    "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
  }
}

m.image

This message represents a single image and an optional thumbnail.

{
  "type": "m.room.message",
  "content": {
    "body": "filename.jpg",
    "info": {
      "h": 398,
      "w": 394,
      "mimetype": "image/jpeg",
      "size": 31037,
      "is_animated": false
    },
    "url": "mxc://example.org/JWEIFJgwEIhweiWJE",
    "msgtype": "m.image"
  }
}

m.key.verification.request

Requests a key verification in a room. When requesting a key verification using to-device messaging, an event with type m.key.verification.request should be used.

{
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@alice:example.org",
  "type": "m.room.message",
  "unsigned": {
    "age": 1234
  },
  "content": {
    "body": "Alice is requesting to verify your device, but your client does not support verification, so you may need to use a different verification method.",
    "from_device": "AliceDevice2",
    "methods": [
      "m.sas.v1"
    ],
    "to": "@bob:example.org",
    "msgtype": "m.key.verification.request"
  }
}

m.location

This message represents a real-world location.

{
  "type": "m.room.message",
  "content": {
    "body": "Big Ben, London, UK",
    "geo_uri": "geo:51.5008,0.1247",
    "info": {
      "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
      "thumbnail_info": {
        "mimetype": "image/jpeg",
        "size": 46144,
        "w": 300,
        "h": 300
      }
    },
    "msgtype": "m.location"
  }
}

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.

{
  "type": "m.room.message",
  "content": {
    "body": "This is an example notice",
    "msgtype": "m.notice",
    "format": "org.matrix.custom.html",
    "formatted_body": "This is an <strong>example</strong> notice"
  }
}

m.server_notice

Represents a server notice for a user.

{
  "type": "m.room.message",
  "content": {
    "body": "Human-readable message to explain the notice",
    "msgtype": "m.server_notice",
    "server_notice_type": "m.server_notice.usage_limit_reached",
    "admin_contact": "mailto:server.admin@example.org",
    "limit_type": "monthly_active_user"
  }
}

m.text

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

{
  "type": "m.room.message",
  "content": {
    "body": "This is an example text message",
    "msgtype": "m.text",
    "format": "org.matrix.custom.html",
    "formatted_body": "<b>This is an example text message</b>"
  }
}

m.video

This message represents a single video clip.

{
  "type": "m.room.message",
  "content": {
    "body": "Gangnam Style",
    "url": "mxc://example.org/a526eYUSFFxlgbQYZmo442",
    "info": {
      "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
      "thumbnail_info": {
        "mimetype": "image/jpeg",
        "size": 46144,
        "w": 300,
        "h": 300
      },
      "w": 480,
      "h": 320,
      "duration": 2140786,
      "size": 1563685,
      "mimetype": "video/mp4"
    },
    "msgtype": "m.video"
  }
}

m.room.redaction

This event is created by the server to describe which event has been redacted, by whom, and optionally why. The event that has been redacted is specified in the redacts event level key. Redacting an event means that all keys not required by the protocol are stripped off, allowing messages to be hidden or allowing admins to remove offensive or illegal content.

• Kind: Room message event

Content Fields

{
  "type": "m.room.redaction",
  "content": {
    "redacts": "$fukweghifu23:localhost",
    "reason": "Spamming"
  }
}

m.sticker

This message represents a single sticker image.

• Kind: Room message event

Content Fields

{
  "type": "m.sticker",
  "content": {
    "body": "Landing",
    "info": {
      "mimetype": "image/png",
      "thumbnail_info": {
        "mimetype": "image/png",
        "h": 200,
        "w": 140,
        "size": 73602,
        "is_animated": true
      },
      "h": 200,
      "thumbnail_url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP",
      "w": 140,
      "size": 73602
    },
    "url": "mxc://matrix.org/sHhqkFCvSkFwtmvtETOtKnLP"
  }
}

Ephemeral Events

m.presence

Informs the client of a user's presence state change.

• Kind: Basic event

Content Fields

{
  "sender": "@example:localhost",
  "type": "m.presence",
  "content": {
    "avatar_url": "mxc://localhost/wefuiwegh8742w",
    "last_active_ago": 2478593,
    "presence": "online",
    "currently_active": false,
    "status_msg": "Making cupcakes"
  }
}

m.receipt

Informs the client of new receipts.

• Kind: Basic event

Content Fields

{
  "type": "m.receipt",
  "content": {
    "$1435641916114394fHBLK:matrix.org": {
      "m.read": {
        "@erikj:jki.re": {
          "ts": 1436451550453
        }
      },
      "m.read.private": {
        "@self:example.org": {
          "ts": 1661384801651
        }
      }
    }
  }
}

m.typing

Informs the client of the list of users currently typing.

• Kind: Basic event

Content Fields

{
  "type": "m.typing",
  "content": {
    "user_ids": [
      "@alice:matrix.org",
      "@bob:example.com"
    ]
  }
}

Space Events

m.space.child

Defines the relationship of a child room to a space-room. Has no effect in rooms which are not spaces.

• Kind: State event

Content Fields

{
  "type": "m.space.child",
  "state_key": "!roomid:example.org",
  "content": {
    "suggested": true,
    "via": [
      "example.org",
      "other.example.org"
    ],
    "order": "lexicographically_compare_me"
  }
}

m.space.parent

Defines the relationship of a room to a parent space-room.

• Kind: State event

Content Fields

{
  "type": "m.space.parent",
  "state_key": "!parent_roomid:example.org",
  "content": {
    "canonical": true,
    "via": [
      "example.org",
      "other.example.org"
    ]
  }
}

VoIP Events

m.call.answer

This event is sent by the callee when they wish to answer the call.

• Kind: Room message event (VoIP)

Content Fields

{
  "type": "m.call.answer",
  "content": {
    "version": "1",
    "party_id": "67890",
    "call_id": "12345",
    "answer": {
      "type": "answer",
      "sdp": "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
    },
    "sdp_stream_metadata": {
      "271828182845": {
        "purpose": "m.screenshare"
      },
      "314159265358": {
        "purpose": "m.usermedia"
      }
    }
  }
}

m.call.candidates

This event is sent by callers after sending an invite and by the callee after answering. Its purpose is to give the other party additional ICE candidates to try using to communicate.

• Kind: Room message event (VoIP)

Content Fields

{
  "type": "m.call.candidates",
  "content": {
    "version": "1",
    "party_id": "67890",
    "call_id": "12345",
    "candidates": [
      {
        "sdpMid": "audio",
        "sdpMLineIndex": 0,
        "candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0"
      }
    ]
  }
}

m.call.hangup

Sent by either party to signal their termination of the call. This can be sent either once the call has has been established or before to abort the call.

The meanings of the reason field are as follows:

• ice_failed: ICE negotiation has failed and a media connection could not be established.
• ice_timeout: The connection failed after some media was exchanged (as opposed to ice_failed which means no media connection could be established). Note that, in the case of an ICE renegotiation, a client should be sure to send ice_timeout rather than ice_failed if media had previously been received successfully, even if the ICE renegotiation itself failed.
• invite_timeout: The other party did not answer in time.
• user_hangup: Clients must now send this code when the user chooses to end the call, although for backwards compatibility with version 0, a clients should treat an absence of the reason field as user_hangup.
• user_media_failed: The client was unable to start capturing media in such a way that it is unable to continue the call.
• user_busy: The user is busy. Note that this exists primarily for bridging to other networks such as the PSTN. A Matrix client that receives a call whilst already in a call would not generally reject the new call unless the user had specifically chosen to do so.
• unknown_error: Some other failure occurred that meant the client was unable to continue the call rather than the user choosing to end it.

• Kind: Room message event (VoIP)

Content Fields

{
  "type": "m.call.hangup",
  "content": {
    "version": "1",
    "party_id": "67890",
    "call_id": "12345",
    "reason": "user_hangup"
  }
}

m.call.invite

This event is sent by the caller when they wish to establish a call.

• Kind: Room message event (VoIP)

Content Fields

{
  "type": "m.call.invite",
  "content": {
    "version": "1",
    "party_id": "67890",
    "call_id": "12345",
    "lifetime": 60000,
    "offer": {
      "type": "offer",
      "sdp": "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
    },
    "sdp_stream_metadata": {
      "271828182845": {
        "purpose": "m.screenshare"
      },
      "314159265358": {
        "purpose": "m.usermedia"
      }
    }
  }
}

m.call.negotiate

Provides SDP negotiation semantics for media pause, hold/resume, ICE restarts and voice/video call up/downgrading. Clients should implement and honour hold functionality as per WebRTC's recommendation.

If both the invite event and the accepted answer event have version equal to "1", either party may send m.call.negotiate with a description field to offer new SDP to the other party. This event has call_id with the ID of the call and party_id equal to the client's party ID for that call. The caller ignores any negotiate events with party_id + user_id tuple not equal to that of the answer it accepted and the callee ignores any negotiate events with party_id + user_id tuple not equal to that of the caller. Clients should use the party_id field to ignore the remote echo of their own negotiate events.

This has a lifetime field as in m.call.invite, after which the sender of the negotiate event should consider the negotiation failed (timed out) and the recipient should ignore it.

The description field is the same as the offer field in m.call.invite and answer field in m.call.answer and is an RTCSessionDescriptionInit object as per https://www.w3.org/TR/webrtc/#dom-rtcsessiondescriptioninit.

Once an m.call.negotiate event is received, the client must respond with another m.call.negotiate event, with the SDP answer (with "type": "answer") in the description property.

In the m.call.invite and m.call.answer events, the offer and answer fields respectively are objects of type RTCSessionDescriptionInit. Hence the type field, whilst redundant in these events, is included for ease of working with the WebRTC API and is mandatory. Receiving clients should not attempt to validate the type field, but simply pass the object into the WebRTC API.

• Kind: Room message event (VoIP)

Content Fields

{
  "type": "m.call.negotiate",
  "content": {
    "version": "1",
    "party_id": "67890",
    "call_id": "12345",
    "lifetime": 10000,
    "description": {
      "type": "offer",
      "sdp": "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
    },
    "sdp_stream_metadata": {
      "271828182845": {
        "purpose": "m.screenshare"
      },
      "314159265358": {
        "purpose": "m.usermedia"
      }
    }
  }
}

m.call.reject

If the m.call.invite event has version "1", a client wishing to reject the call sends an m.call.reject event. This rejects the call on all devices, but if the calling device sees an answer before the reject, it disregards the reject event and carries on. The reject has a party_id just like an answer, and the caller sends a select_answer for it just like an answer. If another client had already sent an answer and sees the caller select the reject response instead of its answer, it ends the call. If the m.call.invite event has version 0, the callee sends an m.call.hangup event. If the calling user chooses to end the call before setup is complete, the client sends m.call.hangup as previously.

Note that, unlike m.call.hangup, this event has no reason field: the rejection of a call is always implicitly because the user chose not to answer it.

• Kind: Room message event

Content Fields

{
  "type": "m.call.reject",
  "content": {
    "version": "1",
    "party_id": "67890",
    "call_id": "12345"
  }
}

m.call.sdp_stream_metadata_changed

This event is sent by callers when they wish to update a stream's metadata but no negotiation is required.

• Kind: Room message event (VoIP)

Content Fields

{
  "type": "m.call.sdp_stream_metadata_changed",
  "content": {
    "version": "1",
    "call_id": "1414213562373095",
    "party_id": "1732050807568877",
    "sdp_stream_metadata": {
      "2311546231": {
        "purpose": "m.usermedia",
        "audio_muted:": true,
        "video_muted": true
      }
    }
  }
}

m.call.select_answer

This event is sent by the caller's client once it has decided which other client to talk to, by selecting one of multiple possible incoming m.call.answer events. Its selected_party_id field indicates the answer it's chosen. The call_id and party_id of the caller is also included. If the callee's client sees a select_answer for an answer with party ID other than the one it sent, it ends the call and informs the user the call was answered elsewhere. It does not send any events. Media can start flowing before this event is seen or even sent. Clients that implement previous versions of this specification will ignore this event and behave as they did before.

• Kind: Room message event (VoIP)

Content Fields

{
  "type": "m.call.select_answer",
  "content": {
    "version": "1",
    "call_id": "12345",
    "party_id": "67890",
    "selected_party_id": "111213"
  }
}

Moderation Policy Events

m.policy.rule.room

A moderation policy rule which affects room IDs and room aliases.

• Kind: State event

Content Fields

{
  "type": "m.policy.rule.room",
  "state_key": "rule:#*:example.org",
  "content": {
    "entity": "#*:example.org",
    "recommendation": "m.ban",
    "reason": "undesirable content"
  }
}

m.policy.rule.server

A moderation policy rule which affects servers.

• Kind: State event

Content Fields

{
  "type": "m.policy.rule.server",
  "state_key": "rule:*.example.org",
  "content": {
    "entity": "*.example.org",
    "recommendation": "m.ban",
    "reason": "undesirable engagement"
  }
}

m.policy.rule.user

A moderation policy rule which affects users.

• Kind: State event

Content Fields

{
  "type": "m.policy.rule.user",
  "state_key": "rule:@alice*:example.org",
  "content": {
    "entity": "@alice*:example.org",
    "recommendation": "m.ban",
    "reason": "undesirable behaviour"
  }
}

Account Data & Other Events

m.accepted_terms

A list of terms URLs the user has previously accepted. Clients SHOULD use this to avoid presenting the user with terms they have already agreed to.

• Kind: Basic event

Content Fields

{
  "type": "m.accepted_terms",
  "content": {
    "accepted": [
      "https://example.org/somewhere/terms-1.2-en.html",
      "https://example.org/somewhere/privacy-1.2-en.html"
    ]
  }
}

m.direct

A map of which rooms are considered 'direct' rooms for specific users is kept in account_data in an event of type m.direct. The content of this event is an object where the keys are the user IDs and values are lists of room ID strings of the 'direct' rooms for that user ID.

• Kind: Basic event

Content Fields

{
  "type": "m.direct",
  "content": {
    "@bob:example.com": [
      "!abcdefgh:example.com",
      "!hgfedcba:example.com"
    ]
  }
}

m.fully_read

The current location of the user's read marker in a room. This event appears in the user's room account data for the room the marker is applicable for.

• Kind: Basic event

Content Fields

{
  "type": "m.fully_read",
  "content": {
    "event_id": "$someplace:example.org"
  }
}

m.identity_server

Persists the user's preferred identity server, or preference to not use an identity server at all, in the user's account data.

• Kind: Basic event

Content Fields

{
  "type": "m.identity_server",
  "content": {
    "base_url": "https://example.org"
  }
}

m.ignored_user_list

A map of users which are considered ignored is kept in account_data in an event type of m.ignored_user_list.

• Kind: Basic event

Content Fields

{
  "type": "m.ignored_user_list",
  "content": {
    "ignored_users": {
      "@someone:example.org": {}
    }
  }
}

m.invite_permission_config

• Kind: Basic event

{
  "type": "m.invite_permission_config",
  "content": {
    "default_action": "block"
  }
}

m.marked_unread

The current state of the user's unread marker in a room. This event appears in the user's room account data for the room the marker is applicable for.

• Kind: Basic event

Content Fields

{
  "type": "m.marked_unread",
  "content": {
    "unread": true
  }
}

m.push_rules

Describes all push rules for this user.

• Kind: Basic event

Content Fields

{
  "type": "m.push_rules",
  "content": {
    "global": {
      "override": [
        {
          "actions": [],
          "conditions": [],
          "default": true,
          "enabled": false,
          "rule_id": ".m.rule.master"
        },
        {
          "actions": [],
          "conditions": [
            {
              "key": "content.msgtype",
              "kind": "event_match",
              "pattern": "m.notice"
            }
          ],
          "default": true,
          "enabled": true,
          "rule_id": ".m.rule.suppress_notices"
        }
      ],
      "room": [],
      "sender": [],
      "underride": [
        {
          "actions": [
            "notify",
            {
              "set_tweak": "sound",
              "value": "ring"
            },
            {
              "set_tweak": "highlight",
              "value": false
            }
          ],
          "conditions": [
            {
              "key": "type",
              "kind": "event_match",
              "pattern": "m.call.invite"
            }
          ],
          "default": true,
          "enabled": true,
          "rule_id": ".m.rule.call"
        },
        {
          "actions": [
            "notify",
            {
              "set_tweak": "sound",
              "value": "default"
            },
            {
              "set_tweak": "highlight"
            }
          ],
          "conditions": [
            {
              "kind": "event_property_contains",
              "key": "content.m\\.mentions.user_ids",
              "value": "@alice:example.com"
            }
          ],
          "default": true,
          "enabled": true,
          "rule_id": ".m.rule.is_user_mention"
        },
        {
          "actions": [
            "notify",
            {
              "set_tweak": "sound",
              "value": "default"
            },
            {
              "set_tweak": "highlight",
              "value": false
            }
          ],
          "conditions": [
            {
              "kind": "room_member_count",
              "is": "2"
            },
            {
              "kind": "event_match",
              "key": "type",
              "pattern": "m.room.message"
            }
          ],
          "default": true,
          "enabled": true,
          "rule_id": ".m.rule.room_one_to_one"
        },
        {
          "actions": [
            "notify",
            {
              "set_tweak": "sound",
              "value": "default"
            },
            {
              "set_tweak": "highlight",
              "value": false
            }
          ],
          "conditions": [
            {
              "key": "type",
              "kind": "event_match",
              "pattern": "m.room.member"
            },
            {
              "key": "content.membership",
              "kind": "event_match",
              "pattern": "invite"
            },
            {
              "key": "state_key",
              "kind": "event_match",
              "pattern": "@alice:example.com"
            }
          ],
          "default": true,
          "enabled": true,
          "rule_id": ".m.rule.invite_for_me"
        },
        {
          "actions": [
            "notify",
            {
              "set_tweak": "highlight",
              "value": false
            }
          ],
          "conditions": [
            {
              "key": "type",
              "kind": "event_match",
              "pattern": "m.room.member"
            }
          ],
          "default": true,
          "enabled": true,
          "rule_id": ".m.rule.member_event"
        },
        {
          "actions": [
            "notify",
            {
              "set_tweak": "highlight",
              "value": false
            }
          ],
          "conditions": [
            {
              "key": "type",
              "kind": "event_match",
              "pattern": "m.room.message"
            }
          ],
          "default": true,
          "enabled": true,
          "rule_id": ".m.rule.message"
        }
      ]
    }
  }
}

m.recent_emoji

Lets clients maintain a list of recently used emoji.

• Kind: Basic event

Content Fields

{
  "type": "m.recent_emoji",
  "content": {
    "recent_emoji": [
      {
        "emoji": "🤔",
        "total": 19
      },
      {
        "emoji": "👍",
        "total": 7
      },
      {
        "emoji": "😅",
        "total": 84
      }
    ]
  }
}

m.room.encrypted

This event type is used when sending encrypted events. It can be used either within a room (in which case it will have all of the normal properties in Room events), or as a to-device event.

• Kind: Basic event

Content Fields

m.tag

Informs the client of tags on a room.

• Kind: Basic event

Content Fields

{
  "type": "m.tag",
  "content": {
    "tags": {
      "u.work": {
        "order": 0.9
      }
    }
  }
}

Key Verification Events

m.key.verification.accept

Accepts a previously sent m.key.verification.start message.

• Kind: Basic event

Content Fields

{
  "type": "m.key.verification.accept",
  "content": {
    "transaction_id": "S0meUniqueAndOpaqueString",
    "method": "m.sas.v1",
    "key_agreement_protocol": "curve25519",
    "hash": "sha256",
    "message_authentication_code": "hkdf-hmac-sha256.v2",
    "short_authentication_string": [
      "decimal",
      "emoji"
    ],
    "commitment": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
  }
}

m.key.verification.cancel

Cancels a key verification process/request.

• Kind: Basic event

Content Fields

{
  "type": "m.key.verification.cancel",
  "content": {
    "transaction_id": "S0meUniqueAndOpaqueString",
    "code": "m.user",
    "reason": "User rejected the key verification request"
  }
}

m.key.verification.done

Indicates that a verification process/request has completed successfully.

• Kind: Basic event

Content Fields

{
  "type": "m.key.verification.done",
  "content": {
    "transaction_id": "S0meUniqueAndOpaqueString"
  }
}

m.key.verification.key

Sends the ephemeral public key for a device to the partner device.

• Kind: Basic event

Content Fields

{
  "type": "m.key.verification.key",
  "content": {
    "transaction_id": "S0meUniqueAndOpaqueString",
    "key": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
  }
}

m.key.verification.m.relates_to

Required when sent as an in-room message. Indicates the m.key.verification.request that this message is related to. Note that for encrypted messages, this property should be in the unencrypted portion of the event.

• Kind: Basic event

m.key.verification.mac

Sends the MAC of a device's key to the partner device. The MAC is calculated using the method given in message_authentication_code property of the m.key.verification.accept message.

• Kind: Basic event

Content Fields

{
  "type": "m.key.verification.mac",
  "content": {
    "transaction_id": "S0meUniqueAndOpaqueString",
    "keys": "2Wptgo4CwmLo/Y8B8qinxApKaCkBG2fjTWB7AbP5Uy+aIbygsSdLOFzvdDjww8zUVKCmI02eP9xtyJxc/cLiBA",
    "mac": {
      "ed25519:ABCDEF": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
    }
  }
}

m.key.verification.ready

Accepts a key verification request. Sent in response to an m.key.verification.request event.

• Kind: Basic event

Content Fields

{
  "type": "m.key.verification.ready",
  "content": {
    "from_device": "BobDevice1",
    "transaction_id": "S0meUniqueAndOpaqueString",
    "methods": [
      "m.sas.v1"
    ]
  }
}

m.key.verification.request

Requests a key verification using to-device messaging. When requesting a key verification in a room, a m.room.message should be used, with m.key.verification.request as msgtype.

• Kind: Basic event

Content Fields

{
  "type": "m.key.verification.request",
  "content": {
    "from_device": "AliceDevice2",
    "transaction_id": "S0meUniqueAndOpaqueString",
    "methods": [
      "m.sas.v1"
    ],
    "timestamp": 1559598944869
  }
}

m.key.verification.start

Begins a key verification process. Typically sent as a to-device event. The method field determines the type of verification. The fields in the event will differ depending on the method. This definition includes fields that are in common among all variants.

• Kind: Basic event

Content Fields

Message Types (content.msgtype)

m.reciprocate.v1

Begins a key verification process using the m.reciprocate.v1 method, after scanning a QR code.

m.sas.v1

Begins a SAS key verification process using the m.sas.v1 method.

{
  "type": "m.key.verification.start",
  "content": {
    "from_device": "BobDevice1",
    "transaction_id": "S0meUniqueAndOpaqueString",
    "method": "m.sas.v1",
    "key_agreement_protocols": [
      "curve25519"
    ],
    "hashes": [
      "sha256"
    ],
    "message_authentication_codes": [
      "hkdf-hmac-sha256.v2",
      "hkdf-hmac-sha256"
    ],
    "short_authentication_string": [
      "decimal",
      "emoji"
    ]
  }
}

{
  "type": "m.key.verification.start",
  "content": {
    "from_device": "BobDevice1",
    "transaction_id": "S0meUniqueAndOpaqueString",
    "method": "m.sas.v1"
  }
}

E2E & Key Management Events

m.dummy

This event type is used to indicate new Olm sessions for end-to-end encryption. Typically it is encrypted as an m.room.encrypted event, then sent as a to-device event.

The event does not have any content associated with it. The sending client is expected to send a key share request shortly after this message, causing the receiving client to process this m.dummy event as the most recent event and using the keyshare request to set up the session. The keyshare request and m.dummy combination should result in the original sending client receiving keys over the newly established session.

• Kind: Basic event

{
  "content": {},
  "type": "m.dummy"
}

m.forwarded_room_key

This event type is used to forward keys for end-to-end encryption. It is encrypted as an m.room.encrypted event using Olm, then sent as a to-device event.

• Kind: Basic event

Content Fields

{
  "content": {
    "algorithm": "m.megolm.v1.aes-sha2",
    "room_id": "!Cuyf34gef24t:localhost",
    "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
    "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...",
    "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
    "sender_claimed_ed25519_key": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
    "forwarding_curve25519_key_chain": [
      "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
    ]
  },
  "type": "m.forwarded_room_key"
}

m.key_backup

Allows clients to track user preferences about key backup.

• Kind: Basic event

Content Fields

{
  "type": "m.key_backup",
  "content": {
    "enabled": false
  }
}

m.room_key

This event type is used to exchange keys for end-to-end encryption. It is encrypted as an m.room.encrypted event using Olm, then sent as a to-device event.

• Kind: Basic event

Content Fields

{
  "type": "m.room_key",
  "content": {
    "algorithm": "m.megolm.v1.aes-sha2",
    "room_id": "!Cuyf34gef24t:localhost",
    "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
    "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8LlfJL7qNBEY..."
  }
}

m.room_key.withheld

This event type is used to indicate that the sender is not sharing room keys with the recipient. It is sent as a to-device event.

Possible values for code include:

• m.blacklisted: the user/device was blacklisted.
• m.unverified: the user/device was not verified, and the sender is only sharing keys with verified users/devices.
• m.unauthorised: the user/device is not allowed to have the key. For example, this could be sent in response to a key request if the user/device was not in the room when the original message was sent.
• m.unavailable: sent in reply to a key request if the device that the key is requested from does not have the requested key.
• m.no_olm: an olm session could not be established.

In most cases, this event refers to a specific room key. The one exception to this is when the sender is unable to establish an olm session with the recipient. When this happens, multiple sessions will be affected. In order to avoid filling the recipient's device mailbox, the sender should only send one m.room_key.withheld message with no room_id nor session_id set. If the sender retries and fails to create an olm session again in the future, it should not send another m.room_key.withheld message with a code of m.no_olm, unless another olm session was previously established successfully. In response to receiving an m.room_key.withheld message with a code of m.no_olm, the recipient may start an olm session with the sender and send an m.dummy message to notify the sender of the new olm session. The recipient may assume that this m.room_key.withheld message applies to all encrypted room messages sent before it receives the message.

• Kind: Basic event

Content Fields

{
  "type": "m.room_key.withheld",
  "content": {
    "algorithm": "m.megolm.v1.aes-sha2",
    "room_id": "!Cuyf34gef24t:localhost",
    "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
    "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
    "code": "m.unverified",
    "reason": "Device not verified"
  }
}

m.room_key_request

This event type is used to request keys for end-to-end encryption. It is sent as an unencrypted to-device event.

• Kind: Basic event

Content Fields

m.secret.request

Sent by a client to request a secret from another device or to cancel a previous request. It is sent as an unencrypted to-device event.

• Kind: Basic event

Content Fields

{
  "type": "m.secret.request",
  "content": {
    "name": "org.example.some.secret",
    "action": "request",
    "requesting_device_id": "ABCDEFG",
    "request_id": "randomly_generated_id_9573"
  }
}

m.secret.send

Sent by a client to share a secret with another device, in response to an m.secret.request event. It must be encrypted as an m.room.encrypted event using Olm, then sent as a to-device event.

The request_id must match the ID previously given in an m.secret.request event. The recipient must ensure that this event comes from a device that the m.secret.request event was originally sent to, and that the device is a verified device owned by the recipient. This should be done by checking the sender key of the Olm session that the event was sent over.

• Kind: Basic event

Content Fields

{
  "type": "m.secret.send",
  "content": {
    "request_id": "randomly_generated_id_9573",
    "secret": "ThisIsASecretDon'tTellAnyone"
  }
}

Common Content Sub-Objects

These are shared structures that appear inside content across many event types.

m.relates_to

Used to create relationships between events (replies, edits, threads, reactions).

{
  "m.relates_to": {
    "rel_type": "m.annotation",
    "event_id": "$target_event_id",
    "key": "👍"
  }
}

For replies (m.in_reply_to):

{
  "m.relates_to": {
    "m.in_reply_to": {
      "event_id": "$original_event_id"
    }
  }
}

m.mentions

Intentional mentions (added in Matrix v1.7):

{
  "m.mentions": {
    "user_ids": ["@alice:example.org"],
    "room": false
  }
}

Media info Object

Shared by m.image, m.video, m.audio, m.file, and m.sticker content types:

Source: matrix-org/matrix-spec event schemas. Spec version: latest (fetched at generation time).