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

Room Version 4

This room version builds on version 3 using a different encoding for event IDs.

Client considerations

This room version changes the format form event IDs sent to clients. Clients should already be treating event IDs as opaque identifiers, and should not be concerned with the format of them. Clients should still encode the event ID when including it in a request path.

Clients should expect to see event IDs changed from the format of $randomstring:example.org to something like $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg (note the lack of domain).

Server implementation components

The information contained in this section is strictly for server implementors. Applications which use the Client-Server API are generally unaffected by the intricacies contained here. The section above regarding client considerations is the resource that Client-Server API use cases should reference.

Room version 4 uses the same algorithms defined in room version 3, however using URL-safe base64 to generate the event ID.

Event IDs

Room version 3 generated event IDs that were difficult for client implementations which were not encoding the event ID to function in those rooms. It additionally raised concern due to the / character being interpretted differently by some reverse proxy software, and generally made administration harder.

The event ID is the reference hash of the event encoded using a variation of Unpadded Base64 which replaces the 62nd and 63rd characters with - and _ instead of using + and /. This matches RFC4648’s definition of URL-safe base64. Event IDs are still prefixed with $ and may result in looking like $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg.

Just like in room version 3, 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. Room version 3 also changes the format of auth_events and prev_events in a PDU.

`Persistent Data Unit`

A persistent data unit (event) for room version 4 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.

UnsignedData
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.

Examples

{
  "auth_events": [
    "$urlsafe_base64_encoded_eventid",
    "$a-different-event-id"
  ],
  "content": {
    "key": "value"
  },
  "depth": 12,
  "hashes": {
    "sha256": "thishashcoversallfieldsincasethisisredacted"
  },
  "origin": "example.com",
  "origin_server_ts": 1404838188000,
  "prev_events": [
    "$urlsafe_base64_encoded_eventid",
    "$a-different-event-id"
  ],
  "redacts": "$some-old_event",
  "room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
  "sender": "@alice:example.com",
  "signatures": {
    "example.com": {
      "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
    }
  },
  "state_key": "my_key",
  "type": "m.room.message",
  "unsigned": {
    "age": 4612,
    "key": "value",
    "prev_content": {
      "displayname": "Bob",
      "membership": "join"
    },
    "prev_sender": "@someone:example.org",
    "redacted_because": "Inappropriate content",
    "replaces_state": "$state_event:example.org"
  }
}

Last modified December 14, 2020: Remove /en directory and move content up a level (128876b)