You're looking at an unstable version of this specification. Unstable specifications may change at any time without notice.

Switch to the current stable release.

Room Version 3

This room version builds on version 2 with an improved event format.

Client considerations

This room version changes the format for event IDs sent to clients. Clients should be aware that these event IDs may contain slashes and other potentially problematic characters. Clients should be treating event IDs as opaque identifiers and should not be attempting to parse them into a usable form, just like with other room versions.

Clients should expect to see event IDs changed from the format of $ to something like $acR1l0raoZnm60CBwAVgqbZqoO/mYU81xysh1u7XcJk (note the lack of domain and the potentially problematic slash).

Server implementation components

Room version 3 uses the state resolution algorithm defined in room version 2, and the event format defined here.

Event IDs

The event ID is the reference hash of the event encoded using Unpadded Base64, prefixed with $. A resulting event ID using this approach should look similar to $CD66HAED5npg6074c6pDtLKalHjVfYb2q4Q3LZgrW6o.

Event IDs should not be sent over federation to servers when the room uses this room version. On the receiving end of an event, the server should compute the relevant event ID for itself.

Additionally, the auth_events and prev_events have had a format change compared to other room versions to make it easier to handle. Instead of a tuple of values, they are now plain lists of events.

Persistent Data Unit

A persistent data unit (event) for room version 3 and beyond.

Persistent Data Unit
Name Type Description
auth_events [string] Required:

Event IDs for the authorization events that would allow this event to be in the room.

Must contain less than or equal to 10 events. Note that if the relevant auth event selection rules are used, this restriction should never be encountered.

content object Required: The content of the event.
depth integer Required: The maximum depth of the prev_events, plus one. Must be less than the maximum value for an integer (2^63 - 1). If the room’s depth is already at the limit, the depth must be set to the limit.
hashes Event Hash Required: Content hashes of the PDU, following the algorithm specified in Signing Events.
origin string Required: The server_name of the homeserver that created this event.
origin_server_ts integer Required: Timestamp in milliseconds on origin homeserver when this event was created.
prev_events [string] Required:

Event IDs for the most recent events in the room that the homeserver was aware of when it made this event.

Must contain less than or equal to 20 events.

redacts string For redaction events, the ID of the event being redacted.
room_id string Required: Room identifier.
sender string Required: The ID of the user sending the event.
signatures { string: Server Signatures} Required: Signatures for the PDU, following the algorithm specified in Signing Events.
state_key string If this key is present, the event is a state event, and it will replace previous events with the same type and state_key in the room state.
type string Required: Event type
unsigned UnsignedData Additional data added by the origin server but not covered by the signatures. More keys than those defined here may be used.
Event Hash
Name Type Description
sha256 string Required: The hash.
Name Type Description
age integer The number of milliseconds that have passed since this message was sent.
prev_content object The content of the replaced state event.
prev_sender string The sender of the replaced state event.
redacted_because string A reason for why the event was redacted.
replaces_state string The event ID of the state event this event replaces.


  "auth_events": [
  "content": {
    "key": "value"
  "depth": 12,
  "hashes": {
    "sha256": "thishashcoversallfieldsincasethisisredacted"
  "origin": "",
  "origin_server_ts": 1404838188000,
  "prev_events": [
  "redacts": "$some/old+event",
  "room_id": "!",
  "sender": "",
  "signatures": {
    "": {
      "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
  "state_key": "my_key",
  "type": "",
  "unsigned": {
    "age": 4612,
    "key": "value",
    "prev_content": {
      "displayname": "Bob",
      "membership": "join"
    "prev_sender": "",
    "redacted_because": "Inappropriate content",
    "replaces_state": "$"

Changes to APIs

Due to the event ID being removed from the event, some APIs need to change. All APIs which currently accept an event ID must do so with the new format. Servers must append the calculated event ID to all events sent to clients where an event ID would normally be expected.

Because the format of events has changed, servers must be aware of the room version where the event resides so that the server may parse and handle the event. The federation API has taken this concern into consideration by ensuring that servers are aware of (or can find) the room version during a request.

Authorization rules for events

The authorization rules for a given event have changed in this room version due to the change in event format:

  • The event no longer needs to be signed by the domain of the event ID (as there is no domain in the event ID), but still needs to be signed by the sender’s domain.
  • In past room versions, redactions were only permitted to enter the DAG if the sender’s domain matched the domain in the event ID being redacted, or the sender had appropriate permissions per the power levels. Due to servers now not being able to determine where an event came from during event authorization, redaction events are always accepted (provided the event is allowed by events and events_default in the power levels). However, servers should not apply or send redactions to clients until both the redaction event and original event have been seen, and are valid. Servers should only apply redactions to events where the sender’s domains match, or the sender of the redaction has the appropriate permissions per the power levels.

The remaining rules are the same as room version 1.