Elements of Matrix

curl -XPOST
 -d '{"msgtype":"m.text", "body":"hello"}'
 "https://matrix.alice.com/_matrix/client
 /v2/rooms/ROOM_ID/send/m.room.message
 ?access_token=ACCESS_TOKEN"
{
  "event_id": "$YUwRidLecu:alice.com"
}

curl –XPOST –H 'Authorization: X-Matrix origin=alice.com,...' –d '{
    "ts": 1413414391521,
    "origin": "alice.com",
    "destination": "bob.com",
    "pdus": [{
        "event_id": "$YUwRidLecu:alice.com",
        "content": {
        "body": "hello world",
        "msgtype": "m.text"
        },
        ...
        "pdu_type": "m.room.message",
        "signatures": {
        "matrix.org": {
            "ed25519:auto": "jZXTwAH/7EZ..."
        }
        },
        "sender": "@alice:alice.com"
    }]
}' https://matrix.bob.com:8448/_matrix/federation/v1/send/916d...

curl "https://matrix.bob.com/_matrix/client/v2/sync?access_token=ACCESS_TOKEN"
{
    "next_batch": "s72595_4483_1934",
    "rooms": [{
    "room_id": "!KrLWMLDnZAyTapqLWW:alice.com",
    "events": {
        "batch": [{
        "event_id": "$YUwRidLecu:alice.com",
        "type": "m.room.message",
        "content": {
            "body": "I am a fish",
            "msgtype": "m.text",
        },
        "origin_server_ts": 1417731086797,
        "sender": "@alice:alice.com"
        }],
    },
    }]
}

Matrix works like email, but for instant messaging. People need to use a client to be able to write and receive messages, and they need providers to provide them an account on their homeserver.

Let's explore what those are.

Homeserver

A homeserver is a piece of software hosting accounts of Matrix users. It is bound to a single domain that cannot change over time. The accounts on a server have an identifier made of a local part (the username), and a server part, which is the (vanity) domain of the homeserver. A typical identifier would be

@username:example.com

The Matrix ID of the users on the schema above look like below.

You can find a list of existing homeserver implementations in the Ecosystem > Servers section of this website. Most of them are open source, so you can explore how they work. Please also refer to their documentation if you want to deploy them either for testing or in production.

Client

Homeservers communicate between each other with the Server-Server / Federation API, but they also communicate with clients in a standard way: the Client-Server API.

Clients are pieces of software that can use a Matrix account to send and receive events from a specific homeserver. The clients themselves only ever talk to the homeserver of the account they're using. If a client uses the @alice:example.com account, they will only talk to example.com.

The most common kinds of client are the user facing ones. In the case of instant messaging, those clients show rooms as timeline of messages, with users joining, leaving, redacting messages…

To get a better idea of what clients look like in practice, you can find a list on Ecosystem > Clients and give them a go.

If you're more interested in writing your own client to bring a new experience to users, you may want to rely on an existing SDK (see Ecosystem > SDKs). Those will do significant part of the Matrix heavy-lifting and allow you to focus on the UX you want to build. Finally, if you're interested in learning more about the interactions between clients and servers, please head to the Client-Server section of the Matrix Specification.

AppService (bridges and some bots)

Many Matrix bots are non-human clients. They can be built with the same SDKs as regular clients, and instead of showing a UI to display what is happening they will listen to events, parse them, and for example send automatic replies.

Simple and advanced bots

A good example of simple bot would be a RSS bot: it subscribes to a RSS feed completely outside of Matrix and whenever it sees a new item in the feed it posts a message in a specific Matrix room, with the name of the item. Such a bot is nothing more than a very limited and specialised client.

But sometimes you need to get a more global view of what is happening on your homeserver to take action. If you want to write an anti-spam module for example, you want to be able to read each and every message from public rooms to detect patterns and ring the alarm or take action directly.

To do it with a bot, you would need to invite the bot in each and every room where you want the monitoring to happen. An appservice is able to monitor all the unencrypted events (messages sent/edited/redacted, people joining or leaving rooms) within its namespace.

Bridges

Sometimes you need to do even more than being an all-seeing eye: you need to be able to create users and rooms automatically. A typical use case for this is bridges. Bridges allow you to connect a Matrix community to a third-party platform such as IRC, Discord or Slack. Users on these communities appear as native users on Matrix, and ideally the other way around on the third-party platform as well.

• The users created on the Matrix side by the bridge to mimic users on the third-party platform are called ghosts.
• The users created on the third-party platform by the bridge to mimic Matrix users are called puppets.

To do so, the bridge needs to be able to create and impersonate users on Matrix, and to control rooms as well. In order to limit the risks of abuse, bridges can be limited to controlling a namespace.

To get a high level view of bridges concepts and see which platforms Matrix can be bridged to, please head to Ecosystem > Bridges on this website. If you're interested in writing your own bridge, you will very likely want to rely on an existing SDK, in which case you check the existing ones in Ecosystem > SDKs and have a look at the Application Service section of the specification.

The Specification

We have been mentioning the Matrix Specification several times already. The Matrix Specification is a document describing interactions between the various components of the Matrix ecosystem (homeservers, clients, appservices). For a given feature, implementation details may vary, but Matrix aims for a consistent behaviour and wants to avoid the need for negotiation between parties.

The specification is open, versioned, and can be freely browsed at spec.matrix.org. Its governance and decision process are public, so anybody can make a proposal to extend it via Matrix Spec Change.

A Matrix Spec Change (MSC) is a document describing how the author would like to amend the Matrix Specification, to introduce a change in the interactions between the components of the ecosystem. Such documents are discussed publicly, and when the author think they have addressed all of the important concerns they can bring the Spec Core Team's attention to it and start the formal review process.

The Matrix Spec Process is detailed on spec.matrix.org.