| 1 | # Matrix |
| 2 | |
| 3 | - Status: ??? |
| 4 | - Maintainers: @poVoq |
| 5 | - Features: ??? |
| 6 | |
| 7 | > [!WARNING] |
| 8 | > **Create a dedicated user first. It will not relay messages from yourself if you use your account** |
| 9 | |
| 10 | ## Configuration |
| 11 | |
| 12 | > [!TIP] |
| 13 | > For detailed information about matrix settings, see [settings.md](settings.md) |
| 14 | |
| 15 | **Basic configuration example:** |
| 16 | |
| 17 | ```toml |
| 18 | [matrix.mymatrix] |
| 19 | RemoteNickFormat="[{PROTOCOL}] <{NICK}> " |
| 20 | Server="https://matrix.org" |
| 21 | Login="yourlogin" |
| 22 | Password="yourpass" |
| 23 | # Alternatively, you can use MXID + a session Token + a device id |
| 24 | #MxID="@yourbot:example.net" |
| 25 | #Token="tokenforthebotuser" |
| 26 | #DeviceID="deviceidofmxidandtokenlogin" |
| 27 | ``` |
| 28 | |
| 29 | ## FAQ |
| 30 | |
| 31 | ### How to encrypt matterbridge messages to Matrix? |
| 32 | |
| 33 | [matrix.test] |
| 34 | RemoteNickFormat="{NICK} ({LABEL}) " |
| 35 | Server="<https://domain.tld>" |
| 36 | Login="yourlogin" |
| 37 | Password="yourpass" |
| 38 | SessionFile="matrix_crypto.db" # sqlite database file used to store the login session persistently |
| 39 | PickleKey="yourreallylongandcomplicatedpickle" # a long password to use when accessing the session store |
| 40 | RecoveryKey="this thing isss real long bubb" # your account recovery key from matrix for this account |
| 41 | MxID="@yourusername:domain.tld" # your mxid from the logs |
| 42 | Token="your token from log output" # your token from the logs |
| 43 | DeviceID="yourdeviceid" # your deviceid from the logs |
| 44 | |
| 45 | #### Steps for getting an encrypted connection working |
| 46 | |
| 47 | MxID, Token and DeviceID are required for encryption even though they are optional normally |
| 48 | |
| 49 | 1. Generate a recovery key using your preferred Matrix client for your account and make sure to store it for later |
| 50 | 2. Fill in the following |
| 51 | |
| 52 | - RemoteNickFormat (Optional) |
| 53 | - Server |
| 54 | - Login |
| 55 | - Password |
| 56 | - SessionFile (make sure this is readable and writable by the bot's run account) |
| 57 | - PickleKey |
| 58 | - RecoveryKey |
| 59 | |
| 60 | 3. Start your bot and log in making sure to keep a log or watch output |
| 61 | 4. Copy these from the logs in to your configuration file |
| 62 | |
| 63 | - MxID |
| 64 | - Token |
| 65 | - DeviceID |
| 66 | |
| 67 | 5. Restart the bot and enjoy encrypted messaging |
| 68 | |
| 69 | ##### Notes |
| 70 | |
| 71 | - If you enable encryption on a channel after enabling encryption on the bot, you may need to regenerate your RecoveryKey, Token and DeviceID before the bot can send encrypted messages |
| 72 | - If Matterbridge was present before encryption was enabled on a channel, it will not initialize crypto correctly and will continue sending unencrypted messages. |
| 73 | 1. Kick the bot from the room or leave the room with the bot's account (e.g in Element or some other client). |
| 74 | 2. Re-invite the bot to the room. |
| 75 | 3. The bot will get the encryption flag and start sending encrypted messages. |
| 76 | |
