📗 Matrix and Element / Riot Manual

Documentation & Support Collaboration
,
1

We use the Matrix instant messaging system at Edgeryders for collaborating among our teams on projects. This wiki documents how to use your Matrix ID for communication with the most common Matrix client software “Element” (formerly called “Riot”).

Content

1. Getting a Matrix account

2. Logging in to Element

3. First steps with your Matrix account

4. Advanced topics

5. Edgeryders’ Matrix addressbook

1. Getting a Matrix account

As a collaborator on an Edgeryders project, you’ll need a Matrix account (or more formally, a “Matrix ID”). It’s simple:

  1. Create an edgeryders.eu account. Because your Matrix account username will be the same as your edgeryders.eu username.

  2. Ask @matthias to create an @username:edgeryders.eu Matrix account for you. Ask by direct message here on the edgeryders.eu platform, or by e-mail to matthias@edgeryders.eu. You will receive your password to your e-mail address.

How Matrix IDs look. Matrix IDs have the form @localpart:domainpart.tld. Similar to e-mail addresses, they have a “localpart” and a “domain part”. The punctuation is a bit different than in e-mail addresses to avoid confusing them. For Edgeryders, we are running our own Matrix software on our own server, so the “domain part” is always edgeryders.eu. The “localpart” is always the same as your edgeryders.eu username (in all-lowercase).

Do not use a federated Matrix account. To collaborate on Edgeryders projects, please get a @username:edgeryders.eu account as instructed above. Because we disabled federation, it is not possible to get an account at a different Matrix homeserver (such as :matrix.org, available for free) and to use that to participate in Edgeryders’ Matrix chats. The reasons for us disabling the federation features are:

  • There are still some bugs in Matrix for presence notifications across federated servers, which means users with an :edgeryders.eu account may not see people with :matrix.org accounts as online, and vice versa.

  • Chat messages in rooms with users from different Matrix homeservers are permanently stored on these multiple homeservers, not just on our own. This is a privacy / confidentiality issue (possibly even clashing with the GDPR), except if we would consistently use end-to-end encryption to enforce that these messages are stored in an encrypted manner. However, there are still some software issues with end-to-end encryption in Matrix and it is generally annoying to use, so it’s not advisable to do this for cases like this where we have the alternative to keep all messages confined to our server.

2. Logging in to Element

In the browser. We have an own Matrix server running and disabled federation with other Matrix servers, so all your messages are saved only on our own server. However, we do not have our own application installed to actually use Matrix. Instead, you can use the free and open source software “Element” to communicate over Matrix.

You can log in as follows (normally you never log out, so this is a one-time thing per browser):

  1. Open this link in a new tab: Element

  2. Choose: “Sign in with: Username”.

  3. Enter your username in the form @username:edgeryders.eu , as found in the e-mail you received or in our “Matrix addressbook” below. You can not use your e-mail address for login because of the way we have set up our Matrix server.

  4. Press Tab or click into the password field. The software will now automatically change and fill some fields, so that you should see a message “Sign in to your Matrix account on edgeryders.eu”. See under “login issues” below if you don’t have that message.

  5. Enter your password (as received in the e-mail from @matthias).

  6. Click on Sign in.

