matrix-spec/specification/events.rst

Event Structure
===============

All communication in Matrix is expressed in the form of data objects called
Events. These are the fundamental building blocks common to the client-server,
server-server and application-service APIs, and are described below.

{{common_event_fields}}

{{common_room_event_fields}}

{{common_state_event_fields}}


Differences between /v1 and /v2 events
--------------------------------------

There are a few differences between how events are formatted for sending
between servers over federation and how they are formatted for sending between
a server and its clients.

Additionally there are a few differences between the format of events in the
responses to client APIs with a /v1 prefix and responses APIs with a /v2
prefix.

Events in responses for APIs with the /v2 prefix are generated from an event
formatted for federation by:

* Removing the following keys:
  ``auth_events``, ``prev_events``, ``hashes``, ``signatures``, ``depth``,
  ``origin``, ``prev_state``.
* Adding an ``age`` to the ``unsigned`` object which gives the time in
  milliseconds that has ellapsed since the event was sent.
* Adding a ``prev_content`` to the ``unsigned`` object if the event is
  a ``state event`` which gives previous content of that state key.
* Adding a ``redacted_because`` to the ``unsigned`` object if the event was
  redacted which gives the event that redacted it.
* Adding a ``transaction_id`` if the event was sent by the client requesting it.

Events in responses for APIs with the /v1 prefix are generated from an event
formatted for the /v2 prefix by:

* Moving the folling keys from the ``unsigned`` object to the top level event
  object: ``age``, ``redacted_because``, ``replaces_state``, ``prev_content``.
* Removing the ``unsigned`` object.
* Rename the ``sender`` key to ``user_id``.
* If the event was an ``m.room.member`` with ``membership`` set to ``invite``
  then adding a ``invite_room_state`` key to the top level event object.


Size limits
-----------

The total size of any event MUST NOT exceed 65 KB. There are additional
restrictions on sizes per key:

- ``user_id`` MUST NOT exceed 255 bytes (including domain).
- ``room_id`` MUST NOT exceed 255 bytes.
- ``state_key`` MUST NOT exceed 255 bytes.
- ``type`` MUST NOT exceed 255 bytes.
- ``event_id`` MUST NOT exceed 255 bytes.

Some event types have additional size restrictions which are specified in
the description of the event. Additional keys have no limit other than that
implied by the total 65 KB limit on events.

Room Events
-----------
.. NOTE::
  This section is a work in progress.

This specification outlines several standard event types, all of which are
prefixed with ``m.``

{{m_room_aliases_event}}

{{m_room_canonical_alias_event}}

{{m_room_create_event}}

{{m_room_join_rules_event}}

{{m_room_member_event}}

{{m_room_power_levels_event}}

{{m_room_redaction_event}}