This is a documentation about how to get started using the messenger app Riot, which uses the free, open and secure protocol “Matrix”.

Why should you use this one? For several reasons I consider Riot with Matrix the most interesting messaging solution for everyone available today. Please see this blog post to read more about my reasoning.

Unfortunately, I couldn’t find a good user guide online. This article should help everyone, not only IT geeks, to simply start messaging in the fediverse of Riot and Matrix.

To follow this guide to its full extent you need:

  • a computer 
  • a friend you’d like to chat with
  • 15 minutes of your time

Have fun!

First, create an account

1. Let’s download the messaging app “Riot” on the device of your choice. Go to and download Riot for your operating system.

2. Install Riot and start it. After startup it should look like this:

3. Create an account by clicking on “Register” in the text field with the red alert sign upfront. It should look like this:

Now, fill out the fields. Note that only a user name and password is mandatory. However, I recommend to provide your email address to allow password recovery. For this guide, I assume you provide an email address.
Finish registration by clicking on the button “register”.

More advanced users should use a custom server, of course. In this article, I focus on the easiest way for beginners.

4. Go to your inbox and follow the instructions in the email you just received from

5. Close Riot and open it again such that you see the login mask. Type in your new credentials in the corresponding fields and click “sign in”.

6. Signing-in may take up to 30 seconds. Afterwards, it should look like this:

Now let‘s start messaging!

1. First, you need a contact you‘d like to chat with. So ask a friend to join 🙂 If you found a chat partner, click on the symbol on the bottom left of the Riot window to start a new chat:

2. A new windows opens. Here, you are asked to put in some ID to find your chat partner. For that a “Matrix-ID” is the best option to use. Your partner‘s and your own Matrix-ID has always the following format “”. For example, if you registered your account with name “bigfanofmatrix”, your Matrix-ID is “”.

Thus, put in the Matrix-ID of your chat partner. Then click “start chat”. It might take up to 30 seconds until the chat is initialized. Then you‘ll be able to start chatting to your partner!

3. Congrats! You now can start to communicate with a messenger that respects your privacy! Next, you can install Riot on more of your devices. Again, go to, download Riot for your operating system and log in with your new credentials. That‘s it!

Let‘s add encryption!

Note: As of Jan 2019, this end-to-end encryption does not work reliably. If you are a non-IT-person, I do not recommend to activate encryption for now! Messages are secured during transport. Bare with that for now.

1. Until now, your conversation is not end-to-end encrypted. Activate E2E encryption by clicking on the gear button on the top right in the Riot app:

This should open the settings page. In the top half of that page, check the box saying “Enable encryption (warning: cannot be disabled again!)”. Afterwards, click on “save” in the top right corner.

2. Next, write a text message to your partner from all devices you’ve Riot installed on, and ask your partner to do the same from all his devices.

3. Some of the messages might not be readable or include warning. In this case should see a yellow sign with and exclamation mark next to your and/or your partner‘s messages. Click on the yellow sign, which opens a new window. In that new window click on the button “verify…” at the bottom right. Finally, click on “I verify that the keys match” and close the window with “OK“.

4. If the encryption is working properly, you should see a closed locker next to your recent chat messages. If you still see the yellow sign, just repeat step 2 and 3 until you see the locker as well.
If you click on the yellow sign and do not have an option to verify keys – also repeat step 3 and 4 and also restart the app Riot. Sometimes this helps 🙂

Congrats! Welcome in the fediverse of open, free and secure messaging!

There‘s more to come!

If you‘ve followed the setup steps in this article, you‘ve probably noticed, that the Riot is not all the time as user friendly as mainstream apps like Whatsapp or Telegram are. To me, all in all these issues are minor compared to the features I get: a reliable and secure messenger. Luckily, the usability will be improved soon. In February of 2018, the project got an investment of $5 M, which should result in several improvements on the project.

I am very happy to receive feedback for improvements. Please get in touch with me by using the comments at the bottom of the article or create a Github issue or pull request using the link at the end of this article.

Now, please spread the word and let everyone else participate in a more open, free and secure future!

Edit this post on GitHub.

Leave a Reply

Your email address will not be published.

Related Posts


Whatsapp-like chat messaging that respects your privacy

This guide helps using a chat messenger on your phone that works like Whatsapp or Facebook Messenger, but which respects your privacy and freedom.


Qwant – the most interesting search engine today

The search engine Qwant currently offers the best mix of good search results, high data protection and usability without further IT knowledge.


Optimize Ubuntu 18.04 for privacy, security and usability

A tool for everyone to improve Ubuntu 18.04 – fully automized within just 5 Minutes!