Login issues in the browser.

  • “Invalid homeserver discovery response.” If you see that error message, and the login screen still shows “Sign in to your Matrix account on matrix.org” instead of “Sign in to your Matrix account on edgeryders.eu”, then your browser cannot figure out on which server your account has been registered. Try the following steps to fix this:

    1. Disable Privacy Badger. Privacy Badger can prevent you from logging into the Matrix server. This issue was reported with Firefox Quantum 69.0 (64-bit) for Mac and Privacy Badger 2019.7.1.1. The problem went away after disabling Privacy Badger for the element.io website.

    2. Disable other privacy enhancing extensions. It is possible that adblockers or privacy extensions like Ghostery block the requests to edgeryders.eu and matrix.edgeryders.eu for login. Try disabling these extensions on element.io, or first try if login works in a private window / incognito mode (where extensions are typically disabled already).

    3. Enter the homeserver manually. This should always work, but is another manual step during login. After the message “Sign in to your Matrix account on matrix.org” click the link “Change” an in the field “Homeserver URL” enter https://matrix.edgeryders.eu:8448 . Enter the URL exactly as given above. Even a small deviation like a trailing slash will make this fail, which is an issue we have reported.

  • Firefox login issues. Generally, Element works in a recent Firefox browser. However, if login does not work in Firefox using the normal procedure above, try it in a Firefox Private Window instead (see issue #11844).

On a smartphone. To be available on the go, you probably want to install a Matrix client software on your smartphone as well. For that, the Riot.im software is also available as mobile apps for Android and for iOS.

Here is the login procedure for the Android app:

  1. Open the installed app, called “Element (Riot.im)” on the app icon.

  2. Click “Get Started”, then click “Log in with Matrix ID”.

  3. Enter your username in the form @username:edgeryders.eu, as found in the e-mail you received or in our “Matrix addressbook” below. You can not use your e-mail address for login because of the way we have set up our Matrix server.

  4. Enter your password (as received in the e-mail you received from @matthias).

  5. Click “Sign in”.

3. First steps with your Matrix account

After log in, here are some first steps to do in the Matrix software:

  1. Accept the invitations. Your Matrix account has already been invited to one or several rooms by the admin who created your account. So, please accept the invitation on the left side of the screen (when using Matrix in your browser). Attention: The “Campfire” is a public socializing corner where we invite everyone from Edgeryders and our networks with a Matrix account. So please don’t put anything even remotely confidential there :slight_smile:

  2. Adapt your account settings. Click the gear icon in the left bottom part to go to your account settings. There:

    1. Connect an e-mail address. (Note: For now, it will be possible to find your Matrix account under this e-mail address on the vector.im identity server, so use one that you are ok with for this purpose.)

    2. Change your password – this is important, because the one above was not safely transmitted via e-mail. Instructions: (1) first connect an e-mail address, as mentioned above, (2) change the password in the account settings, (3) click the confirmation link in the e-mail sent to your e-mail address, (4) after the confirmation “password successfully changed”, ignore the warning about exporting and reimporting keys since you have not sent or read any encrypted messages by now.

    3. Change your display name – also important, because important functionalities like mentions and invitations do not work as well if you do not do this. By default, you will appear as “@username:edgeryders.eu” in chat logs and as room name of your direct chats, which is ugly. We propose to set the display name to your localpart, so just “username” in this case, to keep things simple. Due to a software bug, you can’t do this in one step yet. So change the display name to something else first, close the settings, then reopen it again and change it to the localpart of your Matrix ID (with lowercase first letter, please!).

    4. Add a profile picture.

    5. Enable e-mail notifications. There is an option in the account settings to do this for the e-mail address you just connected to your account. You will then get e-mails about messages received while you were offline / unresponsive.

    6. Enable @all notifications. To get everyone’s attention in a long-running team chat where most people have set the notification level to “Mentions only”, this is a nice trick. In line “Notifications → Messages containing keywords”, click on “keywords” and enter “@all” (without the “”). Confirm, then set “Messages containing keywords” to “Noisy”. You’ll see a red message and get @mention equivalent notifications when somebody types @all.

    7. Enable “New Composer & Autocomplete”. (Optional.) To get nice but “experimental” buttons for adding simple formatting to your messages, and for adding emojis with autocomplete after typing a colon “:” and a keyword.

    8. Reduce the default notification level to “Mentions only”. This is ok for a team chat if you want to reduce notification frequency. You’ll still see red bubbles with “new messages” counters in chats so you can catch up, but you will only get notifications (little desktop overlay window, sounds, e-mail message) for your @username mentions and for @all. To set this up, mouse over the “Open Village MENA: Team” room in the room list, click the “…” on-hover button and choose “Mentions only”.

    9. Mobile app: Shorten the “sync request delay” time. In the Android mobile app, this is done under “☰ → Settings → Delay between two sync requests”. The default value is 600 s. Set it to around 60 s instead. Otherwise, you would get all messages 10 minutes (!) after they are sent in cases when Matrix is not the Android foreground app. And that probably includes “when the screen is locked or off”.

4. Advanced topics

4.1. Formatting your content

Formatting messages. Matrix messages support basic Markdown syntax for formatting – see the complete syntax reference. Some is also available from buttons after enabling the “New Composer & Autocomplete” option in your account settings. Some is not, for example the code for proper hyperlinks: to create a link like this, you would write this text into your message: [like this](http://example.com/).

Emojis. With the “New Composer & Autocomplete” option enabled in your account settings, you get emoji auto-complete after typing a colon “:” and the start of an emoji’s name. The complete list of named emojis is available in an emoji cheat sheet and the emoji codes reference. (Images may look slightly different though, as Riot uses an EmojiOne emoji font in a different version, probably the last fully open source version EmojiOne v2, here on Github.)

  It is even possible to include emojis into your display name – they will show up as little colorful images whenever your username is displayed. You configure this either by putting the equivalent Unicode character (like the one for “ghost”) into the “Settings → Display name” field. Or by doing the same with a slash command and the emoji code in a message: /nick someword :ghost:. This also means that when mentioning your display name, the emoji has to be included for a mention notification to work! Not a problem when only appending the emoji to a normal text username, as people can use autocomplete for mentioning. And esp. not a problem when keeping the textual part of such a username the same as the localpart in @localpart:edgeryders.eu, as then the mention will also work when somebody omits the emoji, as it’s still a valid Matrix ID, and mentions also work for these.

4.2. Posting pictures and files

Sharing images and other files. It is possible to share any files to a chat room, using the “Upload File” button in the message editor. Uploaded images will be displayed inside the chat, other uploaded files will be offered for download. When the chat is end-to-end encrypted, the files will also be saved encrypted on our server, in which case nobody outside of the chatroom (not even the server admin) can access their content. Please delete the messages with large files (>1 MiB) after the other people in the chat downloaded them. It will help us keep the backup sizes small. Even better is to upload the files to a shared folder (like, Google Drive) and to only post the link to them in the chatroom.

Posting images from the clipboard. It is possible to post images to a chatroom from the clipboard, which is faster for sharing images than to save an image from the browser to a file first. Tested with Chrome / Chromium 60. Instructions:

  1. In your browser, right-click on the image you want to share in the chatroom.
  2. Click “Copy image”.
  3. Right-click in the Matrix chat message editor and select “Paste” (or just press Ctrl+V while the keyboard focus is on the chat message editor).
  4. A popup window will appear asking if you want to upload the image from your clipboard to share i in the chatroom. Confirm that.

4.3. Getting people’s attention

Getting people’s attention. We’ll have to experiment to find best practices for a long-running team chat without constant notification spam. The current proposal is this one though: Assume everyone in the project team chat has notifications set to “Mentions only” for this room. They will probably catch up with all messages at some time, but you can’t rely on that. So use mentions to get their attention – username, Username, @username and @username:edgeryders.eu all work and produce a red message on the receiver’s side, and a notification (desktop notification, sound, e-mail after 10 minutes). Please note: when you try to mention someone who has not changed their default display name, autocomplete will not work, and you will have to type the whole @username:edgeryders.eu.

  When you really need the attention of everyone in the chat, in theory you can use @all to the same effect. This assumes everyone made the required keyword notifications setup as described above, which in practice will be a completely wrong assumption.

How e-mail notifications work. After setting up your Matrix account as instructed above by connecting your e-mail address and enabling it as a notification target, you will receive e-mail notifications about Matrix messages you received while offline, or that you rceived but did not yet read in your browser / mobile app. Quite similar to how it works with Facebook messages. In more detail, the timers work like this for each Matrix “room” individually (however if any e-mail is sent, it will include all accumulated e-mails from all rooms!):

  1. A first e-mail is sent 10 minutes after you received the first message while offline, or after 10 minutes of not reacting to browser / phone notifications.

  2. A second e-mail is sent 10 minutes after the first if there are any new messages since the first one.

  3. No new e-mails are sent for the next 12 hours, after which this whole three-step timer process is started again.

4.4. Creating and managing rooms and chats

Creating rooms. It is advisable to always create rooms, even if you only want to chat with one person. For that, click + next to the section title “Room”, click “Create new room” and in the settings screen that appears set “Enable end-to-end encryption: off”. Unlike chats create in section “People”, rooms allow to disable encryption, so you will not have to deal with cross-device key requests, key backup, inability to read old messages and so on.

  The difference of chats created in section “People” is that these chats treat every message as if it contained a mention, so the person you are chatting with will see the notification of every message you send. However, you can achieve the same in rooms by hovering over the room name in the element.io room list sidebar, clicking on the bell icon, and setting “Notification options: All Messages”. That affects only notifications to you, so your chat partner would have to do the same on their side.

Inviting people to a room. Once a room has been created, you will need to invite people to join it. Click on the room from the list on the left, then click the “Invite to this room” icon on the bottom right of the window. Invited people appear in a list on the right side of the window. Please note: when you try to invite someone who has not changed their default display name, autocomplete will not work, and you will have to type the whole address as @username:edgeryders.eu.

Customizing rooms. Click the cog icon next to the room name to change the settings. We recommend to upload a nice avatar for it: you can do so by clicking the camera icon under the avatar (the default avatar is a circle with the first letter of the room’s name). The camera icon is only visible after clicking on the cog (settings) icon. We also recommend you set a color for the room that is in line with the avatar. This way, people have a visual cue as to which room they are writing in.

Room administration actions. As a room’s administrator, you have the options to “mute”, “kick” and “ban” users, also accessible with slash commands of the same name:

  • “Mute” means the user stays in the room and can read but not contribute any more.

  • “Kick” is forcing a user to leave the room, just as if they had chosen the “leave” action by themselves. Means, they can re-join at will (if it’s a public room) or when invited.

  • “Ban” means a forced leave, and the user is prevented from re-joining until the admin uses an “unban” command.

Getting more help. The “official” documentation of the Riot client to Matrix, which we use, is here.

4.5. Voice calls, video calls, screensharing

Matrix includes functions for voice and video calls. The one-on-one calls work pretty well, and you can just use them. But the conference calls feature is not mature at all and will not be finished, so we use Zoom and sometimes Google Hangouts for group / team calls etc…

Fixing “Could not connect media”. In case a one-on-one voice or video call does not work for you with an error message “could not connect media”, try the following:

  1. Simply try calling again. Usually, this happens due to intermittent network failures, esp. network congestion, either in the local wifi networks or the WAN / Internet. Otherwise:

  2. Don’t use Firefox on Mac. Currently (2020-01), voice calls are not possible with the Firefox browser on a Mac OS X operating system. If that’s your case, switch to Chrome (or Chromium, Ungoogled Chromium or the like) for these calls.

  3. Disable P2P connections. Click the lower-left gear icon to go to the user settings screen, and there enable the option “VOPI: Disable Peer-to-Peer for 1:1 calls”. Both parties of a call have to do this before the call. This should work around firewall issues that can prevent direct connections between computers on the Internet; such issues can happen when you are in a university network or other heavily managed / protected network. (However, this tip is experimental. Tell in the comments below if it helped.)

Screensharing. Matrix / Riot supports screensharing in calls, but like voice and video calls it is only properly usable for one-on-one calls. It works with recent Firefox and Chrome versions like this:

  • If the screen-sharing user’s browser is Chrome (or Chromium), he or she has to start it with a special command line option (details). For example:
    chromium-browser --enable-usermedia-screen-capturing

  • In the Riot web application, press the “Shift” key and then click the videocall button.

  • Confirm you really want to share your screen. (More on screensharing safety.)

More details about this process here. It works well when screen-sharing from Firefox or Chrome, and receiving in Chrome (should also work in Firefox, but it had issues at times).

4.6. Voice messaging

When communicating over a low-bandwidth Internet connection with undependable quality, voice calls in Matrix / Riot or otherwise will not be of much use as it will be hard and often impossibe to understand each other. Here, sending voice messages back and forth in a Matrix chat is a nice solution.

Voice messages are just audio files uploaded from the local computer. Those in formats MP3, OGG and WAV (and perhaps more) will then get an embedded player right in the Matrix chat. For the file format, we here go for Vorbis files (.ogg) at the lowest quality (0), which means 64 kbps and results in a file size of ca. 360 kB per minute when using one audio channel. That audio quality is good for voice messages, file size is as well compact.

So we only need an efficient workflow to record and upload these audio files, and we’re good to go – see the instructions below.

Remaining issues. In the setup as documented below, a few issues remain:

  • Navigation in the soundplayer embedded in Riot does not work. Probably a normal bug. You can download and open the file in another soundplayer to fix this.

  • For uploading voice messages or any other files >2 MiB, a configuration change to our Matrix server is needed.

1. Voice messaging under Linux

Installation and configuration:

  1. Install audio-recorder (instructions).

  2. Start audio-recorder with the command audio-recorder.

  3. In the “Additional Settings → General” screen, disable “Window always on top”.

  4. In the “Additional Settings → Recording Commands” screen, create a OGG recording command with:

    • Title: “Voice message, lossy, 64 kbps”
    • File extension: ogg
    • Command: audio/x-raw,rate=44100,channels=1 ! vorbisenc name=enc quality=0.0 ! oggmux

  5. Using the corresponding option in your window manager, send the window to a specific desktop to prevent it from showing up on all at once.

  6. Create a bookmark in your file opening dialogue for the directory where audio-recorder stores its recordings.

Usage:

  1. Make a recording in audio-recorder by pressing start and stop. It is saved automatically.

  2. Click the “file upload” dialogue in Riot to upload the recorded file.

  3. Use your bookmark to navigate to the directory with the recordings and choose the newest one.

More documentation:

  • For audio-recorder: open this URL in your browser (tested on Ubuntu 17.04): file:///usr/share/audio-recorder/.

  • For the options of GStreamer vorbisenc, see here.

  • For the quality values of GStreamer vorbisenc: 0.0 - 1.0 correspond to 0 - 10 in the official Vorbis standard – source.

2. Voice messaging under Windows

Installation and configuration:

  1. Visit the Github project “Instruction Guide: fmedia under Windows”.

  2. Download the project as a .zip file, as shown here:

    Capture.PNG999×332 30.3 KB

  3. To unpack, install and use the software, follow the installation and usage instructions in the project’s README.

4.7. Sharing login credentials and other secrets

The advised and safest way to share login information of Edgeryders’ accounts for external platforms (e.g. GMail, Twitter, Zoom) is to send it in Riot as follows:

  1. Make sure receiving party is on the Edgeryders Matrix server: mouse over their avatar to show the address and make sure the address ends in :edgeryders.eu.

  2. Start a personal one-on-one chat for this purpose.

  3. Enable encryption for this chat in the chatroom’s settings.

  4. Send the login credentials or other secret information.

  5. Remove the message after the other party confirms they got it. You find that option in the … menu of a message, which appears when mousing over it.

In fact this mechanism is much safer than sending a password by (unencrypted) e-mail: it is encrypted by HTTPS and by end-to-end encryption, stored in encrypted form, and is deleted after use from our server, with no copies ending up on other servers. (The latter is why this process should only be used for @username:edgeryders.eu Matrix IDs.)

4.8. Resetting your password

Due to the way how our Matrix server is set up right now, your Matrix ID is independent of your e-mail address. You also cannot connect it to your e-mail address yourself – the corresponding feature under “user menu → All Settings → E-Mail Adresses” simply does not work.

Consequentially, you cannot reset your own password. Ask @matthias to do so if you need it reset.

4.9. Other tips and tricks

Fixing online status issues. If you see somebody posting while they are shown as “offline” in your Riot application’s sidebar, it is usually because they are posting from a device you did not verify. Click on their user avatar icon, and verify the device they are currently using, or all devices. Do it either “the right way” (confirming in a voice call that the keys match), or just click “verify” if you don’t care about encryption integrity in this chat.

Slash commands. Similar to good old IRC, Matrix supports some commands. With the “New Composer & Autocomplete” enabled in your account settings, type a slash “/” at the beginning of a message, and choose from the proposed commands. Most are useful for admins only. The riot.im/app/ stable version provides 8 commands at this time, while the riot.im/develop/ development version has 19.

Using the Riot.im “develop” version. While riot.im/app/ provides the main / stable version of the Riot software, there is also a development version available at riot.im/develop/. It will share a login with the main / stable version, so you can use both in parallel without having to log in again. The develop version is always some days or weeks newer than the main / stable version, so some bugs will be removed and perhaps some new ones will be introduced. Use if you’re an optimist :slight_smile:

5. Edgeryders’ Matrix addressbook

Currently, the following accounts exist on our Matrix server (and some more, but just because this list needs some updating …):

5 Likes
6

I think we already need this in the Help and support cat. We are using the Matrix for MENA, but also for the team and basically for everything operational. Agree?

7

Agreed, and already re-assigned to the “Documentation” cat :cat2: now.

9

I am so embarrassed to ask this, but I had cleared stuff in my browser lately and now cant remember my password for riot.
When requesting a new one I get:

Error
Failed to send email: This email address was not found

Help?

10

Just made you a new one, check e-mail (and change it again after login).

Re. your e-mail adress for the account, it seems it has not been properly registered before for notifications etc… Probably because of the bugs in the older versions. Try again after login, adding the e-mail address should work properly now.

1 Like
11

Thanks <33

12

was wondering if anyone is using Android version of Riot, I finally got an android phone as my old windows phone finally died, RIP,but I can’t find the log in via matrix id page. only via email, I tried using my notification mail or matrix id in this field but doesn’t work.

so if anyone got this running can you write some instructions about this.

thanks

2 Likes
13

@anu, you got this to work right? Could you add instructions to the manual about it?

1 Like
14

Sure @matthias :slight_smile:

15

Hey @hazem. Yes I have been using Riot on my android phone and will update the instructions :slight_smile: Thanks

16

Hello @hazem I have updated instructions about logging in Riot for android :slight_smile:

2 Likes
17

I use Riot for Android, @hazem. It works like a charm.

I only had to log in the once, but I remember it was exactly the same as on the desktop, with the nondefault server.

18

Using Riot on both Ubuntu and Android as @gregoiremarty

19

@gregoiremarty’s message brings a question to mind: does our Matrix interoperate with the Riot matrix? Could we invite him to one of our rooms? (@matthias).

20

Yes, that works. We can invite him as @gregoiremarty:matrix.org . The only issue I have seen with this federation feature so far is that the online status notifications are not always accurate.

21

It works yes. I was actually talking to @unknown_author today and he has an edgeryders.eu matrix account while I’m on the main matrix.

2 Likes
22

Thank you @matthias for setting me up and making it so clear in the manual

23

Hei I have cleared data from by browser and now I can’t seem to be able to login with Riot.

Neither it recognizes the edgeryders homeserver, nor my username (if I use matrix.org server). Can you help @matthias? thanks.

24

Hmm yes, confirmed. There is some interference with the ongoing installation of Natalia’s Edgeryders form builder software. I’m going to have a look now and fix it …

1 Like
25

@noemi: It’s fixed. Riot login works again now (tested it …).