Click "Edit" to choose your preferred Matrix homeserver if you have one, or host your own.
To learn more about homeservers, please visit matrix.org. From here, please enter a username, password and email address and **click Register**. Alternatively you can register with your existing Github, Google, GitLab, Facebook or Apple account. Once prompted, please read the Terms and Conditions and **click accept**. An email will be sent to your inbox to **verify your email address**, please follow the steps in the email to complete your registration. **Now you can login** Enter your email or username and password then click **sign in / log in**. From here you will be taken to Home, where you can start exploring! ### Secure backup Secure backup is an important safeguarding step to take, to ensure you never lose access to your encrypted messages and data. When setting up your account, a message will appear which prompts you to do so. If you missed the prompt you can set this up from within your security and privacy settings. 1. Click continue to start this process. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690986359791.png) 2. Choose a memorable security passphrase or security key (for file store). This will create an encrypted backup on your server that only you can decrypt. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690986370111.png) The next time you login on a new device or session, simply enter the passphrase or key to verify your session and you’ll have access to all of your data. ### Device Verification Device verification is optional and allows you to verify who you’re talking to. 1. Click the Avatar the person you would like to verify, in the room header or after clicking the information icon. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690986507929.png) 2. This will bring up their information and options, including one named "verify". [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690986496971.png) 3. Once accepted, both you and the other user will have a set of emoji s appear on screen. We recommend comparing these in real life or over a video call to ensure you're verifying the right person. If these match, click accept and a green shield will display. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690986525234.png) ### Verify an additional device To add your additional device please log into the Element app. You will be asked to verify this login on your existing device. This is an important step as it’ll allow other people to see that the new login is really you. 1. Click Accept on your desktop app to start the verification process. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690986711135.png) 2. Next you will be asked to either scan a QR code with your mobile camera or compare unique emoji's. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690986725088.png) 3. A green shield will show once the process is complete. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690986741835.png) 4. To manage your verified device, go to Security & Privacy in your settings where you can see all devices, rename or sign out of them. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690986853305.png) # The Left Panel [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690986917256.png) Organize your chats into spaces, people, rooms and favorites. ### A. Your Profile Update settings such as your display name, profile picture, language and password. Here is also where you manage notifications, security and privacy, and general settings about your account.Access settings by clicking on your profile picture (Avatar) at the top left, from there select "All settings" and then "General".
[](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690987155444.png) Here you can update settings such as your display name, profile picture, language and password. You can also manage notifications, security and privacy, and general settings about your account. **Avatars** are selected on the General tab. This is what will show as your display picture to other users. When you hover over the circle, the word upload will show. Click this and you will be taken to your system s files where you can select a file you want to upload. **Display Names** are added or updated in the General tab, type your desired name into the box and click save. **Contact Details** are added or removed on the General tab. Email addresses and phone numbers are optional, to reset your account or have forgotten your password. **Language** preference can be selected using the drop down menu. ### B. Spaces Organize groups of people and rooms together by using Spaces. A selected space will only show the list of rooms and people that are part of it. - On Web / Desktop, Set up a new space by clicking "+ Create a space" - On iOS / Android, Tap the space icon and select "create" [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690987258040.png) From here you can create either a public or private space. Once your space is created you can invite people to join it and create new or add already existing rooms. Cater the space to your specific wants and needs. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690987351699.png) ### C. Search Bar Find people and rooms who are already part of your lists. ### D. Rooms This is where group discussions take place. Naming conventions help conversations be focused on a specific topic, and aid discoverability. When searching for a room, make sure to select the right server for it to be discoverable. You can only join a private room by receiving and accepting an invite. #### Find a public room - On Web / Desktop, Find a room by using the "Compass" icon to explore already created public rooms and press "join". - On iOS / Android, Tap the compose icon and select “Explore rooms”. Press "join" to participate. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690987514646.png) #### Create a room - On Web / Desktop, Create a new room by clicking the "+" next to Rooms in the left panel. - On iOS / Android, Tap the compose icon and select Add room. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690987677645.png) #### Leave a room - On Web / Desktop, Leave a room by clicking the three dots and choose the "leave room" option. - On iOS / Android, Leave a room by clicking the "room name" at the top of the room and choose the "leave room" option. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690987786722.png) ### E. Notifications To stay focused, you can set when you want to receive notifications. Manage notifications per room and per person by clicking on the alarm icon next to it. Manage all notifications in your profile settings under "Notifications" to control where and when you will receive notifications. The notifications will be set to a default e.g. Noisy for messages containing my username. Please alter these settings to your personal preference. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690987948270.png) ### F. People This is where one-to-one chats take place. - On Web / Desktop, Start a new chat by using the + button next to "People" in the left panel and type in their username or Matrix ID. - On iOS / Android, Tap the compose button and select “Start chat”. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988074158.png) ### G. Favorites Easily pin favorite rooms and people for quick access to be displayed at the top of your list. You can select "low priority" for the rooms and people you wish to push to the bottom of the lists using the “three dots” icon next to it. ### H. Appearance Once you’re up and running, you can start to think about how you want everything to look. In settings, click "Appearance" where you can amend the theme to light or dark, increase or decrease your font size or click on "Show advanced" for more. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988206385.png) # The Middle Panel [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988573221.png) ### A. Room header Shows you the room name and a quick summary of the topic. Settings and details of the room can be found and managed in the right hand panel (see separate section). [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988643107.png) Start a video or audio call when you’re in a room or conversation by clicking on the icons in the "Room header". ### B. Messages **Send a message** by typing into the composer. Hit enter to send. **Notify someone in a room** by writing their name or @ before their name. **Send a file** either by drag and drop or click on the paperclip to browse your filesystem. You can also copy/paste into the composer. **React with emojis 😁** by hovering on a message and clicking the smiley face! **Reply to a message** by hovering on a message and clicking the reply button. **Edit a message** you’ve sent by hovering on the message and clicking the edit button (the room will be notified of edited messages). **Remove a message** you’ve sent by hovering on it, clicking the 3 dots option button and choosing "remove" (the room will see a note that a message has been removed). **Format text** by highlighting your message in the composer. You have options to bold, italics, strikethrough, code block and quote messages. **Forward a message** by highlighting your message, clicking the options button and choosing "forward". You can then choose which room or conversation you want to forward it to. **Quote a message** by hovering over your message and clicking the options button. You can then click "Quote" and type in your desired message. ### C. Threads Threads move message replies out of your timeline to help declutter the main feed, keep topics together and “catch up” on conversation easier. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988773838.png) You can see Thread responses and respond/react to them. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988818788.png) And see Threads in a room on the Thread panel. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988829624.png) Tap on a message to bring up options then "Thread / Reply in thread" [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988847645.png) ### D. Voice Messages Send a voice message when you re in a room by clicking on the microphone in the "composer" bottom right hand corner. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988878845.png) # The Right Panel [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988507954.png) ### A. Room information Click on the "information icon" or the room name on iOS and android in the room header to open the room information panel. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988400608.png) **People** lets you see who is already in the room, with the option to invite others to join. **Files** gives you instant access to the shared files in the room. **Export chat** lets you download the conversation in a room and export it to HTML, Plain Text and JSON formats. **Share room** gives you a way to invite multiple people to the room, via a QR code or social media. **Room settings** gives you a series of advanced room setting options. Please note you can only amend these settings if you are an admin. Click the room name and click "Settings" from the drop down menu. Here you can manage a number of things, including room permissions and roles. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690988331553.png) Additionally, security and privacy settings give you the freedom around encryption, room access and chat history. Manage widgets, bridges and bots are optional advanced extras to improve room productivity. ### B. Show notification messages Displays room notifications to keep on top of important conversations. ### C. Search conversations Brings up the search functionality within the current (or other) rooms. # Frequently Asked Questions #### Account management How do I reset my password? - Please note that we cannot reset passwords or reactivate matrix.org accounts. If you have an email address attached to your account, you can reset your password here. Do I need an email address to register? - Using an email address when creating a Matrix account is optional; it will make it easier for others to discover you and can help you to reset your password if needed.Please note that Element is a client that allows you to access any homeserver in the Matrix network, just like a browser allows you to access any website you want. Each homeserver has different approaches to Abuse Management and Privacy, which are out of Element’s control.
How is my personal data being used? - Here is Element’s privacy policy. If you have additional questions, contact our DPO. How do I report on content in Element? - Report inappropriate content on Element by hovering on the message and clicking the more options button (three dots) and "Report content". How do I submit an abuse report? - To report a general abuse issue, please contact abuse@element.io Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Creating your Matrix Account Depending on your homeserver, and it's configuration, the sign-up process may differ slightly, however the overall process should largely follow these steps. From your Matrix Client, click `Create Account`, then make sure to change the homeserver as needed. You can do this by clicking `Edit` next to the current homeserver name. Once a homeserver is selected, the client will then show you the available registration / authentication methods. [](https://ems-docs.element.io/uploads/images/gallery/2023-06/image-1686041959863.png) #### External Services External service registration allows you to register for your account using a handful of different login providers, For example, matrix.org allows sign-up using a number of external services, including GitHub.If you choose to register using an external service, you will not be able to use it with any other account, including if you deactivate the account it is associated with.
#### Username, Password and Email For the initial stage of the registration flow, you will need to choose a username, otherwise known as your Matrix ID (MXID). Like email it follows a standardized format, `@username:homeserver.com`, for example a username of `example-name` on the `matrix.org` homeserver would be `@example-name:matrix.org`. Choose carefully, it isn't possible to change your MXID, you will however have a display name, that is freely changeable. You will also be able to provide an email, this is an optional field, if you add an email you will be able to reset your password. Additionally, adding an email allows you to opt-in to be discoverable by existing contacts. #### Privacy Policy Before your account can be created, you may need to review and accept any policies of the homeserver you wish to join. Do so by clicking the `Privacy Policy` link and reading through the document - if you accept the policy, confirm by clicking the checkbox and clicking `Accept`. ### Creating a Matrix Account on your Homeserver If you're an EMS customer, you can create your users via the Server Admin tab of the EMS Control Panel. Alternatively you can make use of the Synapse Admin API to create a Matrix Account on a homeserver you hold an Admin account on. To do so, you will need to use Create or Modify Account from the User Admin API. ``` https://HOMESERVER_URL/_synapse/admin/v2/users/FULL_USERNAME ``` ```json { "password": "user_password", "displayname": "User", "threepids": [ { "medium": "email", "address": "Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
Once you have an account, it's important to understand the mechanisms it uses to keep your messages secure. Matrix uses encryption to protect your communication. The keys for this encryption should be kept secure, this is done using Secure Backup. ### Secure Backup After sending your first encrypted message, you'll receive a prompt to `Set up Secure Backup`, to safeguard against losing access to encrypted messages & data. If you choose not to, any new sessions you start by logging into different clients, will not be able to see you messages. If you do not receive a prompt, or chose to action later, you can initiate its setup by clicking on your avatar in the top left, then selecting `Security & Privacy`. Under the `Encryption` / `Secure Backup` section, select `Set up`. Follow the prompt to set up your Secure Backup, you can opt to use a phrase or always use a Security Key. If you opt for a Security Phrase, you will be able to provide a phrase of your choosing which you will need to provide to any client when you login with your account. Alternatively, if you forget your phrase, or did not provide one - you will need to provide the generated key. #### Verified Session A verified session is a device (any client logged into your account) that has been verified as legitimate. On your accounts' first login, the session will be marked as verified, make sure to set up a Secure Backup, you will need it if you ever lose access to all verified sessions. When you login to a new session, you will be presented with the option to either provide your Security Key / Phrase, or to request verification from another already verified session. Successfully completing either option will mark your new session as verified. ##### Forgotten or lost all recovery methods? If you have forgotten or lost all methods of verifying your account, you will need to `Reset` you account. Doing so will result in losing access to all your encrypted messages, and mark all sessions as unverified (treating this new session like your first). ### Add Email to your account Adding an email to your account will allow you to be able to reset your password should you lose it. Simply follow these steps: 1. Go to Element `All settings` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651101546-24-15-pm.png) 2. Enter your email address and click `Add` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651182568-51-19-am.png) 3. When you get this message, check your email [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651265482-57-57-am.png) 4. Click the link in the email. Make sure it opens in another tab/window, leaving your Element client where it is [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651210107-55-01-am.png) 5. When you get this message, you can close the verification tab/window and return to Element [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651288348-00-03-pm.png) 6. Go back to Element and click `Continue` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651323286-57-57-am.png) 7. Enter your account password or confirm using SSO, then click `Continue` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651357335-01-34-pm.png) 8. If all worked correctly, your new email should now show up under the `Email addresses` section in Element settings. If not, something went wrong and you need to try again [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651385753-02-17-pm.png) ### Securing a Matrix Account on your Homeserver If you're an EMS customer, you can create your users via the Server Admin tab of the EMS Control Panel. Alternatively you can make use of the Synapse Admin API to create a Matrix Account on a homeserver you hold an Admin account on. To do so, you will need to use Create or Modify Account from the User Admin API. ``` https://HOMESERVER_URL/_synapse/admin/v2/users/FULL_USERNAME ``` ```json { "threepids": [ { "medium": "email", "address": "Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Changing your Matrix Account passwordIf you don't know your password, you'll need to recover your account, see our Recovering a Matrix Account page for instructions.
1. Go to Element `All settings` [ 2. Enter your current password and your new password [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651780042-26-13-pm.png) 3. Click `OK` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651805137-31-01-pm.png) 4. You now need to sign in again on all your other devices ### Changing a Matrix Account password on your Homeserver If you're an EMS customer, you can create your users via the Server Admin tab of the EMS Control Panel. Alternatively you can make use of the Synapse Admin API to change a Matrix Account password on a homeserver you hold an Admin account on. To do so, you will need to use Create or Modify Account from the User Admin API. ``` https://HOMESERVER_URL/_synapse/admin/v2/users/FULL_USERNAME ``` ```json { "password": "new_password" } ``` # Recovering a Matrix AccountDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
Resetting the account password will log out all your sessions, before doing this, make sure that - All your sessions are connected to Secure Backup - All sessions have backed up all their keys ([Check Cross Signing Status](https://ems-docs.element.io/books/element-cloud-documentation/page/check-status)) - You have your correct key backup passphrase available ### Recovering your Matrix AccountThis will only work if you have an email address attached to your Matrix account. If you do not have an email address attached, contact the administrators of your homeserver.
Reminder: support@matrix.org does not reset passwords under any circumstances
1. Sign out of Element [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721651991898-32-36-pm.png) 2. Click `Sign out` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652013530-15-05-pm.png) 3. Click "Not sure of your password? `Set a new one`" [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652041660-15-56-pm.png) 4. Enter your email address, and a new password. Then click `Send Reset Email` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652072517-20-13-pm.png) 5. When you get this message, check your email [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652099747-22-21-pm.png) 6. Click the link in the email. Make sure it opens in new browser tab, leaving your Element client open [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652128382-23-42-pm.png) 7. Click `Confirm changing my password` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652188389-26-36-pm.png) 8. You can now close this tab and return to Element [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652219082-27-21-pm.png) 9. Click `I have verified my email address` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652254888-22-21-pm.png) 10. Click `Return to login screen` [](https://ems-docs.element.io/uploads/images/gallery/2024-07/image-1721652295124-28-38-pm.png) 11. Sign in like normal with your new password. Note that all your other sessions have been signed out and you need to sign in again. ### Recovering a Matrix Account on your Homeserver If you're an EMS customer, you can create your users via the Server Admin tab of the EMS Control Panel. Alternatively you can make use of the Synapse Admin API to manage a Matrix Account on a homeserver you hold an Admin account on. To do so, you will need to use the User Admin API. # Deactivating a Matrix AccountDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Deactivating your Matrix Account If you wish to deactivate your account, you can do so by following the below steps: - Log in to your Matrix Client - Click on your Avatar / Username in the top left corner - Open `Settings` - From the bottom of the `General` tab, click `Deactivate` - Check any additional options, if applicable, then enter your password or confirm via SSO to deactivate your account [](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1679492386786.png) Please note once the account has been deactivated, it is impossible to reactivate it again or reuse the username. Your user is stored indefinitely to avoid account recycling, as such you may also wish to remove any Third-Party ID's from your account **before** deactivation, as this may cause issues if you ever attempt to create a new account. #### Erasing your Matrix Account You can also GDPR erase your account, this means messages sent by the user will still be visible by anyone that was in the room when these messages were sent, but hidden from users joining the room afterwards. You can do this by checking the `Hide my messages from new joiners` checkbox on the `Deactivate Account` confirmation prompt. ### Deactivating a Matrix Account on your Homeserver If you're an EMS customer, you can create your users via the Server Admin tab of the EMS Control Panel. Alternatively you can make use of the Synapse Admin API to deactivate a Matrix Account on a homeserver you hold an Admin account on. To do so, you will need to use Deactivate Account from the User Admin API. ``` https://HOMESERVER_URL/_synapse/admin/v1/deactivate/FULL_USERNAME ``` ```json { "erase": true } ``` # Reactivating a Matrix AccountDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Reactivating your Matrix Account #### Matrix.org Once your account has been deactivated, it is impossible to reactivate it again or reuse the username. Your user is stored indefinitely to avoid account recycling. To protect the security and privacy of our users, we never reactivate, or release deleted usernames. Instead, we recommend creating a new account using a different Matrix ID. ### Reactivating a Matrix Account on your Homeserver If you're an EMS customer, see [this FAQ entry](https://ems-docs.element.io/link/6#bkmrk-how-do-i-reactivate-). Alternatively you can make use of the Synapse Admin API to reactivate a Matrix Account on a homeserver you hold an Admin account on. To do so, you will need to use Create or Modify Account from the User Admin API, passing `"deactivated": false` as well as providing a new password. ``` https://HOMESERVER_URL/_synapse/admin/v2/users/FULL_USERNAME ``` ```json { "password": "new_password" "deactivated": false } ``` # EMS Account Management Unsure what an EMS account is, see the 'Understanding Your Element Accounts' page above. # Creating an EMS Account Your EMS Account is used to manage and use your subscriptions with Element, whether for your own managed homeserver in the cloud, accessing your On-Premise subscription download portal or your Element One bridges. Depending on which subscription you want, you wil setup an EMS Account as part of that setup flow. You can however also manually create an account first, then sign-up for your desired subcription. ### Manually Registering for an EMS Account To manually register, from the Element homepage, click `Sign In` then `Admin Dashboard` to be taken to the EMS Control Panel. As you don't yet have a login, you will be presented with the login page. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053542763.png) Simply click `Register` and fill in the information requested to create and account. **Note:** Your password must be a minimum length of 12 characters. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053685641.png) Click `Next Step` to move to email verification, if you don't recieve the email, you can request it be resent from this page. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053824964.png) After you recieve the email, click the link to verify, then on the page `Click here to proceed` to confirm creation of your EMS Account. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053972849.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053984968.png) With your email verified and account created, repeat the steps to open the [EMS Control Panel](https://ems.element.io/user/hosting#/hosts), or click the link. Login with your details, then accept the Terms and Conditions. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054183691.png) You are now in the EMS Control Panel where you can manage your account and subscriptions. ### Your EMS Account when signing up through Element One If your interested in Element One, you'll be prompted to create your EMS Account whilst running through the Element One setup flow. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054322843.png) Agree to the Terms and Conditions, then you'll be taken to the account creation form. Follow the steps from the `Manually Registering for an EMS Account` section above for step-by-step instructions on this process. If you already manually created an account, but still see the `Sign Up` screen, it's possible you are no longer signed in. Open the EMS Control Panel, log in with your details, then repeat the Element One sign-up flow. Once signed up, or logged in, you should be taken to complete the Element One sign-up flow, seen below. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054557538.png) ### Your EMS Account when signing up for an On-Premise trial If you're looking at trying our self hosted On-Premise offering, you will be prompted to register for an account. Click `Register` then accept the Terms and Conditions. Provide your email address then click `Continue`, you will be taken to the registration page. Follow the steps from the `Manually Registering for an EMS Account` section above for step-by-step instructions on this process. If you already manually created an account, but still see the `Sign Up` screen, it's possible you are no longer signed in. Open the EMS Control Panel, log in with your details, then repeat the Element One sign-up flow. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054742377.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054761175.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054781236.png) ### Your EMS Account when signing up for a fully managed homeserver If you're looking to buy a fully managed homeserver you'll be presented with the creation flow, the first stage being registering for an EMS Account. Click `Register`, then agree to the Terms and Conditions. Follow the steps from the `Manually Registering for an EMS Account` section above for step-by-step instructions on this process. If you already manually created an account, but still see the `Sign Up` screen, it's possible you are no longer signed in. Open the EMS Control Panel, log in with your details, then repeat the sign-up flow. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055187227.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055274956.png) # Securing an EMS Account ### Two-Factor Authentication From the Element homepage, click `Sign In` then `Admin Dashboard` to be taken to the EMS Control Panel. If you aren't logged in already, you will be presented with the login screen - sign in using your details to be taken to the EMS Control Panel. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053542763.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055581048.png) Click `Your Account`, found in the top right, then select `Account`, or goes directly there from this link, Account Page. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055644130.png) This page contains details about your account, to secure your account, you will need to click `Authentication Settings` found at the bottom of the `Edit your profile` section. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055793853.png) This will take you to your Account Console, where you can manage your account security settings. Click `Signing In` under `Account Security`, then from the `Two-factor authentication` section click `Setup an authenticator application`. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055925565.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055946973.png) You will need to reauthenticate to confirm your identity, then follow the steps provided to setup a mobile authenticator. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055997291.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056046959.png) If you're planning on using a password manager, you may not be able to scan the QR code. Simply click `Unable to scan`, copy the code and paste it into your password manager. Configuration values are provided below the code, should your application require this information. To complete this process, provide a generated code from your device / password manager, give it a recognisable device name then click `Submit`. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056199966.png) You can confirm this was successful, as you will see the device listed under the `Two-factor authentication` section. ### Changing your EMS Account Email From the Element homepage, click `Sign In` then `Admin Dashboard` to be taken to the EMS Control Panel. If you aren't logged in already, you will be presented with the login screen - sign in using your details to be taken to the EMS Control Panel. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053542763.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055581048.png) Click `Your Account`, found in the top right, then select `Account`, or goes directly there from this link, Account Page. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055644130.png) This page contains details about your account, to change your email, simply edit the existing email present and then click `Save`, a banner will appear asking you to verify this new email address. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055793853.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056404870.png) You will recieve an email, simply click the `Confirm Email Address` button in the email to verify this new address. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056498132.png) # Changing an EMS Account Password ### Changing your EMS Account Password From the Element homepage, click `Sign In` then `Admin Dashboard` to be taken to the EMS Control Panel. If you aren't logged in already, you will be presented with the login screen - sign in using your details to be taken to the EMS Control Panel. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053542763.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055581048.png) Click `Your Account`, found in the top right, then select `Account`, or goes directly there from this link, Account Page. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055644130.png) This page contains details about your account, to change your password, you will need to click `Authentication Settings` found at the bottom of the `Edit your profile` section. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055793853.png) This will take you to your Account Console, where you can manage your account security settings. Click `Signing In` under `Account Security`, then from the `Basic authentication` section click the `Update` button. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055925565.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056709130.png) You will need to reauthenticate to confirm your identity, then follow the steps provided to setup a mobile authenticator. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055997291.png) Finally, you will be presented with the screen to update your password. Confirm it and then click `Submit` to change your account password. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056774523.png) # Deleting an EMS Account ### Deleting an EMS Account From the Element homepage, click `Sign In` then `Admin Dashboard` to be taken to the EMS Control Panel. If you aren't logged in already, you will be presented with the login screen - sign in using your details to be taken to the EMS Control Panel. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053542763.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055581048.png) Click `Your Account`, found in the top right, then select `Account`, or goes directly there from this link, Account Page. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055644130.png) This page contains details about your account, to dleete your account, you will need to click the `Delete Account` button found at the bottom of the page. [](https://ems-docs.element.io/uploads/images/gallery/2023-09/image-1694420234229.png) Confirm the account deletion in the following prompt to irreveribily delete all hosts and integrations you have and cancel any subscriptions. Your account will then be deleted. [](https://ems-docs.element.io/uploads/images/gallery/2023-09/image-1694420311450.png) # Element Web/Desktop Client Settings Documentation covering the options available within the Element Web/Desktop Clients' Settings. # Accessing General SettingsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing the Settings Page You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings. You can also use this menu to quickly return `Home`, provide `Feedback` and this is where you can `Sign Out` from your client. **Disclaimer:** The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function. ### General Settings [](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1678368932401.png) #### Profile Allows you to change your `Display Name`, this is the name seen by others whilst messaging with them. Updating this will notify all rooms of the change of name. You are also able to upload / change your profile picture, you can do this by hoovering over the existing picture and clicking. After making your changing, click 'Save' to set them. You Matrix ID in full is also displayed here for your reference. #### Account Allows you to add email addresses / phone numbers to your account, as well as change your `Language and Region` setting. Adding of Third-Party IDs requires verifying your login by either supplying your account password, or using SSO (such as when using Element One). You'll want to add your email if you'd like to enable Email notifications, check out the [Notification Settings]() documentation, or discovery via Identity Server - see the `Discovery` section below. #### Discovery Allows you to agree to the identity server (vector.im) Terms of Service to allow yourself to be discoverable by email address or phone number, change your identity server. Using an identity server is optional. If you choose not to use an identity server, you won't be discoverable by other users and you won't be able to invite others by email or phone. You can stop using an identity server by clicking 'Do not use an identity server' #### Manage integrations Allows you to turn on or off the use of an integration manager. You the toggle button to configure as desired. #### Deactivate account Allows you to deactivate your account - Warning! Deactivating your account is a permanent action. # Appearance SettingsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing Appearance Settings You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings, click `Appearance` in the vertical navigation menu on the left to open `Appearance` settings.Info: The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function.
### Appearance Settings [](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1678368867514.png) Appearance settings allows you to customize the look and feel of your client, all settings provide visual representation of the changes so you can confirm your preferred style. Options include Theme, Message Layout, Font Size and Image size in the timeline. # Notification SettingsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing Notification Settings You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings, click `Notifications` in the vertical navigation menu on the left to open `Notifications` settings.Info: The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function.
### Notification Settings [](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1678908474209.png) Notification settings allow you to customize default notification settings which are synced to your account, however you are also able to customize whether you receive notifications for this specific device. **Note:** A device is per client, using both a web-based Matrix client and a Desktop client on the same physical device will still appear as two separate devices. #### Desktop Notifications To enable desktop notifications from your client, you can enable the toggle 'Enable desktop notifications for this session', you can also customize these notifications to also display the message that triggers the notification using the 'Show message in desktop notification' toggle. When using a web-based Element client, you will also need to accept permissions allowing the client to display notifications. #### Notification types explained Notification settings allow notifications to be set as either 'Off', 'On' or 'Noisy'. - **Off:** You won’t be notified when the selected event happens. - **On:** You will get a message popping up when the selected event happens, but no sound. - **Noisy:** You will get a visual highlight (red badge and/or text highlight), a sound and/or vibration (depending on the device) when the selected event happens. For finer tuning, you can easily configure per room notification setting from the context menu you get by clicking on the `...` icon that appears when hovering over the room name in the room list. You can use this to temporarily mute a room, or make sure you’re not missing anything from a given discussion. You can select the following options: - **Mute:** You won’t be notified, even if your name or a keyword is mentioned. - **Mentions only:** You will only be notified for the items that are meant to be ‘noisy’, i.e. your name and keywords. - **All messages:** You will get a (silent) notification for every message happening in the room; your ‘noisy’ events (e.g. your name being mentioned) will still be noisy (red badge and sound). - **All messages (Noisy):** every message will make a noise on top of the visual notification. Your noisy events will still be differentiated by a red badge. #### Keyword Notifications From the notification settings you can also add additional keywords to listen for to trigger a notification. You can directly specify how a notification triggered from these keywords responds in the 'Mentions & keywords' section. # Preference SettingsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing Preference Settings You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings, click `Preferences` in the vertical navigation menu on the left to open `Preference` settings.Info: The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function.
### Preference Settings [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690991017311.png) The Preferences view allows you to customize various aspects of the Element client organized by each area of the application. Each preference is explained next to the toggle to enable or disable the option. # Keyboard SettingsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing Keyboard Settings You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings, click `Keyboard` in the vertical navigation menu on the left to open `Keyboard` settings.Info: The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function.
### Keyboard Settings [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690989357290.png) The Keyboard settings view allows you to view all Keyboard shortcuts you can use with the Element client organized by each area of the application. # Sidebar SettingsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing Sidebar Settings You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings, click `Sidebar` in the vertical navigation menu on the left to open `Sidebar` settings.Info: The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function.
### Sidebar Settings [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690991167924.png) The sidebar settings controls what Spaces to show down the sidebar on the left. **Home:** Home is useful for getting an overview of everything. - _Show all rooms:_ Show all your rooms in Home, even if they're in a space. **Favorites:** Group all your favorite rooms and people in one place. **People:** Group all your people in one place. **Rooms outside of a space:** Group all your rooms that aren't part of a space in one place. See the below example of a sidebar with these options enabled: [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690991238396.png) # Voice & Video SettingsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing Voice & Video Settings You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings, click `Voice & Video` in the vertical navigation menu on the left to open `Voice & Video` settings.Info: The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function.
### Voice & Video Settings [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690991422078.png) The Voice & Video settings section allows you to change your default audio and microphone devices, individual voice and video preferences as well as configure advanced options relating to Video Processing and your Connection. To start, if you haven't yet made use of Voice & Video, you may see a `Requests media permissions` prompt, you will need to do this, then accept the prompt in your browser to allow the Element client to see, and use your Camera and Microphone. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690991434643.png) Once you have provided media permissions, you will be able to customize you default Audio and Microphone devices under Voice Settings, and the default Camera to use under Video settings. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690991704345.png) # WIP Security & Privacy SettingsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing Security & Privacy Settings You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings, click `Security & Privacy` in the vertical navigation menu on the left to open `Security & Privacy` settings.Info: The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function.
### Security & Privacy Settings # SessionsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing Sessions You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings, click `Sessions` in the vertical navigation menu on the left to open `Sessions` settings.Info: The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function.
### Sessions [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690992096339.png) The Sessions section allows you to manage the existing logged in sessions you have open across various devices and whether they are verified. #### Security Recommendations [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690992234988.png) This first section will only appear if there are recommendations about your existing sessions to enhance the security of your account. In the example above, 3 unverified sessions exist, as well as 2 Inactive sessions (in this scenario, they are the same three sessions). Clicking on `View All` will filter the `Other Sessions` section on the recommendation clicked. #### Current Session [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690992436887.png) This section will show the details of your current session, i.e. the logged in session on the client you are using. Note, you can have multiple sessions on the same device, for instance, if you are logged in to both the Element Web client and the Desktop client. If the current session is unverified, you will be provided a prompt to begin verification of the session. Clicking the 3-dot menu in the top right, will open a menu to sign out of the current session (or all sessions). Warning, this will sign you out and you will need to log back into your session on the client. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690992562519.png) Clicking the right pointing arrow beneath the 3-dot menu, will expand to show more details about the session. Additional options include `Signing out of this session`, `Rename`-ing a session and toggling of `Push notifications`. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690992645914.png) ### Other Sessions [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690992891681.png) Much like the section above, this sections shows all other sessions you currently have. As above, the 3-dot menu will reveal the option to sign out of all of these other sessions. You could also individually tick various sessions and then click the then revealed `Sign out` button to customize which should be signed out. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690992830197.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690992842874.png) Along the grey bar, you can also filter the view of other sessions on various options: - **All** - **Verified:** Ready for secure messaging - **Unverified:** Not ready for secure messaging - **Inactive:** Inactive for 90 days or longer [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690993019162.png) Clicking the right pointing arrow beneath the 3-dot menu, will expand to show more details about the session (see above). Additional options include `Signing out of this session`, `Rename`-ing a session and toggling of `Push notifications`. # LabsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing Labs You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings, click `Labs` in the vertical navigation menu on the left to open the `Labs` page.Info: The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function.
### Labs [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1690991797607.png) The Labs sections contains experimental options you can turn on to test out new / upcoming features. It is not recommended to enable Lab options unless you are happy to accept enabling of beta functionality. # Help & AboutDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Accessing Help & About You can change your Matrix account settings by clicking your profile icon in the top left of the Element client. By default, this will be a colored circle with the first letter of your Matrix ID. From the presented drop-down menu, you'll be able to jump into specific settings straight away, or access `All Settings`. Clicking `All Settings` will take you first to `General` settings, click `Help & About` in the vertical navigation menu on the left to open the `Help & About` page.Info: The below setting layout / order may change in subsequent client updates, however generally most settings will still perform the same function.
### Help & About [](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1678909486024.png) From Help & About you can find important information related to the client itself, such as it's current version, your homeserver and identity server details as well as links to our FAQ, Legal documents and credits. #### Your Access Token Your access token gives full access to your account via the use of Matrix APIs, you can read more about them depending on your needs. If you are an Admin of a homeserver, and are using an account with Admin access, you can make use of the Synapse Admin API. For both admins and regular users, the Matrix APIs can be found from the latest Matrix Spec page - these include: - Client-Server API - Server-Server API - Application Service API - Identity Service API - Push Gateway API #### Bug Reporting If you've experience a bug, the best place to report it is by submitting a bug report to the appropriate Github repository for your client, the Element account. # Matrix Rooms Documentation covering from basic usage and creation of rooms to room management. # Understanding Matrix Rooms All communication via Matrix takes place within rooms. Rooms can be made available publicly or kept private, and they can configured to be encrypted depending on your requirements. From the Element Matrix clients, Element Web App or Element Mobile / Desktop Apps, rooms can be found under the `Rooms` section. However when speaking directly to one particular person, a Room is marked as a Direct Chat and can be found under the `People` section instead. Rooms, if desired, can be prioritized as `Low Priority` or `Favorite`, moving them into dedicated sections named as such. Rooms can also be organized into any number of Spaces, allowing you to further manage the rooms you see. In addition, you can customize the notification settings for each room to alert for `All messages`, only `Mentions & keywords` or to `Mute room`. ### What's Next? #### Getting Started To start learning the basics of creating and using rooms, check our 'Getting Started' series of docs on the subject, starting with [Creating a Room](https://ems-docs.element.io/books/element-support/page/getting-started-creating-a-room). # Getting Started: Creating a RoomDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
You can create a room by clicking the `+` button, located at the top alongside your current Space's name within the Left Panel - you will be presented with various options to create a room matching your requirements. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684319319954.png) ### Starting a Direct Chat After clicking `Start new chat`, you will be presented with the `Direct Messages` prompt, from here you can search for other people using their name, email address or username. You can select your desired contact(s) to directly invite them, or copy the provided invite link to send separately. You will see suggestions based on people you have most recently interacted with or search directly. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684322001251.png) **Searching for users:** When searching for users, searching by name requires you to have interacted (been within a common room / space) with the user previously, otherwise you will need to specify their full Matrix ID, for example, `@user:example.com`. After confirming the invitees for the chat, click `Go`. This will open a draft of the room in the Right Panel, you must then send your first message for the room to be created and the recipients to be invited. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684322049815.png) ### Starting a New Room After clicking `New room`, you will be presented with the `Create a private room` prompt, from here you can specify the room settings as desired. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684322140871.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684322731897.png) - **Name:** This is the name your room will appear as, if you are making a public room, make sure you choose a name that will be easily found when searching and is appropriate for the homeserver. - **Topic:** This works as a description for the room, it is presented at the top of a room [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684322515432.png) - **Room Type:** Here you can customize whether the room should be publicly accessible, changing to public will change the available configuration options, per images above, and prevent enabling end-to-end encryption1. - **Private Rooms | Enable end-to-end encryption:** Enabling this at any time prevents disabling it, ensure when creating the room you would like encryption. It is always possible to enable encryption after room creation via the room settings. - **Public Rooms | Room Address:** Much like your Matrix ID `@user:example.com`, your room will also have an ID or address `#room:example.com` that can be used to link to it from other chats, using `#`. It maybe beneficial to choose a simpler name here, allowing the room name to be more descriptive. Do note some characters are not allowed, such as spaces, `#` and `%`. - **Advanced - Block anyone not part of homeserver:** Enabling this prevent users from other homeservers from joining the room. > 1 Whilst you can enable encryption for a public room via the room settings after creation it's not recommended to add encryption to public rooms. Anyone can find and join public rooms, so anyone can read messages in them. You'll get none of the benefits of encryption, and you won't be able to turn it off later. Encrypting messages in a public room will make receiving and sending messages slower. ### What's Next? #### Using A Room Now you've created a room, try the next in the Matrix Rooms: Getting Started series, [Getting Started: Using a Room](https://ems-docs.element.io/books/element-support/page/wip-getting-started-using-a-room) #### Managing A Room To learn more about managing a room, try our Matrix Rooms: Managing a Room series, starting with [Managing a Room: Room Info](https://ems-docs.element.io/books/element-support/page/managing-a-room-room-info). # WIP Getting Started: Using a RoomDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Joining a Room - Searching for rooms - Finding rooms using spaces - Troubleshooting failed room invites ### Configuring a Room - Room settings (Priority / Notifications etc.) #### Notifications From this section, you can managed your personal notification settings. The options you choose [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684329791140.png) ### Leaving a Room - Not known room - unable to leave room ### What's Next? #### Managing A Room To learn more about managing a room, try our Matrix Rooms: Managing a Room series, starting with [Managing a Room: Room Info](https://ems-docs.element.io/books/element-support/page/managing-a-room-room-info). # Managing a Room: Room InfoDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
To start managing a room, you can click the `i` icon in the top right of the room, this will open `Room Info`. From here there are a number of basic management options you can perform. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684325165079.png) ### People From this section, you can invite more people to the room and view the existing members. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684325427910.png) Clicking on any member, via this pane or from their username / profile picture from the room directly, will take you to management options specific to that user. You can adjust their power level, remove recent messages, mute them or Remove / Ban them from the room. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684325630636.png) ### Files From this section, you view in chronological order, media shared within the room. File entries include the name of the media and a preview if applicable, the media's size and the option to download it as well as information on who and when it was sent. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684326207406.png) ### Poll History From this section, you can review Active and Past polls, clicking on individual entries to drill down into the results as well as jump to them in the timeline. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684326349026.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684326362574.png) ### Export Chat From this section, you can export your rooms message history (including attachments if needed) in HTML, Plain Text or JSON format. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684326428516.png) ### Share Room From this section, you can generate a link or QR code image that can be shared beyond Matrix to allow others to join the room. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684326511888.png) ### What's Next? #### Room Settings Now you've mastered this section, try the next in the Matrix Rooms: Managing a Room series, [Room Settings](https://ems-docs.element.io/books/element-support/page/managing-a-room-room-settings), for details on available room settings. # Managing a Room: Room SettingsDisclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
You can access `Room Settings` by either clicking `Room settings` from the `Room info` pane: [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684329235935.png) Or by hovering over the room name from the room list, clicking the 3-dot menu, then selecting `Settings`: [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684329277354.png) You will be presented with the `Room Settings` screen, and various navigation options, for details on each of these screens, see the below sections: [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684329214662.png) ### General From this section, you can customize how your room looks and is accessed: [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684329126059.png) #### General - Room Name - The name of your room as it appears within a users' room list. - Room Topic - A description of the room, present along the top bar when viewing the room. - Avatar - An icon for the room, change by clicking the `Pencil` icon and uploading your desired image. Check the FAQ Entry for details on [What is the preferred resolution for room and space icons?](https://ems-docs.element.io/link/6#bkmrk-avatar-resolution) #### Room Addresses ##### Published Addresses Published addresses can be used by anyone on any server to join your room. To publish an address, it needs to be set as a local address first. - Main Address - from this dropdown you can select which local address you would like to be the main address to your room from external homeservers. Once a local address is first set, this will default to that address, however you can remove the main address by selecting `not specified` from the dropdown. - Publish this room to the public in example's room directory - toggling this will allow your room to be discoverable by user's with access to the homeserver. - Room Address - you can also publish other addresses in addition to the main address by adding other local addressed here and clicking `Add`. ##### Local Addresses Set addresses for this room so users can find this room through your homeserver. - Room Address - Provide the address that users can use to access your room, creating your first Room Address will automatically set it as the `Main Address` under `Published Addresses` #### Other - URL Previews - When someone puts a URL in their message, a URL preview can be shown to give more information about that link such as the title, description, and an image from the website. You can enable this for the room just for you, or as the default for participants in the room. - Leave room - Here you can opt to leave the room:If you are the only person in a room, if you leave, no one will be able to join in the future, including you. If you are the sole user with Admin rights to a room and you intend to leave, you should increase the power level of an active member to allow for room management.
### Security & Privacy From this section, you can turn on Encryption if not already on, confirm who can join and the historical messages they can read. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684329744028.png) #### Access - Private (invite only) / Public - Select your desired access level, note to link to a public room, you will need to publish an address. You can do so from the `General` section. - Space members - To use this option, ensure your room is in a space, then select and confirm all spaces that members of those spaces should be able to join. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684401764966.png) - Guest Access - Available only when `Public`, by default, people with supported clients will be able to join the room without having a registered account. You can disable this behavior by clicking `Show Advanced` then switching off via the toggle button. #### Who can read history?Changes to who can read history will only apply to future messages in this room. The visibility of existing history will be unchanged.
From here the options are self-explanatory, simply change as desired to meet your requirements. ### Roles & Permissions From this section, you can manage who can access, who can manage and who can administer your room. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684329990675.png) Management of a room is generally handled by it's admins and moderators, however under-the-hood, rooms make use of power levels. A users' power level is a number between 0 and 100 where the higher the number, the more access you have. The default power levels for the admin and moderator roles are 100 and 50 respectively, however you can specify any custom power level for specific actions. #### Privileged UsersSetting a user from this list to Default will remove them as a Privileged User
If the only Admin for a room is demoted, you will not be able to manage the room, be careful when applying changes to permission levels
Here you can manage all Privileged users for the room, and the power level they have. You can select either Default, Moderator, Admin or Custom Level. #### Add privileged users From this section you can search existing members of the room and specify a desired power level to elevate them as a Privileged User. #### Banned Users A list of banned users, and the option to revoke the ban will be presented here if any bans have been made. You can identify who banned each specific user by hovering over the banned user. [](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1684403306324.png) #### Permissions From here you can see a list of all actions possible within a room, and control the required power level to perform those actions.Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
### Transferring Ownership of a Room There are several scenarios where you might wish to transfer ownership of a room; perhaps you no longer wish to maintain the room yourself; have accidentally removed your, or possibly all privileged users' permissions from a room; or wish to take over an abandoned room. #### How do I transfer ownership of a room? / How do I restore lost privileges to a room?If you do not have permissions yourself, contact a current Admin for the room and get them to follow these steps to promote you.
Admins cannot remove admin permissions from other users, only themselves. Make sure any user prompted to Admin is correct before making changes.
1. Open the room, click `i` / `Room Info` from the top-right 2. Open `Room Settings`, click to `Roles & Permissions` 3. Add a new privileged user, setting their power level to `Admin` 4. Under privileged users, find your username, change your power level from `Admin` to the desired level #### How do I take over an abandoned room? / How do I restore lost privileges to a room without an Admin?For the following you will need Admin access to the homeserver. If you do not manage the homeserver for your room, you will need to contact the support for that homeserver.
When a user is no longer active on your homeserver, or they have been deactivated, you may find some rooms where there are no remaining active Room Admins preventing administration of those rooms. This guide will make extensive use of the Admin API, see our [Getting Started Using the Admin API](https://ems-docs.element.io/books/element-support/page/getting-started-using-the-admin-api) guide for more information, and if required, will also use the Client-Server API, which has an equivalent [Getting Started Using the Client-Server API](https://ems-docs.element.io/books/element-support/page/getting-started-using-the-client-server-api) guide. If there is a non-deactivated but no longer active Room Admin user still present within the room, you can make use of the Admin API [Make Room Admin API](https://matrix-org.github.io/synapse/latest/admin_api/rooms.html#make-room-admin-api) to grant the Admin role to another user: ``` POST https://HOMESERVER_URL/_synapse/admin/v1/rooms/ROOM_ID/make_room_admin { "user_id": "@user:example.com" } ``` However that leaves a problem if there are no longer any admins still within the room. Fortunately, whether they are within the room or not, users retain their power levels unless they demote themselves prior to leaving. So for rooms where you are unsure who holds Room Admin (I.E Power level 100), you can use the Admin API [Room State API](https://matrix-org.github.io/synapse/latest/admin_api/rooms.html#room-state-api):You can find the `ROOM_ID` from Room Settings Advanced
``` GET https://HOMESERVER_URL/_synapse/admin/v1/rooms/ROOM_ID/state ``` This will return a list of states, find the state where `"type": "m.room.power_levels"`, from within that states' `"content": { "users": {} }` you will find a list of users followed by their power level, the Room Admins of the room will have a power level of 100. If the listed Room Admins have been deactivated, you will first reactivate one of them. To reactivate a deactivated user, you can use an Admin Console if you have access to one to perform this operation for you, or you can use the Admin API [Create Or Modify Account API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#create-or-modify-account):`USER_ID` should look something like `@user:example.com`, otherwise known as the full Matrix ID
``` PUT https://HOMESERVER_URL/_synapse/admin/v2/users/USER_ID { "password": "NEW_PASSWORD", "deactivated": false } ``` At this point you should have an active account with Room Admin available that can be used to regain access to management of the room. If you've reactivated a deactivated user, you will have had to set a new password for the account, you could at this point login as the user using a Matrix client. You would then be able to rejoin any required rooms, promoting new users to the Admin role before [deactivating the account](https://ems-docs.element.io/books/element-support/page/deactivating-a-matrix-account). Alternatively you can generate an access token for an account using the Admin API [Login as a user API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#login-as-a-user). ``` POST https://HOMESERVER_URL/_synapse/admin/v1/users/USER_ID/login {} ``` ``` { "access_token": "Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps
You can create a space by clicking the `+ Create a space` button, located at the bottom of the vertical navigation menu on the left when using the [Element Web App](https://app.element.io/). [](https://ems-docs.element.io/uploads/images/gallery/2023-07/image-1689585368792.png) ### Starting a New Space After clicking `Create a space`, you will be presented with the `Create a space` prompt, from here you need to first choose whether the space should be `Public` or `Private`. You will then need to fill in the required details to create your space: [](https://ems-docs.element.io/uploads/images/gallery/2023-07/image-1689585712182.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-07/image-1689585730385.png) - **Avatar:** Here you can upload a picture for your space, this will be visible in the navigation menu and on the space overview. - **Name:** This is the name your space will appear as, if you are making a public room, make sure you choose a name that will be easily found when searching and is appropriate for the homeserver. - **Address:** Available when creating a public space, this is the address for your space. User's will be able to link to it using this address when typing `#` - **Description:** A description of the space and it's purpose will help inform others of why the space exists and help them decide whether it's a space they'd like to join. # Bridges Documentation covering how to use the various Matrix / Element bridges # Setting up Hookshot without E2EE support in encrypted rooms If your Hookshot instance does not have [E2EE support](https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html) enabled but you still want to add it to an encrypted room, you can do this with a couple of caveats: - You cannot send commands to Hookshot in the room as Hookshot cannot read any messages in the room [](https://ems-docs.element.io/uploads/images/gallery/2024-12/image-1733916204476.png) - Any messages sent by Hookshot will be unencrypted To set this up: - Invite your Hookshot bot to the room, this works the same as with unencrypted rooms. The bot follows the same [permissions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html#permissions) in encrypted vs. unencrypted rooms and will join when invited. - Promote the Hookshot bot to the required room permissions. By default, Moderator. - If your Hookshot is configured to automatically [add the widget on invite](https://matrix-org.github.io/matrix-hookshot/latest/advanced/widgets.html?highlight=addOnInvite#configuration), no further configuration is required. - If not, you need to manually send the `setup-widget` command unencrypted. By design, it is impossible to send an unencrypted message into an encrypted room using Element. So to do it: - Grab your account access token from Element settings -> Help & About -> Advanced -> Access Token [](https://ems-docs.element.io/uploads/images/gallery/2024-12/image-1733915620076.png)Your access token grants full access to your Matrix account, threat it carefully like you would with a password
- Grab the room ID for the room you wish to add Hookshot to by clicking the `(i)` `Room Info` button, then Settings in the right column - Under Advanced, copy the Internal room ID [](https://ems-docs.element.io/uploads/images/gallery/2024-12/image-1733915724247.png) - Replace the leading `!` (exclamation mark) with `%21` (for example, `!QrmxBsBKPajykCohPz:localhost:8448` becomes `%21QrmxBsBKPajykCohPz:localhost:8448`) - Find the URL where your Matrix server is exposed. This may not be the same as the domain in your Matrix ID - Open a terminal on your computer. On Windows; PowerShell, on Mac; Terminal - Send the command below for your operating system. Replace `domain-where-your-matrix-server-is-exposed`, `room-id` and `access-toke` with the values from earlier. Note, if you are sending more than one message using your terminal, you need to change `1234` to another value each time. - Mac and Linux: ```bash curl --request PUT \ --url 'https://domain-where-your-matrix-server-is-exposed/_matrix/client/r0/rooms/room-id/send/m.room.message/1234' \ --header 'Authorization: Bearer access-token' \ --header 'content-type: application/json' \ --data '{ "msgtype":"m.text", "body":"!hookshot setup-widget" }' ``` For example: ```bash curl --request PUT \ --url 'https://localhost:8448/_matrix/client/r0/rooms/%21QrmxBsBKPajykCohPz:localhost:8448/send/m.room.message/1234' \ --header 'Authorization: Bearer syt_YWRtaW4_epoEMAUauwwFpsOGJxIg_471LjM' \ --header 'content-type: application/json' \ --data '{ "msgtype":"m.text", "body":"!hookshot setup-widget" }' ``` - Windows: ```powershell $url = "https://domain-where-your-matrix-server-is-exposed/_matrix/client/r0/rooms/room-id/send/m.room.message/1234" $headers = @{ "Authorization" = "Bearer access-token" "Content-Type" = "application/json" } $body = @{ msgtype = "m.text" body = "!hookshot setup-widget" } | ConvertTo-Json Invoke-RestMethod -Uri $url -Method Put -Headers $headers -Body $body ``` For example: ```powershell $url = "https://localhost:8448/_matrix/client/r0/rooms/%21QrmxBsBKPajykCohPz:localhost:8448/send/m.room.message/1234" $headers = @{ "Authorization" = "Bearer syt_YWRtaW4_epoEMAUauwwFpsOGJxIg_471LjM" "Content-Type" = "application/json" } $body = @{ msgtype = "m.text" body = "!hookshot setup-widget" } | ConvertTo-Json Invoke-RestMethod -Uri $url -Method Put -Headers $headers -Body $body ``` [](https://ems-docs.element.io/uploads/images/gallery/2024-12/image-1733916724815.png) [](https://ems-docs.element.io/uploads/images/gallery/2024-12/image-1733923241297.png) My message was sent without encryption and Hookshot responded. You can now use Hookshot via the widget normally. Note that all messages sent by Hookshot remain unencrypted. Element warns you with the red shield on the messages. [](https://ems-docs.element.io/uploads/images/gallery/2024-12/image-1733923333978.png) # Using the Matrix IRC Bridge The Matrix IRC Bridge is an IRC bridge for Matrix that will pass all IRC messages through to Matrix, and all Matrix messages through to IRC. If you're an end user of the bridge, it's unlikely you will need to use the below commands, your IRC Channels may already be bridged to specific Matrix Rooms so you can simply join the Room from Matrix, or the Channel from IRC and communicate with Matrix/IRC users. Our End User focused documentation might be better suited to getting started with Matrix and IRC - [Using the Matrix IRC Bridge as an End User](https://ems-docs.element.io/books/element-support/page/using-the-matrix-irc-bridge-as-an-end-user) Please also refer to the Bridge Documentation for additional guidance. The bridge is currently used on the matrix.org homeserver to bridge a number of popular IRC networks. ### Getting Started with the Matrix IRC BridgeIn this guide we will be using the Matrix.org bridge to the Open and Free Technology Community (OFTC) IRC network. The key information to note is the Room alias format (#_oftc_#channame:matrix.org) and Appservice user (@oftc-irc:matrix.org). Though note this may differ from time of writing, check the link above to up-to-date details.
The Appservice user is the bot that interacts with the bridge, from a Direct Message with this user you will issue commands to connect to the desired channels and perform specific functions. First, invite the user to a DM: [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691576604761.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691578090577.png) Using `@oftc-irc:matrix.org` we start a chat, your first message can be anything to create the room. The bot should join the room and then be responsive to commands. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691578178653.png) ### Matrix IRC Bridge Bot Command Overview Commands to the bot are prefixed with `!`, to get started try `!help`, which should result in the bot listing out the available commands for use. You should see something like the below: **Actions** - `!cmd [irc.example.net] COMMAND [arg0 [arg1 [...]]]`: Issue a raw IRC command. These will not produce a reply.(Note that the command must be all uppercase.) - `!feature feature-name [true/false/default]`: Enable, disable or default a feature's status for your account.Will display the current feature status if true/false/default not given. - `!join [irc.example.net] #channel [key]`: Join a channel (with optional channel key) - `!nick [irc.example.net] DesiredNick`: Change your nick. If no arguments are supplied, your current nick is shown. - `!quit`: Leave all bridged channels, on all networks, and remove your connections to all networks. - `!active`: Mark yourself as active, which will exclude you from any idleness kicks. **Authentication** - `!storepass [irc.example.net] passw0rd`: Store a NickServ OR SASL password (server password) - `!reconnect [irc.example.net]`: Reconnect to an IRC network. - `!removepass [irc.example.net]`: Remove a previously stored NickServ password - `!username [irc.example.net] username`: Store a username to use for future connections. **Info** - `!bridgeversion`: Return the version from matrix-appservice-irc bridge. - `!listrooms [irc.example.net]`: List all of your joined channels, and the rooms they are bridged into. - `!whois [irc.example.net] NickName|@alice:matrix.org`: Do a /whois lookup. If a Matrix User ID is supplied, return information about that user's IRC connection. **Management** *These commands only work for [bridge administrators](https://ems-docs.element.io/link/191#bkmrk-irc-bridge-admins).* - `!unlink !room:example.com irc.example.net #foobar`: Unlink an IRC channel from a Matrix room. You need to be a moderator of the Matrix room or an [administrator of this bridge](https://ems-docs.element.io/link/191#bkmrk-irc-bridge-admins). - `!plumb !room:example.com irc.network.net #channel`: This command allows you to plumb a IRC channel into a room without using the HTTP provisioning API. This command does NOT validate that you have permission to do this on the IRC channel so please take care to ensure that the IRC channel is aware of your actions. You must invite the bridge bot into the Matrix room for this to work. ### Using the Matrix IRC Bridge Depending on your bridge setup you may have multiple IRC Networks accessible from your IRC Bridge bot, if so, you will need to specify the IRC Network after the each command. This guide is using `@oftc-irc:matrix.org` which is dedicated to the W3C IRC network so commands do not need to specify. For any command given arguments wrapped in `[]` are optional, make sure to specify them if required for your usecase. #### Joining a IRC Channel The most basic usage of the bridge is to join IRC channels to talk with IRC users, you can do this with the `!join` command. Simply specify the channel you'd like the join: - `!join [irc.example.net] #channel [key]` [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691578403665.png) The first time you run such a command, the bot will connect to the IRC network, then inform you that you are connected. The nickname your user appears as in IRC is dependant on the bridge's configuration. Using the example above, you can see `[m]` has been appended to the users Matrix display name. If the Channel you are joining hasn't yet been joined via the bot, it will create a Matrix room linking it with the IRC Channel. If the room already exists, the command will simply invite you to the already created room. Likewise, if the Channel doesn't yet exist on the IRC Network, it will be created and your user sent an invite. You will then recieve an invite to a Matrix room, connected to that IRC Channel. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691579350178.png) Once you've joined the room, you can then communicate with others within the channel. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691579708574.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691580515658.png) #### Listing joined IRC Channels After joining a number of IRC Channels you may want to retrieve a list of all the Channels you are joined to, and the associated Matrix rooms. You can do this with the `!listrooms` command. The bot will respond including clickable links to jump straight to the Matrix room. - `!listrooms [irc.example.net]` [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691581430145.png) #### Staying active You can use the `!active` command to mark yourself as active, which will exclude you from any idleness kicks. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691581565496.png) #### Changing your Nickname To change the nickname presented to IRC users, simply use `!nick`. Provide your desired nickname and it will be updated on the IRC Network, you can also not provide any nickname for the bot to output your current nickname. - `!nick [irc.example.net] DesiredNick` [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691580688371.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691580836542.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691580876773.png) #### Finding out more information on IRC / Matrix users You can use the `!whois` command, supplying either a Matrix ID to retrieve their IRC nickname, or a IRC nickname to information on what channels that user is in. The `!whois` command is also useful to test your connection to the IRC network, supply your own Matrix ID and if there's any issues with the connection the command will produce an error. - `!whois [irc.example.net] NickName|@alice:matrix.org` [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691581859325.png) #### Direct Messaging between Matrix and IRC You can start a DM with an IRC user by simply clicking there profile icon from an existing room linked to an IRC Channel. Then from their profile panel, click `Message` to start a chat. Enter a message to create the room (note they will not see this message), then wait for there user to join the room - once joined, you can send a message which will then be sent to the IRC user. IRC users can also start DMs with Matrix users, they can do this by double clicking the Matrix users' name within the participants list of a channel, or if supported by your client, using the `/query NICKNAME` or `/msg NICKNAME MESSAGE` commands. Once a message is sent, the Matrix user will receive an invite from them to start chatting. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691582633480.png) If you know the configuration of your bridge (or by checking existing IRC users), you can also manually start a DM with a user. Simply start a new chat using the username format the bridge uses. In the example above we can see that the format is `@_oftc_NICKNAME:matrix.org`. So we can initiate chats with any nickname by following that format. #### Leaving an IRC Channel Leaving a Channel is simply a case of leaving the Matrix room. Find the room in the [Left Panel](https://ems-docs.element.io/books/element-support/page/the-left-panel), hoover over its name, then click the 3-dot menu then Leave. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691580574311.png) ##### Leaving all IRC Channels If you wish to disconnect from IRC and leave all Channels (/ Matrix linked rooms) you can simply issue the `!quit` command. Doing so will remove you from all the rooms, you can find them again at the bottom of the [Left Panel](https://ems-docs.element.io/books/element-support/page/the-left-panel) under `Historical`. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691581004442.png) ### Advanced Bridge Usage #### IRC Authentication If you need to join the IRC Network using authentication credentials you will need to use the `!storepass` and possibly `!username` commands. With these you can set NickServ / SASL password and username respectively. Once completed, simply use `!reconnect` to rejoin the network with the provided credentials. - `!storepass [irc.example.net] passw0rd` - `!username [irc.example.net] username` - `!reconnect [irc.example.net]` You can also remove your stored password using, you will then need to use `!reconnect` to rejoin without the credential: - `!removepass [irc.example.net]` #### Troubleshooting bridge problems If you are encountering issues with the bridge, first try using `!reconnect`, to see if disconnecting and reconnecting solves your issues. Otherwise `!bridgeversion` is a useful command to advise the version of the bridge. Supply this information, alongside any debug logs to the administrator of the bridge to help them troubleshoot your issue. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691583000864.png) #### Sending raw IRC commands It's possible to use the bot to issue raw IRC commands, to do so you'll need to use `!cmd`, followed by the commmand (in CAPS) and any additional arguments. Unless there is an error with the command, sending `!cmd` will not produce a reply. - `!cmd [irc.example.net] COMMAND [arg0 [arg1 [...]]]` For example, if you wanted to send a private message without creating DM in Matrix, you could use the `/PRIVMSG` IRC command. To do so you'd send: `!cmd PRIVMSG USERNAME MESSAGE` The recipient will then receive the message, but a room in Matrix wont have been created. #### Unlinking an IRC channel from a Matrix room In order to unlink a channel you will need to use the `!unlink` command, followed by the matrix room ID, IRC network and channel name. To successfully perform this action you will need to be a moderator of the Matrix room or an administrator of the bridge. - `!unlink !room:example.com irc.example.net #foobar` You can find the matrix room id by accessing the room's settings page, then within the `Advanced` section you will find the `Internal Room ID`. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691586982296.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691587008743.png) # Using the Matrix IRC Bridge as an End User If your homeserver has the Matrix IRC Bridge configured it will pass messages to and from IRC. Depending on your homeservers' IRC bridge configuration you will interact with IRC through various means; for instance your homeserver may have pre-configured Matrix Rooms bridged to IRC Channels; you may have the ability to join / create bridged rooms dynamically; or you may use private messaging to speak directly with a specific user in IRC. ### Getting Started #### Joining your first IRC Channel via a bridged Matrix Room To start, the most basic usage of the IRC bridge would be to join an IRC Channel to communicate with both Matrix and IRC users together. Your homeserver administrators will have preconfigured bridging from specific IRC Channels to Matrix Rooms, they should be able to advise which rooms you should initially join, for instance, a `#welcome` Channel / Room. When you join a bridged room and send a message for the first time, you'll be sent an invitation to a DM with your homeservers' IRC Bridge Bot. The Matrix User ID of the bridge bot is configurable by your homeservers administrator, but the DM room should be called `IRC Bridge status` prepended with the IRC Network name that the room was bridged to. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1692660623334.png) This room will allow you to keep check on your connection to the IRC network, the initial message from the bridge bot should confirm you connected successfully and the nick name in IRC you have connected as. This is customisable by your homeserver admin, in this guides' example environment, you can see Matrix users appear in IRC as their Display Name followed by `[m]`. #### Messaging in IRC Channels Once you have joined a bridged Matrix Room you're already able to communicate with any IRC users connected to the IRC Channel bridged with the room. You can send messages, emoji 👋, even upload attachments or send voice messages. So what does an IRC user see? While Matrix messages can be formatted in a number of ways, supporting Markdown and HTML, IRC messaging is mostly simple text. You'll find sending simple text messages and emoji works best whereas Markdown and HTML, whilst it will be sent, may not be correctly rendered in an IRC client. When sending attachments, voice messages, and multi-line messages (if restricted by your homeserver) IRC users will instead see a message that you uploaded a file, a voice message or a truncated version of your multi-lined messages each with a link to download / listen / view. From the below examples, of the Element Matrix and mIRC IRC clients respectively, you can see differences in how messages are rendered, that reactions are not supported in IRC etc. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1692664135585.png) [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1692664956715.png) #### Private Messaging IRC Users So long as private messaging is enabled by your administrator you can do so just like with any other Matrix user. IRC users appear in Matrix as Matrix users, you can view the list of people in a room by clicking the `i` icon in the top-right of the client, then selecting `People`. Here you can see all users within the room, including those users created to represent IRC users. The format for their Matrix User IDs is configured by your homeserver administrator, but is usually prefixed with `irc_` followed by their IRC nick name. Just like with any other Matrix user; you can click on a person from this pane; click on their profile picture next to any message they've sent within the room; or simply search for them to initiate the DM. Compose your initial message and send to start a Direct Message with the IRC user. IRC user can likewise start a private message with you, using your IRC nickname - if they do, you will be invited to a DM just like any other Direct Message. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1692665352384.png) ### Going Further #### Changing your IRC Nickname If permitted, you may wish to change the nick name used when you connect to the IRC Network. You can do this by speaking with the bridge bot within the `IRC Bridge status` room you were invited too. Don't worry if you left the room, simply invite the bridge bot into a new DM and it'll work just the same. You can do this by sending `!nick` to the bot, you'll notice the bot will respond advising on how to format the command to change your nick name and supply the nick name your are currently using on each connect IRC Network. [](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1692665943012.png) #### Joining an as-yet unbridged IRC Channel If permitted, you may want to join a conversation within an IRC Channel, not yet bridged to any specific Matrix room. Just like with changing your nick name, you can do this by speaking with the bridge bot within the `IRC Bridge status` room you were invited too. Send the `!join [irc.example.net] #channel [key]` command, making sure to specify the IRC Network if there are multiple, then the IRC Channel name. Make sure to include the key if needed. A complete command to join the `#locked` IRC Channel requiring a key of `password` would look like, `!join irc.example.com #locked password`. Assuming you have permission to use the `!join` command, and that the channel specified is not excluded, you will recieve an invite to the newly created room for the specified IRC Channel. #### Using the bridge bot To delve deeper into using the bridge bot and it's commands, or for a more in-depth doc on the IRC Bridge, you can check out [Using the Matrix IRC Bridge](https://ems-docs.element.io/books/element-support/page/using-the-matrix-irc-bridge). # Using the Matrix XMPP Bridge as an End User If your homeserver has the Matrix XMPP Bridge configured it will pass messages to and from XMPP. You will interact with XMPP by; joining Matrix Rooms specifically bridged to existing XMPP rooms; speaking with XMPP users who have joined public Matrix rooms; or you may use private messaging to speak directly with a specific user in XMPP. ### Getting Started #### Messaging in public Matrix Rooms To start, the most basic usage of the XMPP bridge would be to join a Public Matrix room that XMPP users also join to communicate. You or your homeserver administrators will have created a Public room, which XMPP users can search for using a configured endpoint, by default `matrix` instead of `conference`. That's it, by messaging in this room, anyone who is joined from XMPP will be able to see and respond to your messages. As far as how you appear in XMPP, you'll be displayed in room member lists using your Matrix display name, with a full username formatted based on how your homeserver administrators configured. Usually in a format like `DISPLAYNAME_HOMESERVER@EXTERNALCOMPONENT.XMPPSERVER`, so an example user would look like: ``` alice_example.com@matrix.xmpp.example.com ``` In Matrix, XMPP users will appear with Matrix User IDs, following a format like `@PREFIX_USERNAME=40XMPPSERVER:HOMESERVER`, so an example user would look like: ``` @xmpp_alice=40xmpp.example.com:example.com ``` However it's unlikely you will ever need to directly type these, you can use your native clients' functions to interact with users, just like any other Matrix user in Element, or XMPP user in your XMPP client. #### Messaging in an XMPP room via a bridged Matrix Room The alternative to speaking with XMPP users in a public Matrix room they join, is to join an existing XMPP room. To do this all you need to know is the XMPP rooms name and how your homeservers have configured the room name format in Matrix. By default, XMPP rooms in Matrix are translated following a format like `#PREFIX_XMPPROOMNAME_CONFERENCE.XMPPSERVER:HOMESERVER`, so an example room alias would look like: ``` #_xmpp_exampleroom_conference.xmpp.example.com:example.com ``` So you can either enter this in the room search prompt, or simply send `/join #_xmpp_exampleroom_conference.xmpp.example.com:example.com` in any room (nothing is sent to the room you send this to), for the Element Client to automatically join you to the room. Once joined, exactly as with public Matrix rooms, you can communicate with anyone else in the room just as you normally would in Matrix. #### Private Messaging XMPP Users XMPP users appear in Matrix as Matrix users, you can view the list of people in a room by clicking the `i` icon in the top-right of the client, then selecting `People`. Here you can see all users within the room, including those users created to represent XMPP users. The format for their Matrix User IDs is configured by your homeserver administrator, see above for defaults. Just like with any other Matrix user; you can click on a person from this pane; click on their profile picture next to any message they've sent within the room; or simply search for them to initiate the DM. Compose your initial message and send to start a Direct Message with the XMPP user. A XMPP user can likewise start a private message with you, using your XMPP username - if they do, you will be invited to a DM just like any other Direct Message. # Using the WhatsApp bridge ### Overview This guide describes how to bridge your Element and WhatsApp accounts. This allows you to chat with WhatsApp contacts and groups natively within Element. Before you can carry out the steps in this guide, ensure you have the following: - WhatsApp - You will need a phone with WhatsApp installed and a registered account. - Element - You will need a Matrix account to log into Element, and a WhatsApp bridge set up on your Matrix homeserver. Note: When setting up the Whatsapp bridge you will need to scan a QR code generated in Element from your phone. To make this process as easy as possible, we recommend using Element Web for the initial setup, once set up you can then login to any platform with your Element account and use the bridge which you have set up. However, it is possible with two mobile phones if you can quickly take a photo of the QR code with one phone and then scan it with the original phone. ### Setting up Sign into Element Web using your Element username and password. (If asked to verify your login, see [docs on verifying a new login](https://ems-docs.element.io/books/element-cloud-documentation/page/verify-new-login). Once signed in, start a new direct message with the WhatsApp bridge bot. (It will not work if you create a room with the bridge bot, it needs to be a direct message) The username of the bot will be _@whatsappbot:your.server (for example @whatsappbot:matrix.org)_ Ensure that _your.server_ is the homeserver where the bridge is hosted. This may be different to the homeserver hosting your own account. Click on the suggested **WhatsApp bridge bot**, and click **Go** to start the direct message. [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231103-ktgi.png) You will be taken into a new room with the WhatsApp bridge bot. The bot automatically joins the room. [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231103-kulm.png) Remaining in the room, send the login command by sending **login** into the room. `Tip: You can also send the command **help** to get a list of all available commands.` The bot will generate a QR code to scan from WhatsApp on your phone. [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231103-kvet.png) Leaving Element open, open WhatsApp on your phone for the next step In WhatsApp, tap the three dots **(⋮)** in the top right corner of the app. From the drop-down menu tap **Linked devices**. Tap **LINK A DEVICE**. [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231103-kwvi.png) Tap **OK** to begin scanning the QR code. Scan the QR code generated by the WhatsApp bot in Element. The WhatsApp bridge now shows as a linked device in **DEVICE STATUS**. If this doesn't work the first time, it is likely that the QR code has expired, you will need to repeat the steps again and scan the QR code before it expires. [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231103-kxmz.png) Back in Element, the bridge bot will confirm that you have logged in to WhatsApp. The bridge then creates rooms to allow you to chat with WhatsApp contacts and groups. By default the bridge automatically creates rooms for people or groups you have interacted with in the last week. Others are created as new messages arrive. See below for how to use bridged rooms. Note: WhatsApp requires your phone to connect to your WhatsApp account every 14 days to keep the bridge active, otherwise you will need to QR code scan again. So ensure you open the WhatsApp app every 14 days to ensure you are not disconnected. ### Using direct messages The bridge will automatically invite you to new rooms for your recent contacts. WhatsApp contacts automatically have (WA) added to their display name. To start, click on a room invite and join the room.You will be taken into the new room for your WhatsApp contact. You can now begin chatting with your WhatsApp contact in the same way as any other Element user. (Note that the bridge does not support voice or video calling.) [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231107-jyfe.png) Starting new chats (or resuming older ones that were not automatically set up) can be done with the pm command, followed by the number for the other person in international format. For example to invite whatsapp number +4412345678 you would send the command **pm +4412345678** into the WhatsApp bridge bot room. `Tip: Using the list contacts command retrieves your existing WhatsApp contacts, including their numbers. You can then click on the contact and click message to start chatting.` Once the pm command is sent the bridge will invite you to a new room for the WhatsApp chat. [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231107-kcks.png) ### Using rooms You will automatically be invited to some rooms for WhatsApp group chats that have been automatically created by the bridge. If this has not happened you can manually open an existing group chat. To open an existing WhatsApp group in Element, you can use the list groups command (send the message **list groups** into the WhatsApp bridge bot room) to get a list of all WhatsApp groups. Each will be shown with its ID Use the open command, followed by the ID of the group. For example you can see the Office part ghroup chat has the room ID 447818943525-1636277287, so you would send the command **open 447818943525-1636277287**. The bridge will then create a room for the group and invite you. [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231107-kcks.png) ### Disconnecting from WhatsApp To disconnect WhatsApp from Element enter the logout command, by sending **logout** into the WhatsApp brtidge bot room. This will remove the linked device from WhatsApp. As a further option, the connection to WhatsApp can be forcibly disconnected by using the **delete-session** command. This removes the connection at the Element side but does not perform a graceful logout from WhatsApp. Once logged out, the **delete-all-portals** command can be used to clean up rooms previously created by the bridge. [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231107-kfqi.png) # Using the Telegram Bridge ### Overview This guide describes how to bridge your Element and Telegram accounts. This allows you to chat with Telegram contacts and groups natively within Element. Before you can carry out the steps in this guide, ensure you have the following: - Telegram - You will need a phone with the Telegram app installed and a registered account. - Element - You will need a Matrix account to log into Element, and a Telegram bridge set up on your Matrix homeserver. ### Setting up Sign into Element Web using your Element username and password. (If asked to verify your login, see [docs on verifying login](https://ems-docs.element.io/books/element-cloud-documentation/page/verify-new-login).) Once signed in, start a new direct message with the Telegram bridge bot. (It will not work if you create a room with the bridge bot, it needs to be a direct message) The username of the bot will be _@telegram:your.server (for example @telegram:matrix.org)_ Ensure that _your.server_ is the homeserver where the bridge is hosted. This may be different to the homeserver hosting your own account. Click on the suggested **Telegram bridge bot**, and click **Go** to start the direct message. You will be taken into a new room with the Telegram bridge bot. The bot automatically joins the room. Remaining in the room, send the login command by sending **login** into the room. `Tip: You can also send the command **help** to get a list of all available commands.` Then enter the number of the Telegram account you are wanting to connect to in international format e.g +4412345678. Your Telegram account will then receive a 4 digit login code, enter this code into the Element room to connect. `Note: If you get this wrong the first time, you will need to use the "cancel" command and start again from "login".` Your Telegram account should now be linked to your Element account and the bot should confirm this in your room. [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231123-nbbs.png) ### Using direct messages The bridge will automatically invite you to new rooms for your recent contacts. To start, click on a room invite and join the room. You will be taken into the new room for your Telegram contact. You can now begin chatting with your Telegram contacts in the same way as any other Element user. `Note: The bridge does not support voice or video calling.` To start a chat with a new contact, first ensure you have added the contact in your Telegram contacts. If you send your first message from Telegram you will then get a new invite in Element to join the room. Or it can be done with the **pm** command, followed by the number for the other person in international format. For example to invite Telegram contact number +4412345678 you would send the command **pm +4412345678** into the Telegram bridge bot room. [](https://ems-docs.element.io/uploads/images/gallery/2023-11/scr-20231123-nbzw.png) ### Using rooms You will automatically be invited to some rooms for Telegram group chats that have been automatically created by the bridge. If this has not happened you can manually open an existing group chat. # Element Android/iOS Client Settings Documentation covering the options available within the Element Android/iOS Clients' Settings. # Understanding Push Notifications To best understand how push notifications are setup in Matrix, a good place to start is with the diagram below from the Push Gateway API. ```text +--------------------+ +-------------------+ Matrix HTTP | | | | Notification Protocol | App Developer | | Device Vendor | | | | | +-------------------+ | +----------------+ | | +---------------+ | | | | | | | | | | | | Matrix homeserver +-----> Push Gateway +------> Push Provider | | | | | | | | | | | | +-^-----------------+ | +----------------+ | | +----+----------+ | | | | | | | Matrix | | | | | | Client/Server API + | | | | | | | +--------------------+ +-------------------+ | +--+-+ | | | <-------------------------------------------+ +---+ | | | Provider Push Protocol +----+ Mobile Device or Client ``` The process starts when a user installs a Matrix client, for example on an iOS device or Android device, and signs in. The client is configured with the push gateway location (URL) and also acquires a push key to identify itself from its push provider, Apple Push Notification (APN) service or Firebase Cloud Messaging (FCM). The client then registers a pusher on the users' homeserver providing the URL, push key etc. On the Matrix Homeserver (for instance, Synapse), a pusher is registered for a user. The pusher information details1: - `app_display_name`: A string that will allow the user to identify what application owns this pusher. - `app_id`: This is a reverse-DNS style identifier for the application. Max length, 64 chars. - `url`: The URL to use to send notifications to the push gateway. - `device_display_name`: A string that will allow the user to identify what device owns this pusher. - `pushkey`: This is a unique identifier for this pusher. (Acquired from APN / FCM) 1 See pushers/set and pushers for more information When a notification is received the homeserver sends this information to the registered Push Gateway, i.e. Sygnal from the users' pushers. The push gateway is where you configure your App Types - APNS GCM. The push gateway, Sygnal in this instance, recieves the request and forwards it to the required notification service (APN or FCM) using the pushkey. If successful, the push gateway confirms the success to the homeserver. You can find a good overview of the entire process on Sygnal's Notes for Application Developers. #### What information the payload holds regarding the specific device? Per the above payload example, a pusher contains a display name for the App (client), that app's reverse-DNS style identifier, a device name and finally the push key. The pushkey is the unique identifier of the pusher. See an example of a set pusher from the Client-Server APIs Push Notifications section: ```json { "pushers": [ { "app_display_name": "Appy McAppface", "app_id": "face.mcapp.appy.prod", "data": { "url": "https://example.com/_matrix/push/v1/notify" }, "device_display_name": "Alice's Phone", "kind": "http", "lang": "en-US", "profile_tag": "xyz", "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=" } ] } ``` #### How does e.g Apple APNS know that my device is suppose to get the push notice? When the application on a user's device registers for push notifications, it acquires a pushkey from the push provider. So for iOS, the client will acquire this key from APN and use it when registering the pusher with synapse. #### Does the payload hold any information about my device? E.g. IMEI etc? Per the sample payload provided above, only a `device_display_name` and `pushkey` are included, as such it does not contain a devices' IMEI etc. # Using 'Unified Push' and 'ntfy' for Push Notifications # What is Unified Push? > UnifiedPush is a set of specifications and tools that lets the user choose how push notifications* are delivered. All in a free and open source way. > > [](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1678369653409.png) > > **Unified Push website** The Unified Push website features multiple diagrams detailing the overall process worth viewing - for this setup, per the static version above, we will be utilising the Unified Push specification to have notifications recieved on a Matrix homeserver, sent to a Unified Push compatible push gateway (ntfy) which are relayed to a Unified Push Distributor application (ntfy) installed on a users' device. This distributor application recieves and relays these notifications to applications installed on your device. # What is ntfy? > ntfy (pronounce: notify) is a simple HTTP-based pub-sub notification service. It allows you to send notifications to your phone or desktop via scripts from any computer, entirely without signup, cost or setup. It's also open source if you want to run your own. > > **ntfy website** ntfy comes in two forms, the server and the application. The ntfy server is your push gateway, recieving notifications from your homeserver bound for client devices, it communicates with the ntfy application. The ntfy application is your distributor application, this application is used to subscribe to topics of interest, and specifically for this use-case, subscribing to Unified Push notifications to relay to the Element Android application. # Overview of the process / setup You will need to setup an ntfy server, with a specified domain name and associated certificates, which can access and is accessible by, your Matrix homeserver and end-users' mobile devices. You should also ensure your Certificate Authority (CA) certificate is added to this servers' trust store. Each end-user will need the ntfy distributor application installed on their devices alongside the Element Android application. This application will require the ntfy server address to be changed from the default to your ntfy servers' domain name. Each device should also ensure they too have the required Certicate Authority (CA) certificate added to the device's trust store. Once these essentials are in-place, a user need only open the Element Android application and login to their homeserver. On first login, the application will see the installed ntfy application, and prompt the user for which notification service they wish to use. Once ntfy is selected, a topic is subscribed to within the ntfy application and the push gateway (the ntfy server) is registered as a 'pusher' for the logged in user on the home server. # Getting Started ## Setting up the ntfy server The ntfy docs are the best place to start as they are updated with each new release. For the ntfy server, the Self-Hosting Installation section will cover everything you need to get the server binaries installed on your system. Then the subsequent Configuration section will cover fine-tuning your desired configuration, i.e. Disabling the built-in web application, which isn't used for this use case. ### Pre-Installation The server will need access to the ntfy, for internet connect devices you can directly follow the step in Installation below. For Airgapped systems, please source the required binaries linked to from the Linux Binaries section of the Installation section. Ensure the binary is made available to the airgapped server. Configure your DNS appropriately such as that a sub-domain is setup for the server, i.e. `ntfy.example.com` and is accessible from your homeserver and end-user devices. If required, set the correct DNS settings on the ntfy server, you can verify DNS is resolving correctly by testing your newly setup ntfy domain, i.e. `ping ntfy.example.com`. Generate the required certificates for the sub-domain from your Certificate Authority (CA) and ensure the `.key` & `.crt` is made available to the server (if not using a proxy). The Certificate Authority (CA) certificate should also be made available to the server and installed to it's trust store. The process for this is dependant on your system, for Ubuntu, the Ubuntu Server Docs - Installing a root CA certificate in the trust store are a good choice. Ensure the domain certificate / key files are located in a suitable location accessible by the user running the ntfy binary, and note their location to be added to the ntfy configuration file later, i.e. `/home/example/ntfy/ntfy.example.com.key` & `/home/example/ntfy/ntfy.example.com.crt`. Ensure the ntfy server firewall allows port 80 and 443, the process for this is dependant on your system & firewall, for Ubuntu using the built-in firewall, the Ubuntu Server Docs - Security - Firewall cover the required steps. >❗As above, following the official ntfy documentation is best here, as it is updated with each new release. This guide will focus on steps taken outside the basic install step. For configuration, please check the config sample is up-to-date and adapt as required for your specific environment / setup. ### Installation There are two main choices for installation for Linux systems, manual installation of the Linux binaries or installation via a package / repository - follow the appropriate steps for your system. ### Server Configuration Once installed you can configure the server by config file, command line or using environment variables. For this guide we will make use of the config file, typically located `/etc/ntfy/server.yml`. The official documentation covers all configuration options, including if the server is behind a proxy, setting up access control etc. A basic configuration utilising HTTPS and Certificates on the server, is included below. (This example also disables the web client setup by default) **Note:** for access control, please follow the Unified Push guidance on ensuring Synapse has anonymous write access to the topic used for push messages. See the Unified Push Example under the Access Control section and the linked Access Control Example from the Unified Push website. ```yaml base-url: "http://ntfy.example.com" listen-http: ":80" listen-https: ":443" key-file: "/home/example/ntfy/ntfy.example.com.key" cert-file: "/home/example/ntfy/ntfy.example.com.crt" cache-file: "/var/cache/ntfy/cache.db" attachment-cache-dir: "/var/cache/ntfy/attachments" web-root: disable ``` Modify the config as required, correcting the `base-url`, `key-file` / `cert-file` locations and `cache-file` / `attachment-cache-dir` if desired. Before running the server, please ensure the `/var/cache/ntfy` directory (or wherever you have specified as the `cache-file` location exists), if not simply `sudo mkdir /var/cache/ntfy`will prevent any errors on first-run. A full list of Config Options is available, once configured as desired, run the server so it is ready to recieve notifications from your homeserver. ### Verification These tests can be performed to ensure the server is correctly setup and accessible from all devices involved: #### Tests run from the ntfy server First perform a basic connection test to the ntfy domain name, i.e. `ping https://ntfy.example.com`, this will confirm DNS resolves correctly on the ntfy server itself. Then do the same but to your homeserver, i.e. `ping https://synapse.example.com`, as well as a test mobile device connected to the same Wi-Fi network as your end-users, i.e. `ping 10.0.0.76` (The IP address of the mobile device). Next to confirm the server is correctly hosting a push gateway that your homeserver can make use of, confirm `https://ntfy.example.com/_matrix/push/v1/notify` outputs `{"unifiedpush":{"gateway":"matrix"}}`. Using the above URL, you can also verify that the ntfy server trusts the `ntfy.example.com` certificate and so the Certificate Authority is trusted. To locally test the ntfy server can recieve messages, follow the steps from the Sending messages section of the ntfy documentation. The ntfy logs should confirm the message has been recieved, but you could also, if not disabled, use the web app provided by the server. #### Tests run from the homeserver First perform a basic connection test to the ntfy domain name, i.e. `ping https://ntfy.example.com`, this will confirm DNS resolves correctly to the ntfy server. Next to confirm the homeserver is able to access the push gateway by confirming `https://ntfy.example.com/_matrix/push/v1/notify` outputs `{"unifiedpush":{"gateway":"matrix"}}`. You should also confirm that the `ntfy.example.com` certificate is trusted, adding it's Certificate Authority (CA) certificate to the servers' trust store. For On-Premise setups, please refer to the [On-Premise Documentaion](https://ems-docs.element.io/books/element-server-suite-documentation-lts-2310) for guidance on certification setup. You could also test the ntfy server can recieve messages, by following the steps from the Sending messages section of the ntfy documentation. The ntfy logs should confirm the message has been recieved, but you could also, if not disabled, access the web app provided by the server. #### Tests run from a test mobile device First perform a basic connection test to the ntfy domain name, for a mobile device it's easiest to visit `https://ntfy.example.com/_matrix/push/v1/notify` from your web browser, this will confirm DNS resolves correctly to the ntfy server and the push gateway is available too. ## Setting up a mobile device First ensure the Certificate Authority (CA) certificate that signed the ntfy server domain certificate is added to the devices trust store. You can do this on Android by following these steps: - Open your phone's Settings app, search 'CA Certificate' - Tap 'CA certificate' to be taken to the 'Install a certificate' screen, then tap 'CA certificate' - Tap 'Install anyway' and enter your device PIN / Password - Locate where you saved the certificate and tap the file, i.e. `ca.pem` For the end-user mobile device they will need both the Element Android application, and the ntfy distributor application. Once both are installed, open the ntfy application, click the 3-dot menu from the top right, and press 'Settings'. Under the 'General' section, find 'Defualt server' and press to modify. Replace with your ntfy server domain name, i.e. `https://ntfy.example.com`. You may also notice a warning prompt banner across the top of the main application screen, follow it's steps to ensure the application is being optimised for battery as this may prevent a reliable notification experience. Open the Element application and complete the sign-in flow, once logged in, you will be presented with a prompt 'Choose how to receive notifications', then select 'ntfy'. ### Verification These tests can be performed to ensure the mobile device is correctly setup and recieves notifications correctly: First open the ntfy application and subscribe to a test topic by clicking the '+' icon at the bottom right, then entering an example topic name, i.e. `test`. Follow the steps from the Sending messages section of the ntfy documentation sending a message to the `test` topic (or whichever topic name you specified above). The phone should recieve a notification that the topic has recieved the message. This will confirm the ntfy applications connection to the ntfy server and its ability to successfully recieve messages. Next confirm the presence of an entry within your 'Subscribed Topics' of the ntfy application generated by the Element application. It will have a topic name starting `ntfy.example.com/up`, and below will confirm it was added by the `im.vector.app` / `im.vector.app.debug` and the protocol, `Unified Push`. Ensure on the mobile device, the Element application is not in the foreground. From another device, use a Matrix client to send a message to the account logged into the mobile device. The phone should recieve a notification that they have recieved the message. This will confirm successful registration of the ntfy server as the push gateway for the logged in user. # Result You should now have setup the Unified Push infrastructure so you can recieve push notifications from the Element application via your own self-hosted servers. # Advanced Administration Documentation covering more advanced topics relating to the administration of your homeserver. # Getting Started Using the Admin API The Synapse Admin API allows administration of your homeserver, such as managing users, rooms and media. In order to make use of the API you will need to have an admin user account present on the homeserver you wish to manage. ### Promoting a Matrix Account to Admin If you're an EMS customer, you can create / manage your users via the Server Admin tab of the EMS Control Panel. If you're an ESS customer, you can create / manage your users via your admin dashboard, or via the Admin tab available when running the installer. Promote the user you will be using to Admin by clicking on the desired user, and checking the `Admin` checkbox and confirming. ### Getting your `access_token` In order to use the Synapse Admin API you will need to authenticate your calls to the API using an `access_token` from an Admin user account. You can find your `access_token` from the `Help & About` section of your settings. Check out the [Help & About](https://ems-docs.element.io/books/element-support/page/help-about) page from the [Element Web/Desktop Client Settings](https://ems-docs.element.io/books/element-support/chapter/element-webdesktop-client-settings) chapter for more guidance. ### Making an Admin API request Using your preferred method, you will need to authenticate each request to an Admin API endpoint by providing the token as either a query parameter or a request header. To add it as a request header in cURL, you can use the following, replacing `syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk` with your own `access_token`: ```bash curl --header "Authorization: Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk" -X GET http://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.com ``` Here is the equivalent action using Python and the `requests` library: ```python import requests headers = { 'Authorization': 'Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk', } response = requests.get('http://127.0.0.1:8008/_synapse/admin/v2/users/@foo:bar.com', headers=headers) ``` Further details on the using the API are out-of-scope for this documentation, please consult the Synapse Admin API documentation. You will find multiple sections covering its use, such as Rooms, Users and Media. # Getting Started Using the Client-Server API The Client-Server API allows a user to perform any action they could via a Matrix client programatically. In order to make use of the API you will need to retrieve an access token for your account. ### Getting your `access_token` In order to use the Client-Server API you will need to authenticate your calls to the API using an `access_token` from your user account. You can find your `access_token` from the `Help & About` section of your settings. Check out the [Help & About](https://ems-docs.element.io/books/element-support/page/help-about) page from the [Element Web/Desktop Client Settings](https://ems-docs.element.io/books/element-support/chapter/element-webdesktop-client-settings) chapter for more guidance. ### Making a Client-Server API request Using your preferred method, you will need to authenticate each request to a Client-Server API endpoint by providing the token as either a query parameter or a request header. To add it as a request header in cURL, you can use the following, replacing `syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk` with your own `access_token`: ```bash curl --header "Authorization: Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk" -X GET https://HOMESERVER_URL/_matrix/client/v0/profile/@user:example.com ``` Here is the equivalent action using Python and the `requests` library: ```python import requests headers = { 'Authorization': 'Bearer syt_AjfVef2_L33JNpafeif_0feKJfeaf0CQpoZk', } response = requests.get('https://HOMESERVER_URL/_matrix/client/v0/profile/@user:example.com', headers=headers) ``` Further details on the using the API are out-of-scope for this documentation, please consult the Client-Server API documentation. # Using Python with the Admin + Client-Server APIs You can use Python to make consume and utilise APIs, including those available with Matrix - such as the Synapse Admin API, and the Matrix Client-Server API. See the below docs to learn more about them before progressing with this guide. - [Getting Started Using the Admin API](https://ems-docs.element.io/books/element-support/page/getting-started-using-the-admin-api) - [Getting Started Using the Client-Server API](https://ems-docs.element.io/books/element-support/page/getting-started-using-the-client-server-api) The key requirement before progressing is getting the Matrix Accounts' `access_token`, if your using the Synapse Admin API, you must use a Matrix Account which is a Synapse Admin. #### Using `python` You will need [Python](https://www.python.org/downloads/) setup on your system to make use of the script. The best way to use Python is to keep individual projects / scripts in separate virtual environments (`venv`). The documentation on this can be found [here](https://docs.python.org/3/library/venv.html), for example on Windows you'd use: ```shell python -m venv .\myPythonProject\ .\myPythonProject\Scripts\Activate.ps1 ``` The script uses the `requests` library in order to make the API requests, to install in in you `venv`, after activating run: ```shell python -m pip install requests ``` You will then be able to run scripts you create by using: ```shell python .\myPythonProject\scriptName.py ``` #### Writing a `python` script At it's most basic, you will need to setup the below template within your script: ```python import requests homeseverURL = 'example.com' accountToken = 'accountTokenStringExample' requestHeaders = { 'Authorization': 'Bearer ' + accountToken } requestData = { 'key': 'value' } getResponse = requests.post('API Endpoint URL', headers=requestHeaders).json() postResponse = requests.post('API Endpoint URL', headers=requestHeaders, data=requestData).json() ```The below examples are for reference only, when running any scripts with any access to your homeserver you should verify and understand the script yourself, the below may end up out-dated so please use the various linked documentation before running. We do not provide any support for the following scripts.
##### Example #1: Join Users to Rooms Let's say you wanted to join a list of users to a list of rooms, you would adapt this template to something like the below to make use of the [Edit Room Membership API](https://matrix-org.github.io/synapse/latest/admin_api/room_membership.html): ```python import requests # Homeserver homeserverURL = 'synapse.example.com' # Credentials accountToken = 'accountTokenStringExample' # Rooms to Auto-Join roomAliasList = ['#room1:example.com', '#room2:example.com'] # Users to Auto-Join userList = ['@user1:example.com', '@user2:example.com'] # API Auth Header requestHeaders = { 'Authorization': 'Bearer ' + accountToken, } # Loop through all rooms for roomAlias in roomAliasList: # Construct API Endpoint URL editRoomMembershipURL = 'https://' + homeserverURL + '/_synapse/admin/v1/join/' + roomAlias # Loop through all users for user in userList: # Construct POST contents editRoomMembershipData = { "user_id": user } # Send Request response = requests.post(editRoomMembershipURL, headers=requestHeaders, data=editRoomMembershipData).json() ``` ##### Example #2: Delete Older Media If you are looking to remove all media older than a specific Unix Timestamp, you could adjust the template above to make use of [Delete local media by date or size](https://matrix-org.github.io/synapse/latest/admin_api/media_admin_api.html#delete-local-media-by-date-or-size). ```python import requests # Homeserver homeserverURL = 'synapse.example.com' # Credentials accountToken = 'accountTokenStringExample' # API Auth Header requestHeaders = { 'Authorization': 'Bearer ' + accountToken, } # Construct API Endpoint URL unixTimestamp : str = '1672531200000' deleteMediaURL = 'https://' + homeserverURL + '/_synapse/admin/v1/media/delete?before_ts=' + unixTimestamp # Send Request response = requests.post(deleteMediaURL, headers=requestHeaders).json() ``` ##### Example #3: Remove specific `external_ids` If you are looking to remove specific External IDs from user accounts, you can use the below. Simply replace the `url`, `adminToken` and `authProvider` variables at the top of the script with the desired values. This script makes use of [List Accounts](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#list-accounts) to get all users, [Query User Account](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#query-user-account) to get each users' `external_ids` and finally [Create or Modify Account](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#create-or-modify-account) to remove that specific `external_id`. ```python import requests import json url = 'synapse.example.com' # Replace with Synapse FQDN adminToken = 'exampleToken' # Replace with Admin Token authProvider = 'exampleAuth'# Replace with Auth Provider to Delete headers = { 'Authorization': 'Bearer ' + adminToken, } userAccountURL = 'https://' + url + '/_synapse/admin/v2/users' # GET ALL USER ACCOUNTS def get_all_users(): all_users = [] list_account_from = 0 users = requests.get(userAccountURL + '?limit=5', headers=headers).json() all_users.extend(users['users']) while 'next_token' in users.keys(): list_account_from = int(users['next_token']) users = requests.get(userAccountURL + '?from=' + str(list_account_from), headers=headers).json() all_users.extend(users['users']) return all_users # DELETE EXTERNAL ID WITH SPECIFIED AUTH PROVIDER def delete_matching_external_id(auth_provider, user_accounts): for user in user_accounts: user_details = requests.get(userAccountURL + '/' + user['name'], headers=headers).json() if 'external_ids' in user_details.keys(): body = { 'external_ids': [] } for external_id in user_details['external_ids']: if external_id['auth_provider'] != auth_provider: body['external_ids'].append(external_id) body_json = json.dumps(body) result = requests.put(userAccountURL + '/' + user['name'], headers=headers, data=body_json).json() delete_matching_external_id(authProvider, get_all_users()) ```