# Ansible Community Matrix FAQ
###### tags: `matrix & irc`

A random collection of notes on Matrix for our use. Contributions welcome, either as new questions to answer (skip to [the end](#New-questions-to-answer)) or by adding answers.

Some questions have tags:
- "Bridge" is for questions about how Matrix interacts with IRC
- "IRC" is for information for IRC users coming to Matrix

If anything is not answered, feel free to hop into https://matrix.to/#/#general:ansible.im to chat with us and ask!

# Other useful Matrix sites:

- https://matrix-help.envs.net/messaging/search/ superb walkthrough of most Matrix things

# FAQ

## How do I get an account?

Matrix is decentralised ([like email](https://blog.ergaster.org/post/20210602-matrix-for-im/)) so there are many places you *could* register.

Getting an account on `ansible.im` is still something the [community needs to discuss](https://github.com/ansible-community/community-topics/issues/41). For now, register on other homeservers - [matrix.org](app.element.io/) is the default and largest server.

(You can [self-host a homeserver](https://matrix.org/docs/guides/installing-synapse/) if you wish, but that is beyond the scope of this FAQ)

## What client should I use?

Start with [Element](https://app.element.io) as it covers most usecases fairly well, and has webchat, desktop, and mobile apps.

If Element doesn't suit you, then [Matrix has many others clients to try out](https://matrix.org/clients). You can also check out [This Week In Matrix](https://matrix.org/blog/category/this-week-in-matrix) where new clients are regularly featured.

## How do I find/join an existing room?

There are many ways!

### Directory search

Matrix can search rooms, but because of the decentralisation, you will need to know what directory to look in:

- Offical Ansible rooms are in "ansible.com"
- Wider self-organised community rooms are on "ansible.im"
- A select few rooms have a "matrix.org" alias so they can be found in the default search.


Selecting "Explore public rooms" (in two places, green center button, and in the sidebar) or clicking the "compass" next to the room filter in the sidebar will bring up the search:


If you *don't* see the rooms you want, you can click the server dropdown (that says "Matrix rooms") and add `ansible.com` or `ansible.im` as a new server. You'll then be able to see the directory from that server.


### Via Links

A person may send you a room ID to join. If you're in Element or another client that supports room links, you can join just by clicking it!

You can also use URLs - e.g. https://matrix.to/#/#general:ansible.im will take you to our new-user room, where you can ask more questions!

Finally, there's always text - sending a message (in any room) like "/join <room-id>" will work too.

### Via Spaces

[Spaces are a fairly new thing in Matrix](https://element.io/blog/spaces-the-next-frontier/) bt they are maturing rapidly. As of 2021-08-27 they are still in beta, so it is likely you are not in the Spaces Beta (but you can enable it in Element -> Settings -> Labs).

If you *are* in the Beta, you can join #space:ansible.im to get a list of all the rooms in the community space!

### Via Docs

The [Ansible Communication docs](https://docs.ansible.com/ansible/devel/community/communication.html#ansible-community-on-matrix) have a list of commonly used used, so you can join from there directly!

## How do I create a room?

In Element, you'll have a "+" next to the Rooms sidebar. If you're on the homepage, you'll see a big button as well - see both in this screenshot:


This approach works for private or public rooms.

## How do I chat with someone?

Very similar to rooms - to start a new chat you can:

- Click the "+" next to "People"
- Click on a user in a room and select "Direct Message"
- Use `/query <user id>` as a text command

<div class="bottom">
<div style="float: left; width: 50%;">


</div>
<div style="float: left; width: 50%;">


</div>
</div>

## What notification options do I have?

Matrix has pretty rich notification settings. You can choose the level notifications per-room (silent, normal, noisy) and what things get notified for at each level. Default is "noisy" for 1:1 chats (pings you for every message, and "normal" for group rooms (pings you for highlighted words and namechecks)

You can also configure Matrix to email you about messages, which may be useful if you only check your client infrequently.

## How do I set my highlight keywords?

In Element, go to Settings > Notifications and look at "Messages containing keywords" - keywords is clickable:


That will open a dialog to enter keywords.

## Do I need a bouncer? (IRC)

Nope! Matrix gives you persistence by default, so you can log back in and get your messages later, or from another client.

## How do I log in to my Libera account? (IRC)

This is only needed if you want to join a restricted (+r) room or private-message an IRC user; joining public Ansible rooms from Matrix should work with unauthenticated Matrix accounts. This process will also mean you get your op priviledges from IRC (if you have any :P)

Should you decide you need to, this is the process:

0. Log out of IRC or change your nick, so that your preferred nick is available (the bridge does not ghost users)
1. Open a chat with `@appservice:libera.chat`
2. Send `!username libera-sasl-username`
3. Send `!storepass libera-sasl-password`
4. Send `!nick preferred-irc-nickname`
5. Send `!reconnect` to relogin & check it all worked

You can send `!listrooms` to appservice at anytime to get a list of what IRC channels you are in.

## Token-based registration on chat.ansible.im

Token-based registration has been enabled on `chat.ansible.im` however the UX in Element hasn't been fully implemented, so it's not obvious how to use it.

1. To get an `ansible.im` account you will need a token. Please contact the community team to get one:
1. [#community:ansible.com](https://matrix.to/#/#community:ansible.com) / #ansible-community on chat
2. [e-mail] by email
3. Add a comment on [this GitHub issue](https://github.com/ansible-community/ansible.im/issues/3)
2. Go to https://chat.ansible.im and click "Sign In" (TODO this can be improved on our side)
3. Spot the tiny "New? Create Account" link at the bottom, click it
4. Provide username, password and optionally an email as usual
5. Click "Register"
6. You'll be taken to a similar page, but the form has been replaced with a tiny "Start Authentication" link - click it
7. A popup/new tab will be created, asking for your token
8. Provide the token given to you by the community team

If the token is valid, your account will be created and you will be logged in.

If you provided an email address in step 4, then you will get an email *before* providing the token. This means you can start the process, get a token from us, and then continue by using the link in your mail.

# New questions to answer