Intro

Basics

What is Matrix?

Matrix is an open standard for interoperable, decentralised, real-time communication over IP. It can be used to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things communication - or anywhere you need a standard HTTP API for publishing and subscribing to data whilst tracking the conversation history.

Matrix defines the standard, and provides open source reference implementations of Matrix-compatible Servers, Clients, Client SDKs and Application Services to help you create new communication solutions or extend the capabilities and reach of existing ones.

Client

Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.

client SDK

A client SDK makes it easier to develop client applications using matrix. See: How do I Matrix-enable my existing app?

close

What is Matrix's Mission?

Matrix’s initial goal is to fix the problem of fragmented IP communications: letting users message and call each other without having to care what app the other user is on - making it as easy as sending an email.

The longer term goal is for Matrix to act as a generic HTTP messaging and data synchronisation system for the whole web - allowing people, services and devices to easily communicate with each other, empowering users to own and control their data and select the services and vendors they want to use.

close

What does this mean for users?

The aim is to provide an analogous ecosystem to email - one where you can communicate with pretty much anyone, without caring what app or server they are using, using whichever client app & server you chose, and use a neutral identity system like an e-mail address or phone number to discover people to talk to.

Client

Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.

close

Why are you called Matrix?

We are called Matrix because we provide a structure in which all communication can be matrixed together.

No, it’s nothing to do with the film (although you could go and build virtual worlds on top of Matrix if you wanted :)

matrixed together

In mathematics, a matrix is a lattice-like arrangement, in which expressions can be combined and treated as a single entity

close

What does Matrix provide?

  • Open Standard HTTP APIs for transferring JSON messages (e.g. instant messages, WebRTC signalling), including:
    • Client<->Server API - defines how Matrix compatible clients communicate with Matrix homeservers.
    • Server<->Server API - defines how Matrix homeservers exchange messages and synchronise history with each other.
    • Application Service API - defines how to extend the functionality of Matrix with 'integrations' and bridge to other networks.
    • Modules - specifies features that must be implemented by particular classes of clients.
  • Open source reference implementations of:
    • Clients (Web (React), iOS, Android)
    • Client SDKs (Javascript, Web (React), iOS, Android)
    • Homeservers (Synapse)
    • Application Services (bridges to IRC, Slack, Skype, Lync and more...)
  • The actual ecosystem and community of everyone running Matrix servers and services
  • Loads of 3rd party contributions of clients, SDKs, servers and services.

You can find the full list of Matrix enabled projects at https://matrix.org/blog/try-matrix-now.

client SDK

A client SDK makes it easier to develop client applications using matrix. See: How do I Matrix-enable my existing app?

close

Who and How

What kind of company is Matrix.org?

Matrix.org is an open initiative which acts as a neutral and independent custodian of the Matrix standard. As of Sept 2017 we are finally in the process of incorporating it as a dedicated non-profit entity (most likely a limited by guarantee UK private company called the Matrix.org Foundation).

close

How is Matrix.org funded?

Matrix.org is currently funded by the community, through a combination of community support (via Patreon, Liberapay, Bitcoin and Ethereum), corporate sponsorship, and grant funding.

Current Elliptic-level supporters on Patreon and corporate sponsors can be found on our supporters page.

If you would like to support the core Matrix team as a member of the community, you can do so via:

  • Patreon
  • Liberapay
  • Bitcoin (address: 1LxowEgsquZ3UPZ68wHf8v2MDZw82dVmAE)
  • Ethereum (address: 0xA5f9a4f9E024F6D727f7afdA9257e22329A97485)

If you would like to sponsor the team as a corporation, or are interested in paying for prioritised or custom development, please get in touch.

For the first three years of Matrix's development (2014-2017), most of the core contributors worked for Amdocs, who paid for them to work fulltime on Matrix. In July 2017, Amdocs considered the project to be sufficiently successful that it could now self-support and so stopped funding. The majority of the core team is now employed by New Vector, an independent company set up to hire the team and support Matrix's development. Other contributors are funded by their own employers or donate their own time to the project.

In January 2018, Matrix.org announced that Status.im made a major strategic investment in New Vector, meaning we now have the financial backing to let us focus entirely on improving the Matrix ecosystem.

New Vector

New Vector is a company formed to build Matrix.org. It is a continuation of the original project team, and is focused on development and maintenance of matrix.org.

New Vector

