Rooms & Events

Users on a server can send events into rooms. An event is a particular json object, describing what a user is trying to do (join a room, send a message, update a specific value…). An event will look like the following:

{
  "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
  }
}

In the case of instant messaging, clients display rooms very similarly to Slack, Discord or IRC channels. Most of the events in such rooms are messages. Rooms have a unique technical identifier, and zero or more human-readable aliases. Aliases are made of a room name, and a server part, and are sometimes referred to as "addresses". A typical room alias would be:

#goodfriends:example.com

From a technical perspective, a room is a series of json objects. The schema below represents a room with dumbed down events. It is up to the clients to read, parse, and display the events properly.

Local copies

Homeservers are federated: the Matrix specification defines a Sever-Server API (also known as Federation API) to describe interactions between servers. Whenever a user is in a room, their homeserver needs to have a local copy of that room.

For example, if @alice:example.com is the first user from example.com to try to join #goodfriends:matrix.org, then her homeserver is going to reach out to matrix.org to get a copy of the room. example.com and matrix.org then stay in touch to synchronise their copy of the room.

Administration & privileges

Whenever the homeserver receives new events, it's in charge of parsing them, perform checks on the event, and take action accordingly (e.g. sending messages from users on the homeserver to other participating homeservers, or distributing messages from other participating homeservers to users). The expected behaviour of homeservers is described fully in the Matrix Specification.

It could seem dangerous to think that everyone has their own local copy of the room. Doesn't that mean anyone can become administrator of the room and do nasty things? Fortunately, no. The privileges of people in the room are defined by Power Levels.

Power levels define a hierarchy in the room. All of the actions in a room require a minimum power level. Posting a message in a room requires having the power level 0, redacting someone else's message usually requires having power level 50, changing the room address usually requires having power level 100.

For more details on power levels, please check the relevant section of the community management documentation.

At room creation

A power level is an integer usually between 0 and 100 bound to an account in a room. According to the spec recommendations, when someone creates a room, their account gets power level 100 in that room. So if Alice creates the room #goodfriends on example.com, her account @alice:example.com will get the power level 100 in all the local copies of #goodfriends:example.com, whether the copy is on example.com, matrix.org or ergaster.org.

At room join

When someone else joins the room, whether they are on the same homeserver as the creator or another homeserver, by default they are assigned the power level 0. If Bob on matrix.org joins #goodfriends:example.com, his server is going to ask Alice's example.com a local copy of the room, and stay in sync with it.

If Carol joins from her homeserver ergaster.org, she will also get the power level 0.

Altering a local copy of the room

Let's now consider Walter. Walter is the homeserver administrator of example.com, the homeserver Alice used to create the #goodfriends:example.com room.

When he joins the room, Walter gets the power level 0 by default, as everyone else.

If Walter fiddled with its homeserver database to alter its local copy of the room, his change would not propagate: nobody has granted him power level 0: when the other homeservers would want to update their local copy of the room, they would reject the change making Walter administrator of the room.

Impersonating others

Some homeserver implementations like Synapse have a non-standard Admin API and more particularly an API to make someone the room admin. This doesn't mean homeserver administrators can't take over rooms as they please.

When Walter calls the Make Room Admin API, Synapse is going to control Alice's account to grant Walter the same Power Level as her. Alice is Power Level 100, she is allowed to promote Walter to the same Power Level. This is valid according to the Matrix Spec, so when the other homeservers will update their local copy of the room they will accept the change.

What if Walter was the homeserver administrator of ergaster.org instead? Every user of ergaster.org in this room have the Power Level 0. If Walter called this API, his homeserver would only be able to control a user with Power Level 0, and would not be able to promote him.