Getting Started with Matrix

In my last two posts, I set out the arguments for Matrix, and gave some data to back that up. In response, some new users have tried Matrix and offered feedback. Huge thanks to all of you - I’ve been a Matrix user for years, and I no longer see the rough edges, so your feedback is invaluable.

There have also been a lot of questions, especially from folks used to IRC, so in this post I want to look at the basic operations of Matrix, and give some guidance to folks from other platforms. I’m going to break it down into 3 areas:

• Common Matrix-native tasks
• How the bridge to IRC works and how you interact with it
• Things from other platforms you might be looking for

Before you read any of this, go read Thibault Martin’s blog on how Matrix is very (very!) similar to email, and how you can use your understanding of email to understand Matrix. Go on, I’ll wait.

Done? OK good, let’s dive in. The Get Started docs from Element and other resources cover most of this material, but I’m going to do a complete walkthrough. Bear with me if this seems basic at times :)

Getting started with Matrix

Before you can use Matrix, you must get two basic items: a Matrix account and a Matrix client.

Getting a Matrix account

As with email, you could register with any number of public Matrix homeservers, but to keep it simple, I suggest you stick to matrix.org. I won’t screenshot the registration process - it’s the standard “give an email address, pick a username/password, verify the email address” flow for internet registration.

Getting a Matrix client

As with email, you have quite a few options for clients that interact with Matrix! Of course, that doesn’t help if you don’t know how to choose between them - The Paradox of Choice is a thing, after all.

I recommend Element. It’s not for everyone, especially those more used to a commandline / text-only interface, but it is polished, feature-rich, and well supported. For bonus points, Element is available as a webapp, a desktop application (via Electron), and on Android/iOS as well.

Interacting with Matrix

Once you are registered, and signed in on your client-of-choice (possibly at the same time, if you continue using the browser tab you registered with) then you can look around.

Joining / creating a room

Depending on where you registered, you might be placed in some rooms automatically. If you already see some default rooms, those are good places to ask questions if you get stuck!

If you haven’t been placed in any rooms, you will something like this:

This is my bot’s account (I use it to notify myself of things). You can see I’m already in a private chat with main account. I’m not in any rooms, so that list is empty, but there’s a handy message to get me started, as well as 3 big green buttons in the middle.

If you click “Explore Public Rooms” you’ll get this:

And then you can use the search and click Join when you find a room you want to join. What about creation? If you click “Create” instead then you see:

Which lets you create public or private rooms. You can then invite friends (via Matrix, email, or link sharing) and get started chatting. A similar process works for 1:1 chats, except instead of a room name, you put in the account of the person you want to chat to.

Note: Matrix supports slash-commands too, so if you know the room you want, you can use /join <room id> just like you would on IRC. You can use /query <user id> to start a 1:1 chat too.

Finding Matrix rooms

A question I’ve heard a lot is “How do I find the Ansible rooms?”. It’s true - most are not listed in the default Matrix.org search. Why? Because of decentralisation. There’s no central directory of email addresses, remember, and Matrix is a lot like email. It isn’t easy to build a directory of every Matrix homeserver out there. Look closely at that screenshot again:

The default search is looking for rooms on Matrix.org. We need to tell it to look elsewhere - which you can do by expanding that dropdown and selecting “Add new server” and entering (in our case) “ansible.im”:

And lo! Ansible rooms appear. Side note, though: Most Ansible rooms have a Libera.chat name too, and Libera is one of the default search places (you’ll see it in the dropdown) so you can use that too. If you’re struggling getting the Ansible directory configured (or with anything else!), then join Ansible Chat and ask :).

Matrix and IRC: compare and collaborate

OK, so now you can find friends, join rooms, and chat on Matrix. But wait, there’s more!

Persistence

As you probably know if you’ve dabbled in IRC, by default IRC is not a persistent protocol. If you disconnect (you close your laptop, your internet goes off, etc.), then you leave all your IRC channels. This lack of persistence is annoying, especially for folks looking for help - they post a question and then never see the reply. Folks often deploy a bouncer (or pay for one, such as IRCcloud) to keep them connected when they’re not at their desk, but it’s extra overhead, and many new users don’t know they can (or need to) do this.

Matrix is persistent - you remain in your rooms when your client is closed, and can pick up your messages when you next get a chance to check. You can even configure Matrix to email you if you get notifications!

If you are happy with IRC, you can continue using it to participate in the Ansible community. Read on to discover how Matrix and IRC interact.

The Matrix-to-IRC bridge

Most of the Ansible rooms on Matrix are bridged to Libera.chat IRC. Messages on IRC show up in Matrix. Messages on Matrix show up on IRC. Matrix users and IRC users are in the same space, and that’s good. It allows us to expand our community without losing users who are happy on IRC. IRC has been around a very long time, and it has a lot of supporting tools, etiquette, and expectations. But some of the Matrix features are not supported on IRC. Here’s how the two platforms interact.

How Matrix messages display on IRC

We want to make use of Matrix’s feature set (otherwise what’s the point?), but we’d like our community to be harmonious for anyone who chooses to use IRC. Matrix, like most modern chat platforms, offers the ability to edit, to reply, to react, to post images, and to post long lines of text. The bridge does its best to display these messages on IRC.

Edits

Edits are useful. While typos are irritating, when we post something accidentally misleading, we should correct the record. IRC does not support edits, however, so what happens in a converation that’s happening on both Matrix and IRC?

On Matrix:

On IRC:

The bridge reposts the whole line to IRC, with an asterisk prepended. That’s pretty clean, but for very long lines, it’ll get quite cluttered, as will repeated edits to a single line. I want to encourage edits, as I think they matter, but please be considerate to IRC users when editing.