New Vector is a company formed to build Matrix.org. It is a continuation of the original project team, and is focused on development and maintenance of matrix.org.

close

Who is building Matrix?

The core team is ~12 people with extensive experience in building custom VoIP and Messaging apps for mobile network operators. Most of us work for New Vector, but there are an increasing number of contributors from other companies and folks all over the internet.

New Vector

New Vector is a company formed to build Matrix.org. It is a continuation of the original project team, and is focused on development and maintenance of matrix.org.

close

Concept

Why have you released this as open source?

We believe that any open standard defining interoperable communication needs to be justified, demonstrated and validated with transparent open source implementations. For Matrix to achieve its mission of making all communications services interoperable we believe it needs to be truly open, giving people access to take all the code we produce and to use and build on top of it.

interoperable

A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.

close

What do you mean by open?

Matrix is an open standard, meaning that we have freely published the details for how to communicate interoperably using the Matrix set of HTTP APIs. We encourage anyone and everyone to use the APIs and build their own projects which implement them and so benefit from interoperability with the rest of the Matrix ecosystem. We also ensure the standard is not encumbered by any known patent licensing requirements.

Matrix is also open source, meaning that we have released the source code of the reference servers, clients and services to the public domain under the Apache Licence v2, to encourage anyone and everyone to run their own servers and clients, and enhance them and contribute their enhancements as they see fit.

interoperable

A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.

close

What does federated mean?

Federation allows separate deployments of a communication service to communicate with each other - for instance a mail server run by Google federates with a mail server run by Microsoft when you send email from @gmail.com to @hotmail.com.

Federation is different to interoperability, as interoperable clients may simply be running on the same deployment - whereas in federation the deployments themselves are exchanging data in a compatible manner.

Matrix provides open federation - meaning that anyone on the internet can join into the Matrix ecosystem by deploying their own server.

federation

Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.

interoperable

A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.

close

How is this like e-mail?

The History of email is instructive when thinking about the importance of interoperability.

Early email systems behaved as isolated communities which only allowed you to exchange mail with users on the same system.  If you got your email from one service and your friend from another, then you couldn't message each other.  This is basically the situation we're in today with VoIP and IM.

interoperable

A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.

close

Why has no one done this before?

There have been several attempts before including SIP, XMPP and RCS.

All of these have had some level of success, but many different technological/usability/economic factors have ended up limiting their success. Unfortunately, we've not ended up in a world where everyone has a SIP URI or Jabber ID on their business card, or a phone that actually uses RCS.

Take a look at the Comparisons section for a more detailed look at how Matrix compares to other projects.

SIP

Session Initiation Protocol is a communications protocol for signaling and controlling multimedia communication sessions in applications of Internet telephony for voice and video calls.

XMPP

XMPP is a communication protocol for message-oriented middleware based on XML. We think of Matrix and XMPP as being quite different; at its core Matrix can be thought of as an eventually consistent global JSON db, whilst XMPP can be thought of as a message passing protocol.

RCS

Rich Communication Services is a communication protocol between mobile-telephone carriers and between phone and carrier, aiming at replacing SMS messages with a text-message system that is richer, provides phonebook polling (for service discovery), and transmit in-call multimedia.

close

Practical

What can I actually do with this?

A typical client provides a simple chatroom interface to Matrix - letting the user interact with users and rooms anywhere within the Matrix federation.  Text and image messages are supported, and basic voice-only VoIP calling via WebRTC is supported in one-to-one rooms. (As of October 2015, experimental multi-way calling is also available on Riot.im).

Client

Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.

federation

Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.

close

How can I get involved?

There are plenty of ways to get involved. First, create a user account and come say hi on #matrix:matrix.org!

