# 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/#/#social:ansible.com 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.

We do have accounts on `chat.ansible.im` - however, for various reasons we cannot offer open registration to anyone. We are happy to grant an account to known contributors - please see [token-based registration](#Token-based-registration-on-chatansibleim) below.

Otherwise, the Ansible community is fully available over federation, so any other Matrix account you may have will also work. If you don't have one at all, [matrix.org](app.element.io/) is the default (and largest) server to register on.

(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!

### The Ansible Community Space

If you're just looking to find the list of Ansible Community rooms, you should head to [#space:ansible.com](https://matrix.to/#/#space:ansible.com) to see the Ansible Space. Welcome!

### Directory search

To find rooms more generally, you need to use the directory. 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/#/#social:ansible.com 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 Docs

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

## How do I create a public (community) room?

In Element:

1. Being in a space you are allowed to create rooms in (square icons on the left; for example, in matrix.org), click **+** next to the Rooms sidebar and then click **New room**:


2. In the appeared window, set the following and click **Create room**:
- room name (as it'll be seen at the sidebar and at the top when being in the room)
- its availability, for example, *Public room* (can be changed later in **Settings**)
- room address (will be a part of room's URL)


IMPORTANT: If you enable encryption for your room in settings (see the pictures below), **you cannot disable encryption in the future**. If you need to bridge the room with IRC later, you **will not be able to do it** with encryption enabled.

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


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


<!-- Spaces for padding the image -->
&nbsp;
&nbsp;
&nbsp;
&nbsp;
&nbsp;
&nbsp;
</div>
</div>

### Making your community room official

Because *anyone* can create rooms on Matrix, the Ansible Community needs a way to designate "official" rooms. You can tell an official room in three ways:

- The room has an `ansible.com` room alias as it's primary address
- The room is listed in the [Ansible Space](https://matrix.to/#/#space:ansible.com)
- The Ansible moderation bot (@admin:ansible.com) is present in the room

Official rooms are also subject to the [Ansible Code of Conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html#community-code-of-conduct) so that we can safeguard our community.

If you would like your room to be official, please contact the Community Team via *[e-mail]* - we will ask you accept the CoC, and promote the moderation bot to admin power in the room, after which we can add the alias and put the room in the space.

## 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 using one of the following options:
* [#community:ansible.com](https://matrix.to/#/#community:ansible.com) / #ansible-community on chat
* [e-mail] by email
* 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 **Create account via token**
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.

**Note that the emails are automated and likely to be flagged as spam. Look for a mail from `[e-mail]` if you think it hasn't arrived**

# New questions to answer