As an alternative, consider using an asterisk and the fix - in this case I would send * without to the room.

Replies

A busy room can get complicated. Matrix doesn’t do threaded messages (yet), but it does have replies, and that can keep the flow of one part of the chat moving along. Again, IRC does not have this, so how does it look?

On Matrix:

On IRC:

Again, the bridge reposts the line, with a name-check on the previous user. Fairly sane, and if replying to longer lines, it reverts to a simple namecheck:

Reactions

Matrix supports reactions - adding emoji to messages. This is a small thing, but functions as social glue when tone-of-voice, body-language, and other cues are not available to us. Sadly, IRC has no way to interpret reactions, so the bridge does not relay them. Be aware that your reactions will only be seen by other Matrix users, and that reacting to an IRC user will likely not be noticed (at least by the author).

Long lines, images, and other content

Matrix supports any length of message, as well as images and other content. IRC has a line limit and displays only text.

By default IRC truncates long lines - a practise that I find somewhat hostile. I have seen users get bad advice because what they wrote and what the rest of the room saw were not the same thing. You have to work really hard to hit this on Libera.chat - I was up to 500 words (3412 characters) in a single line before I triggered it. However, it still happens occasionally.

When a Matrix message hits the IRC line limit, the bridge turns the long posts into pastebin links (something IRCcloud does too, I believe). So you may get something like this:

For shorter messages, if there are line breaks, the bridge posts them as separate lines of IRC text, to make it more readable. For me, the balance here is pretty good, but your experience may differ, and I want to hear about it if it’s causing problems in the Ansible rooms.

Likewise, images and other content from Matrix will show up in IRC as links:

It would be nice if I could caption my images during the upload, as this could be carried over to IRC to contextualise the upload (right now, IRC folks would have no idea why they shoud click on that link). This would be an accessibility win too, I think, since alt-text for images is a big deal.

So that’s how the bridge behaves, and mostly I think it’s sane. Edits are my biggest concern, as a repeated set of edits is hard to represent on IRC, and yet we cannot disable it over the bridge for fear of having divergent history. It’s something I think we’ll have to solve through etiquette and teaching our new members about.

Choosing your IRC nickname from Matrix

Matrix users choose their nicknames on Matrix, not on IRC. So how do those nicknames show up in IRC? The choice of nickname (on any platform) is obviously highly personal. By default, the Matrix bridge takes your Matrix display name and adds [m] to designate the Matrix origin. If you don’t like this, you can change it: start a chat with @appservice:libera.chat and use !nick YourNick to change your IRC nick display.

Authentication to IRC from Matrix

The Matrix bridge has no way to know of any IRC account you may have on Libera.chat, so when it connects you to IRC by default your user is unauthenticated. That has two consequences:

• Unless you authenticate on IRC, you cannot join rooms that require registration (to prevent spam)
• Unless you authenticate on IRC, you cannot send private messages to other IRC users (the Libera default)

If you encounter either of these situations, your Matrix client will give you an “err_needreggednick” error (i.e need registered nickname). You can create an authenticated IRC user from the Matrix bridge. The bad news is that it needs a Libera account (no way around that), but the good news is that it needs just a few commands in the right places to achieve.

You can follow Libera’s docs on registration in an IRC client if you wish - but since this post is about getting Matrix users set up, I’ll do a Matrix version here. To register on Libera.chat from Matrix:

1. Start a chat with @appservice:libera.chat (the bridge) and @NickServ:libera.chat
2. Send !nick YourNick to the AppService chat to set your preferred nickname on IRC
3. Send REGISTER YourPassword youremail@example.com in the NickServ chat
4. When the email arrives, send the token in the NickServ chat VERIFY REGISTER YourNick TokenFromEmail

If you want the bridge to automatically reconnect after restarts/netsplits (you likely do, but not everyone is comfortable storing their password on the bridge):

1. Send !username YourNick to AppService which stores your SASL username
2. Send !storepass YourPassword to AppSerivce which stores your password
3. (optional) Send !reconnect to AppService to test that reconnects work as expected

It’s awkward, we’re trying to get away from NickServ, and yet here we are. I don’t want us to use this kind of channel restrictions in the Ansible IRC channels (there are other ways to mitigate spam on IRC), so this should only be needed in the Ansible community if you need to private-message an IRC user from Matrix. If you encounter this issue in a public Ansible channel, please let me know.

(Note: the bridge cannot currently handle usernames with special characters like underscores, at symbols, etc. Current advice from the Libera team is to group a nick without these characters to your account and then authenticate with that - the nick command can use underscores, so you can switch to your preferred nick after auth. Contact me if you need help with this in the Ansible community.)

How Matrix compares to Slack and other platforms

Now you know how Matrix compares to IRC; how does it compare to Slack, Discord, and other platforms? I don’t know all the details, because I moved from IRC to Matrix and never looked back. But there are two main differences I do know about.

Unlike Slack, Matrix does not support threading, though I believe it is planned, so watch this space. I personally dislike threading in Slack, sooooo I may not hold my breath :P.

Also unlike Slack, Matrix is federated, which means you can use the same account to join rooms on multiple Matrix instances. Personally, I find that a bigger win for interacting with multiple communities than the Slack approach of having many accounts and a UX that handles many accounts.

What else?

So, what did I miss? I’m happy to revist this post and add more to it, just tell what you would have liked to know when starting out on Matrix! I’m @gwmngilfen:ansible.im, but I prefer to get private messages from people I know, so come say hi in #general:ansible.im first!