Then...

  • Install synapse and tell us how you get on.
  • Critique the spec, take at look at the current status and see what has been proposed.
  • Write clients.
  • Write bridges! Run bridges!
  • Nose around in the repositories in our GitHub organization and send us some pull requests to fix some bugs or add some features!
  • You could even try to write a homeserver (but be warned, Matrix's architecture makes homeservers orders of magnitude harder than clients or bridges.)

See CONTRIBUTING.rst for full details on how to contribute to the project. All are welcome!

Synapse

Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.

the spec

The Matrix Specification describes the interactions between actors in the Matrix ecosystem, including Server-Server and Client-Server. You can see the spec here.

Client

Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.

bridging

Bridging to Matrix means that it's possible to read and write to channels hosted outside matrix. For example, it's possible to speak in IRC and slack rooms.

close

Where can I get support?

The point of entry for everything matrix is the room #matrix:matrix.org aka #matrix on irc.freenode.

If you're a developer and are looking to get involved with building something on Matrix, try #matrix-dev:matrix.org.

If you host a Synapse homeserver instance and would like support, try #synapse-community:matrix.org.

room

A room is a fundamental building bock of the matrix architecture: events are typically sent in the context of a room. A room is a conceptual place where users can send and receive events. Events are sent to a room, and all participants in that room with sufficient access will receive the event. See more detail.

Synapse

Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.

close

Usage

As a user

What clients are available?

See also: Which matrix clients support E2E?

There are many clients available, ranging from the glossy mass-market to the geeky command-line. There's even an emacs macro.

The most popular and established client is Riot, available on web, desktop, Android and iOS.

Alternatively you can find a client suitable for you:

  • if you're using GNOME, try Fractal
  • Nheko is a glossy native desktop app for Matrix, based on Qt5.
  • Quaternion is a cross-platform desktop client based on Qt5/QML
  • if you prefer a command line client, there is a Matrix plugin for Weechat
  • neo is a Matrix React.js webclient
  • Seaglass is a recently announced (as of July 2018) client written as a native macOS app

A thorough list of clients can be found on the try-matrix-now page.

close

What bridges to other networks are available?

There are a large number of 'bridges' which integrate existing communication networks into Matrix. This list is growing rapidly, and you can find bridges both written by the Matrix core team and contributed by the wider community. The full list can be seen at https://matrix.org/blog/try-matrix-now

As of July 2018, active bridges include:

Writing new bridges is incredibly fun and easy - see the matrix-appservice-bridge HOWTO for an example of how to write a fully functional Slack bridge in less than 100 lines of code!

bridging

Bridging to Matrix means that it's possible to read and write to channels hosted outside matrix. For example, it's possible to speak in IRC and slack rooms.

close

How do I get an account and get started?

The quickest way is to pick a client from https://matrix.org/blog/try-matrix-now and sign up.

Clients can access any homeserver - you don't have to use matrix.org, though as of July 2018 matrix.org is the largest public homeserver.

hello-matrix.net maintains a list of public Matrix servers.

homeserver

Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.

close

Where can I find a mobile app?

Riot is available for Android and iOS.

The iOS version can be downloaded from the Apple store.

The Android version can be downloaded from the Google Play store or F-Droid. If you are not sure which one to choose, install Riot from the Google Play store.

For the Android app, you can also install the latest development version built by Jenkins. Use it at your own risk and only if you know what you are doing.

Riot

Riot is a popular matrix client developed by the core matrix.org team. It's available as a web app, on Android and on iOS.

close

I installed Riot via F-Droid, why is it draining my battery?

The F-Droid release of Riot does not use Google Cloud Messaging. This allows users that do not have or want Google Services installed to use Riot.

The drawback is that Riot has to pull for new messages, which can drain your battery. To counter this, you can change the delay between polls in the settings. Higher delay means better battery life (but may delay receiving messages). You can also disable the background sync entirely (which means that you won't get any notifications at all).

If you don't mind using Google Services, you might be better off installing the Google Play store version.

close

Where can I find a web app?

See also: What clients are available?

Riot

You can use Riot.im - a glossy web client written on top of matrix-react-sdk.

You can also host Riot on your own server. It's a static web application, just download the last release and unpack it.

neo

neo is a Matrix React.js webclient which aims to be lighter than Riot while still feature complete.

close

Where can I find a desktop client?

See also: What clients are available?

You can use the desktop build of Riot.im.

  • if you're using GNOME, try Fractal
  • Nheko is a glossy native desktop app for Matrix, based on Qt5.
  • Quaternion is a cross-platform desktop client based on Qt5/QML
  • Seaglass is a recently announced (as of July 2018) client written as a native macOS app

There are also other desktop clients - check the list of clients on matrix.org.

close

How can I get a rooms list from matrix.org?

If you're using Riot, you can use the "Room directory" screen, which you open from a button in the bottom left.

It you're working on a client, you can use the Client-Server API to get a list of public rooms.

Riot

Riot is a popular matrix client developed by the core matrix.org team. It's available as a web app, on Android and on iOS.

close

Tech

How do I Matrix-enable my existing app?

If your app doesn't have any communication capability already, you'll want to use one of the Matrix client SDKs to add it in. These come in different levels of sophistication - ranging from a simple HTTP API wrapper through to reusable UI components.

There are even more client SDKs available.

Pick the one for your platform, or a 3rd party one if none of the above work for you, and get plugging it in. You'll probably also want to read the Client-Server API HOWTO too.

If you already have communication infrastructure set up (XMPP, custom HTTP, or whatever), then you'll want to run a bridge to expose it to the wider Matrix ecosystem. See matrix-appservice-bridge HOWTO for a guide of how to write bridges using the matrix-appservice-bridge framework, or co-opt one from the list at https://matrix.org/blog/try-matrix-now. Application Service API gives the details of the API that bridges have to implement.

client SDK

A client SDK makes it easier to develop client applications using matrix. See: How do I Matrix-enable my existing app?

close

How can I write a client on Matrix?

See the Client-Server API HOWTO and the API docs and the Spec for all the details you need to write a client.

"Enter the Matrix" from Brendan Abolivier is a great introductory article which also covers the CS API.

close

How do I register custom matrix event types?

We're not yet managing a registry of custom matrix event types.  If you have any particularly good ones you want to tell the world about, please let us know on #matrix-dev:matrix.org.

close

Can I write a Matrix homeserver?

Yes. Matrix is just a spec, and implementations of the spec are very welcome!

The most well-distributed homeserver in the wild today is Synapse. Writing a Matrix homeserver is a different and larger challenge than writing a bot or a client, but other projects aiming to implement the server component include:

The S2S spec is still being finalised for r0, so if you are planning on doing work in this area, come chat to us in #matrix-dev:matrix.org. You can also read about the Federation API here.

the spec

The Matrix Specification describes the interactions between actors in the Matrix ecosystem, including Server-Server and Client-Server. You can see the spec here.

homeserver

Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.

Synapse

Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.

bot

A bot is an autonomous agent. In the context of matrix, it means software which is able to make automated posts in rooms.

Client

Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.

close

Why HTTP? Doesn't HTTP suck? Why don't you use websockets/CoAP/HTTP2/etc?

HTTP may not be the most efficient transport, but it is ubiquitous, very well understood and has numerous implementations on almost every platform and language. It also has a simple upgrade path to HTTP/2, which is relatively bandwidth and round-trip efficient.

For these reasons it has been chosen as the mandatory baseline of the exchange, but it is still entirely possible to use other protocols for communication between clients and server (see for example this websocket transport spec proposal), and it's also possible in the future that negotiation of more efficient protocols will be added for the federation between servers, with HTTP+JSON remaining as the compatibility baseline.

federation

Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.

close

Self-hosting

How do I join the global Matrix federation?

You can choose a client and create a user account on an existing homeserver.

To host your own homeserver you can download and run one of the available Matrix servers - please see this guide for details!

To better understand how to enable federation in Synapse, take a look at the specific docs.

homeserver

Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.

federation

Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.

Synapse

Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.

close

How do I run my own homeserver?

Follow the instructions for the homeserver you want to run. If you want to run Synapse, the reference homeserver from Matrix.org, follow these instructions.

homeserver

Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.

Synapse

Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.

close

What ports do I have to open up to join the global Matrix federation?

We recommend servers use port 8448 for server<->server HTTPS traffic. Look at "Setting up Federation" in the Synapse readme file for details.

Client<->Server traffic can talk directly to Synapse via port 8448, but as by default Synapse creates a self-signed TLS certificate this can cause problems for clients which can't easily trust self-signed certificates (e.g. most web browsers). Instead, you can proxy access to Synapse's HTTP listener on port 8008 via an existing HTTPS proxy with a valid certificate (e.g. an nginx listening on port 443), or you can point Synapse at a valid X.509 signed TLS certificate. In future, Synapse will probably use letsencrypt to autogenerate valid certificates rather than self-signed ones during installation, simplifying this process enormously.

You can also put Synapse entirely behind an existing TLS load balancer and not expose port 8448 at all. In this situation, Synapse will need to be configured to share the same public TLS certificate as the load balancer (as Synapse uses the public certificate for identity in other areas too, and it has to match the certificate that other servers see when they connect).

close

How do I connect my homeserver to the public Matrix network?

If you have a successfully running Synapse instance and want to federate with the rest of the public network, take a look at the specific documentation for details.

federation

Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.

close

Can I run my own identity server?

See also: What is an identity server?

Yes - the reference implementation is sydent and you can run your own ID server cluster that tracks 3rd party to Matrix ID mappings. This won't be very useful right now, though, and we don't recommend it.

If you want your server to participate in the global replicated Matrix ID service then please get in touch with us. Meanwhile, we are looking at ways of decentralising the 'official' Matrix identity service so that identity servers are 100% decentralised and can openly federate with each other. N.B. that you can use Matrix without ever using the identity service - it exists only to map 3rd party IDs (e.g. email addresses) to matrix IDs to aid user discovery.

close

Why can't I rename my homeserver?

Currently, the homeserver name is assumed never to change. This means that if you rename your server, other servers will think it's a different server.

Perhaps in the future we will add an API for changing the homeserver name, but for now this is not supported.

homeserver

Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.

close

Where can I find tools to get starting maintaining a Synapse installation?

There is a collection of utilities provided by xwiki-labs simply called synapse scripts. This collection features the popular synapse_janitor.sql script, which can help clean up a Postgres database.

Postgres

While Synapse can be installed using, Sqlite Postgres is preferred for any significant use.

close

Detail

Position in the World

Why do you think existing apps will ever join this officially?

We firmly believe it is what is right for the consumer. As people begin to use interoperable communications tools, service providers will see the benefit and compete on quality of service, security and features rather than relying on locking people into their walled garden. We believe as soon as users see the availability and benefits of interoperable services they will demand it.

interoperable

A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.

close

Why aren't you doing this through the IETF? or W3C? or 3GPP?

We do recognise the advantages of working with existing standards bodies. We have been focused on writing code and getting it out, and the standard has been evolving rapidly since initial release in September 2014. Once the standard has matured sufficiently it may well be appropriate to work with an official standard body to maintain it going forwards.

close

What is the current project status?

A very quick recap by-the-numbers:

  • Started out in Sept 2014
  • Currently in very late beta
  • ~3.6M user accounts on the Matrix.org homeserver
  • ~2.0M messages per day
  • ~1M unbridged accounts
  • ~500K unbridged messages per day
  • ~900K rooms that Matrix.org participates in
  • ~6000 federated servers
  • ~2000 msgs/s out, ~20 msgs/s in on Matrix.org
  • ~60 companies building on Matrix

As of July 2018, the Matrix ecosystem has dozens of independent homeserver hosts, many bridges and is under active development.

Current development focus is "The Road to 1.0", which means:

  • The aim is to get all APIs to a stable release by end of August 2018
  • Finalising Server/Server API currently
  • Heavy emphasis on security work.
close

Why Apache Licence?

See also: What do you mean by open?

The Apache Licence is a permissive licence. We want the Matrix protocol itself to be free and open, but people are free to create both free and commercial apps and services that uses the protocol. In our opinion, any Matrix-service only enhances the Matrix ecosystem.

close

Comparisons

What is the difference between Matrix and IRC?

We love IRC. In fact, prior to the point where Riot was stable enough for daily use IRC was our primary communication tool. Between us we've written IRCds, IRC bots and admined dreamforge, UnrealIRCd, epona, ircservices and several others. That said, it has some limitations that Matrix seeks to improve on:

  • Text only
  • No history
  • No multiple-device support
  • No presence support
  • Fragmented identity model
  • No open federation
  • No standard APIs, just a rather limited TCP line protocol
  • Non-standardised federation protocol
  • No built-in end-to-end encryption
  • Disruptive net-splits
  • Non-extensible

IRCv3 exists and is addressing some of these issues; this is great news and we wish them well. It's almost a contradiction in terms to get competitive between openly interoperable communication projects - in fact there there already exist mature Matrix<->IRC bridges. matrix-appservice-irc is currently used by matrix.org to bridge with FreeNode.

Riot

Riot is a popular matrix client developed by the core matrix.org team. It's available as a web app, on Android and on iOS.

federation

Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.

close

What is the difference between Matrix and XMPP?

We think of Matrix and XMPP as being quite different; at its core Matrix can be thought of as an eventually consistent global JSON db with an HTTP API and pubsub semantics - whilst XMPP can be thought of as a message passing protocol. You can use them both to build chat systems; you can use them both to build pubsub systems; each comes with different tradeoffs. Matrix has a deliberately extensive 'kitchen sink' baseline of functionality; XMPP has a deliberately minimal baseline set of functionality. If XMPP does what you need it to do, then we're genuinely happy for you! Meanwhile, rather than competing, an XMPP Bridge like Skaverat's xmpptrix beta or jfred's matrix-xmpp-bridge or Matrix.org's own purple-matrix has potential to let both environments coexist and make the most of each other's benefits.

The whole area of XMPP vs Matrix is quite subjective. Rather than fighting over which open interoperable communication standard works the best, we should just collaborate and bridge everything together. The more federation and interoperability the better.

XMPP

XMPP is a communication protocol for message-oriented middleware based on XML. We think of Matrix and XMPP as being quite different; at its core Matrix can be thought of as an eventually consistent global JSON db, whilst XMPP can be thought of as a message passing protocol.

pubsub

The publish-subscribe pattern describes an architecture in which message senders push messages to a location, without needing to know who the subscribers will be. For Matrix, this means a client can send a message to a room without knowing the members, and the members can read that message.

close

How does Matrix compare with something like Trillian or Pidgin?

Trillian and Pidgin and similar aggregating IM clients merge all your IM activity into a single app.  However, your history and identity is still fragmented across the networks.  People can't find you easily, and your history is fragmented (other than on the device where the client runs).   And rather than being able to chose the right app for the job when communicating with people, you are pushed towards relying on a specific aggregation app.

Matrix lets you get the best of both worlds by linking to all the different networks (XMPP, AIM, ICQ, Lync, Skype etc) on the serverside, using bridges which can be run by anyone. Matrix then provides a simple standard HTTP API to access any of these networks, and lets you choose whichever client you prefer (either as a 'native' Matrix client or using a non-Matrix client from one of the networks which has been bridged in).

close

More Detail

What is a client?

Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.

close

Can I use Matrix without installing a Matrix client?

Yes! An ever increasing number of protocols are being bridged into Matrix, so if you use something like IRC on Freenode you may well be indirectly benefiting from Matrix, as others may be connected into the IRC channel via Matrix.

bridging

Bridging to Matrix means that it's possible to read and write to channels hosted outside matrix. For example, it's possible to speak in IRC and slack rooms.

close

What is a home server?

A user's client connects to a single homeserver, which stores the communication history and account information for that user, and shares data with the wider Matrix ecosystem by synchronising communication history with other homeservers.

Client

Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.

close

What is a MXID?

Matrix user IDs (MXID) are unique user IDs. They are in the format @username:homeserver.tld (this format is used to avoid confusing them with email addresses.) They are intended to be fairly hidden (although right now they are not) - instead you will find and identify other users via 3PIDs.

3PID

Third-party IDs (3PIDs) are IDs from other systems or contexts, such as email addresses, social network accounts and phone numbers.

close

What is a 3PID?

Third-party IDs (3PIDs) are IDs from other systems or contexts, such as email addresses, social network accounts and phone numbers.

close

What is an identity server?

Users in Matrix are identified internally via their matrix user ID (MXID). However, existing 3rd party ID (3PID) namespaces such as email addresses or phone numbers should be used publicly to identify Matrix users, at least for invitation purposes. A Matrix "Identity" describes both the user ID and any other existing IDs from third party namespaces linked to their account.

Matrix users can link third-party IDs (3PIDs) to their user ID. Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping can then be used by Matrix users in order to discover the MXIDs of their contacts.

In order to ensure that the mapping from 3PID to user ID is genuine, the intention is for a globally federated cluster of trusted "Identity Servers" (IS) be used to verify the 3PID and persist and replicate the mappings. Usage of an IS is not required in order for a client application to be part of the Matrix ecosystem. However, without one clients will not be able to look up user IDs using 3PIDs.

The precise architecture of identity servers is currently in flux and subject to change as we work to fully decentralise them.

MXID

Matrix user IDs (MXID) are unique user IDs. They are in the format @username:homeserver.tld.

3PID

Third-party IDs (3PIDs) are IDs from other systems or contexts, such as email addresses, social network accounts and phone numbers.

close

Where do my conversations get stored?

Each homeserver stores the communication history and account information for all of its clients, and shares data with the wider Matrix ecosystem by synchronising communication history with other homeservers and their clients. Clients typically communicate with each other by emitting events in the context of a virtual room. Room data is replicated across all of the homeservers whose users are participating in a given room.

homeserver

Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.

Client

Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.

federation

Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.

close

What are redactions?

Since events are extensible it is possible for malicious users and/or servers to add keys that are, for example offensive or illegal. Since some events cannot be simply deleted (e.g. membership events) we instead 'redact' events, essentially stripping the event of all keys that are not required by the protocol. Redacting an event cannot be undone, allowing server owners to also delete the offending content from the databases.

close

Can I log into other homeservers with my username and password?

Currently, no. We are looking at options for decentralising or migrating user accounts between multiple servers, and might add this feature at a later stage.

close

What are communities?

Communities, previously known as "groups" are collections of rooms. They use "+" as a sigil, for example +matrix:matrix.org.

community

Communities are collections of rooms.

group

Groups are now known as communities, they are collections of rooms.

sigil

Sigils refer the symbols uses at the beginning of many matrix identifiers. For example '@' is used for users, '#' for rooms, and '+' for communities.

close

Architecture

How does Matrix actually work architecturally?

For an introduction to the Matrix architecture, see https://matrix.org/docs/spec#architecture.

close

What is a room?

For a more thorough introduction see: https://matrix.org/docs/spec#room-structure.

A room is a conceptual place where users can send and receive events. Events are sent to a room, and all participants in that room with sufficient access will receive the event.

close

Encryption

What does End-to-End (E2E) encryption mean?

End-to-End encryption describes a scenario where a message is encrypted at the device or client of the sender, and is only decrypted by the device or client of the receiver, with no decryption or reading performed on the server.

close

What is the status of E2E?

End-to-End Encryption is currently in late beta. Rooms can have encryption enabled, but it is not by default.

Regarding client support, Riot and Nheko each currently support E2E end.

As of July 2018, work is progressing to add E2E support in the matrix-python-sdk.

Riot

Riot is a popular matrix client developed by the core matrix.org team. It's available as a web app, on Android and on iOS.

close

Which matrix clients support E2E?

End-to-end encryption is currently available in Riot (and the matrix-react-sdk) and more recently in Nheko. E2E will also presently be available in the matrix-python-sdk.

Riot

Riot is a popular matrix client developed by the core matrix.org team. It's available as a web app, on Android and on iOS.

close

The Spec

What is The Spec?

The Matrix Specification describes and prescribes the interaction between clients, servers, Application Services and more.

The spec is available to read on matrix.org.

To contribute to the development of the Matrix Specification, see https://matrix.org/docs/spec/proposals.

Client

Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.

homeserver

Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.

close

Where is The Spec?

You can view the spec at https://matrix.org/docs/spec/.

close

How can I contribute to The Spec?

To contribute to the Matrix Specification, first take a look at the documentation as it is currently written, then review the process for new proposals. You should start by writing a publicly-accessible proposal describing your change.

To see the proposals currently under discussion,join us in #matrix-spec:matrix.org.

close

What is the process for adding Spec proposals?

See the documentation at https://matrix.org/docs/spec/proposals. In summary:

close

What's an MSC?

"MSC" refers to Matrix Spec Change, each proposal is assigned an MSC number to make referencing them easier.

MSC numbers are taken from GitHub issues on the matrix-doc repo. To see a list of all active MSCs, and to understand how to contribute your own, see https://matrix.org/docs/spec/proposals.

close

Voip

How do you do VoIP calls on Matrix?

Voice (and video) over Matrix uses the WebRTC 1.0 standard to transfer call media (i.e. the actual voice and video traffic). Matrix is used to signal the establishment and termination of the call by sending call events, like any other event.

close

Are VoIP calls encrypted?

WebRTC encrypts the media that's being sent. The signalling events that set up (and end) the call are encrypted if the room they were sent in has enabled encryption.

close

Do I need a TURN server?

VoIP calls should work if both parties are on public networks. However, in practice one (or both) devices are often behind NAT, and so having a TURN server is important to help set up the call.

See this guide for setting up a TURN server with Synapse.

close

Synapse

What is Synapse?

Synapse is a reference "homeserver" implementation of Matrix from the core development team at matrix.org, written in Python 2/Twisted. It is intended to showcase the concept of Matrix and let folks see the spec in the context of a codebase and let you run your own homeserver and generally help bootstrap the ecosystem.

homeserver

Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.

close

Why is Synapse in Python/Twisted?

This is because both provide a mature and well known event-driven async IO framework for writing serverside code. Whilst this has been okay for our initial experimentation and proof of concept, it's future homeserver work will be written in a more strongly typed language (e.g. Go).

As of July 2018 work is progressing on Dendrite, a homeserver from the matrix.org core team written in Go.

homeserver

Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.

close

Why aren't you using an ORM layer like SqlAlchemy in Synapse?

Synapse is very database dependent (as of Oct 2015; this is improving in the near future however), and we like having the flexibility to sculpt our own queries.

close

Will Synapse share my chat data with other servers in the federation?

Federation in Matrix means that data is only shared between servers of participating users of a room. If all users in a room are on your server, no data is shared with other servers.

federation

Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.

close

Why is the state_groups_state table so large? What is it storing?

Room state takes up a lot of space! To be specific, regular snapshots are taken of room states, so you can rapidly find out the state for historical events.

Why is it so important to record this, and to know the past room state including full member list?

It's needed to enable access control and state resolution, for example the home server needs to be able to decide:

  • "who can see this message at that point in time?"
  • "what was the state of the room was when this message was received, and so is it allowed to be received?"

Synapse stores these snapshots approximately every 100 messages, with deltas in between.

close

Definitions

Term Definition
Client Users in Matrix use one or more clients to communicate. This could be any combination of a web client, a command line client, a mobile client - or embedded clients built into existing apps. It could even be a piece of hardware (e.g. a drone) that is Matrix enabled.
matrixed together In mathematics, a matrix is a lattice-like arrangement, in which expressions can be combined and treated as a single entity
homeserver Each account in the Matrix federation is associated with a single homeserver. The software running at this server stores the history and account information for that user. Homeservers synchronise message history with other homeservers.
Synapse Synapse is a homeserver implemented in Python by the matrix.org core team. It is currently by far the most installed homeserver available.
interoperable A more general definition of interoperability is for systems to be able to freely exchange data with another by a known mechanism. In the case of matrix, we have openly documented how to communicate with our HTTP APIs.
New Vector New Vector is a company formed to build Matrix.org. It is a continuation of the original project team, and is focused on development and maintenance of matrix.org.
federation Federation means that separate instances of a service communicate - the best example of this is email servers, in which it's possible to send mail between difference service providers. For Matrix, this means that data about rooms and message history is shared between servers of participating users.
SIP Session Initiation Protocol is a communications protocol for signaling and controlling multimedia communication sessions in applications of Internet telephony for voice and video calls.
XMPP XMPP is a communication protocol for message-oriented middleware based on XML. We think of Matrix and XMPP as being quite different; at its core Matrix can be thought of as an eventually consistent global JSON db, whilst XMPP can be thought of as a message passing protocol.
RCS Rich Communication Services is a communication protocol between mobile-telephone carriers and between phone and carrier, aiming at replacing SMS messages with a text-message system that is richer, provides phonebook polling (for service discovery), and transmit in-call multimedia.
bridging Bridging to Matrix means that it's possible to read and write to channels hosted outside matrix. For example, it's possible to speak in IRC and slack rooms.
Riot Riot is a popular matrix client developed by the core matrix.org team. It's available as a web app, on Android and on iOS.
client SDK A client SDK makes it easier to develop client applications using matrix. See: How do I Matrix-enable my existing app?
MXID Matrix user IDs (MXID) are unique user IDs. They are in the format @username:homeserver.tld.
3PID Third-party IDs (3PIDs) are IDs from other systems or contexts, such as email addresses, social network accounts and phone numbers.
the spec The Matrix Specification describes the interactions between actors in the Matrix ecosystem, including Server-Server and Client-Server. You can see the spec here.
sigil Sigils refer the symbols uses at the beginning of many matrix identifiers. For example '@' is used for users, '#' for rooms, and '+' for communities.
community Communities are collections of rooms.
group Groups are now known as communities, they are collections of rooms.
room A room is a fundamental building bock of the matrix architecture: events are typically sent in the context of a room. A room is a conceptual place where users can send and receive events. Events are sent to a room, and all participants in that room with sufficient access will receive the event. See more detail.
bot A bot is an autonomous agent. In the context of matrix, it means software which is able to make automated posts in rooms.
pubsub The publish-subscribe pattern describes an architecture in which message senders push messages to a location, without needing to know who the subscribers will be. For Matrix, this means a client can send a message to a room without knowing the members, and the members can read that message.
Postgres While Synapse can be installed using, Sqlite Postgres is preferred for any significant use.
How helpful was this page? Click to give a rating