Element Support

Platform-agnostic (Cloud / On-Premise) documentation for Matrix, the Element clients etc. and troubleshooting / getting support.

Quick Start Guide

EMS Docs version of the Element Quick Start Guide - https://element.io/user-guide

Quick Start Guide

Onboarding

If you are a new user click Create Account to register.

Select where to host your account by choosing a “homeserver”. You can use the custom server options to sign into other Matrix servers by specifying a homeserver URL. This allows you to use Element with an existing Matrix account on a different homeserver.

create_account

homeserver

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.

    setup_secure_backup

  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.

    generate_security_key

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.

    invite_to_room

  2. This will bring up their information and options, including one named "verify".

    user_profile

  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.

    session_verification

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.

    verification_request_prompt

  2. Next you will be asked to either scan a QR code with your mobile camera or compare unique emoji's.

    verify_other_login_prompt

  3. A green shield will show once the process is complete.

    green_shield

  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.

    security_and_privacy_settings

Quick Start Guide

The Left Panel

the_left_panel

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".

accessing_all_settings

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.

create_space

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.

public_or_private

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

find_a_room

Create a room

create_a_room

Leave a room

leave_a_room

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.

notification_settings

F. People

This is where one-to-one chats take place.

start_a_chat

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.

customize_your_appearance

Quick Start Guide

The Middle Panel

the_middle_panel

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).

room_header

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.

reply_in_thread

You can see Thread responses and respond/react to them.

message_with_reply_in_thread

And see Threads in a room on the Thread panel.

thread_panel

Tap on a message to bring up options then "Thread / Reply in thread"

reply_in_thread

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.

voice_messages

Quick Start Guide

The Right Panel

the_right_panel

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.

room_information

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.

roles_and_permissions_settings

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

Quick Start Guide

Frequently Asked Questions

Account management

How do I reset my password?

Do I need an email address to register?

What is the username used for?

Can I register with a phone number?

Chat

How can I mention someone?

With what type of mentions will I get notified?

How do I send a file?

Can I upload a file from a mobile device?

How can I invite a contact to use Element?

Is there a way to know if a message has been read?

How can I search for a file or message?

Settings

How do I change my account settings?

How do I change my notification settings?

How do I set up email notifications?

How can I change my display name?

How do I reset my password?

Why would I need to associate an email address to my account?

Rooms

How can I change the settings for a specific chat or room?

Can I restrict the access of a room to a given set of people?

Can I limit the access of a room to people knowing its existence?

Can I make a room publicly discoverable?

Will anyone be able to join my room if I list it in the directory?

If I make the room accessible to anyone, will new joiners be able to read the history?

Why would I want to make the history visible to anyone?

What is a room address?

What is a favorite room?

What is a low priority room?

What is the “historical” section?

As a room admin, can I decide what members can do?

Privacy, abuse and notices

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?

How do I report on content in Element?

How do I submit an abuse report?

How do I request a DMCA takedown?

End-to-end encryption

What is encryption?

What is end-to-end encryption?

Who can read my messages?

Why can't I read a message?

What is Key Backup?

Is it safe to back up my encryption keys to your servers?

How do I set up key backup?

How do I restore from key backup?

How do I request the key from another device via key share?

What is a 'device'?

What does it mean to verify or trust a device in Element?

Are all of my messages encrypted?

Can I search in encrypted rooms?

What does the red/green symbol mean at the top of the encrypted room?

Reporting bugs and requesting features

How do I submit a bug report?

How do I request a new feature?

Threads Beta

Why does my homeserver need to support threads?

How does the room list unread badge work in regards to threads?

How can I avoid missing messages posted to threads?

Why does the thread list unread badge show only a dot, and not an unread count?

Will the room list unread badge be incremented if someone sends a message in a thread I did not participate in?

Why does a thread show as unread even if I already read it on another device?

Where are the read receipts in my threads?

Are push/email notifications supported?

Understanding Your Element Accounts

There are two different accounts you will have when signing up with Element. The first is your EMS Account, it is used to manage your subscriptions and configure them. Second is your Matrix account, this is the account you login to via any Matrix Client, such as the Element Web App or Element Mobile / Desktop Apps, and actively use to message other users.

EMS Account

When you sign up for a service with Element, you do so using your EMS Account. This account holds your personal details, company details (if applicable) and billing address / payment information.

Attached to this account are all your subscriptions, as well as the ability to manage those subscriptions' configuration, including creating additional subscriptions and cancelling existing ones.

You can access your account, and manage the above via the 'Admin Dashboard', you can find this by visiting Element.io selecting 'Sign In' then 'Admin Dashboard'. Alternatively you can access it directly from here EMS Control Panel.

All different subscriptions are managed through your EMS account, the admin dashboard will provide different management options depending on; if you host a homeserver with us; have an Element One account; or self-host using Element On-Premise.

You can find dedicated documentation depending on your subscription via EMS Cloud Documentation or Element On-Premise Documentation.

Deleting an EMS account

If you wish to delete your EMS account entirely, you can do so from your user account page in the [EMS Control Panel](https://ems.element.io/user/account) by clicking the "delete account" button and confirming. This will delete all hosts and subscriptions before removing your user account.

Matrix Account

Your Matrix account is created on the homeserver of your choice, and you use it via a Matrix client to message others, make calls and join rooms etc. Following setup of a subscription, you will be provided your homeserver details, this maybe something you specified yourself or set depending on your subscription.

See our Matrix Account Management documentation for information covering creation and management of your Matrix account.

Cloud Hosted

If you have chosen for us to host your own dedicated homeserver in the cloud, you will need to create an account on the homeserver. Deployed alongside the homeserver is a dedicated Matrix web client accessible, by default, from the homeserver URL. When using this client, your homeserver URL will already be applied for you.

Alternatively you can use any other Matrix client of your choosing, simply make sure to correctly set your homeserver before registering for an account.

Self Hosted

If you are self-hosting your homeserver, you will need to create an account on the homeserver. As part of your configuration during the On-Premise setup process, you will have specified a sub-domain for your dedicated Matrix web client. You can access that URL to get started, when using this client, your homeserver URL will already be applied for you.

Alternatively you can use any other Matrix client of your choosing, simply make sure to correctly set your homeserver before registering for an account.

Deactivating your Matrix Account

If you'd like to deactivate your Matrix Account, check our Deactivating a Matrix Account page for guidance.

Element One

An Element One subscription is essentially a combination of both an EMS account and a Matrix account. While they are technically separate, your EMS account is used to authenticate accessing your Matrix account so you'll only have 1 login. It is however worth reading the above sections to understand the differences between them.

If you have signed up for an Element One account, you will have created your Matrix account, i.e. @example:one.ems.host, as part of the setup flow. A dedicated Matrix web client is accessible via Element One. When using this client, you'll be prompted for your EMS account login, which will seamlessly log you into your Matrix account.

Alternatively you can use any other Matrix client of your choosing, simply make sure to correctly set your homeserver to one.element.io and you'll be able to login using your EMS account.

Deleting an Element One account

You can manage or cancel your Element One subscription on by logging into the EMS Control Panel Element One page.

Matrix Account Management

Unsure what an EMS account is, see the 'Understanding Your Element Accounts' page above.

Matrix Account Management

Creating a Matrix Account

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.

create_account_prompt

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
{
    "password": "user_password",
    "displayname": "User",
    "threepids": [
        {
            "medium": "email",
            "address": "<user_mail_1>"
        },
        {
            "medium": "email",
            "address": "<user_mail_2>"
        }
    ],
    "external_ids": [
        {
            "auth_provider": "<provider1>",
            "external_id": "<user_id_provider_1>"
        },
        {
            "auth_provider": "<provider2>",
            "external_id": "<user_id_provider_2>"
        }
    ],
    "avatar_url": "<avatar_url>",
    "admin": false,
    "deactivated": false
}
Matrix Account Management

Securing a Matrix Account

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

  2. Enter your email address and click Add

  3. When you get this message, check your email

  4. Click the link in the email. Make sure it opens in another tab/window, leaving your Element client where it is

  5. When you get this message, you can close the verification tab/window and return to Element

  6. Go back to Element and click Continue

  7. Enter your account password or confirm using SSO, then click Continue

  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

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
{
    "threepids": [
        {
            "medium": "email",
            "address": "<user_mail_1>"
        },
        {
            "medium": "email",
            "address": "<user_mail_2>"
        }
    ],
}
Matrix Account Management

Changing a Matrix Account password

Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps

Changing your Matrix Account password

If 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 [![](https://ems-docs.element.io/uploads/images/gallery/2024-07/scaled-1680-/image-1721651752111-24-15-

    You might want to export your E2E room keys. Just to be on the safe side in case something goes wrong. See also Export and Import E2E Room Keys

  2. Enter your current password and your new password

  3. Click OK

  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
{
    "password": "new_password"
}
Matrix Account Management

Recovering a Matrix Account

Disclaimer: 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

Recovering your Matrix Account

This 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

  2. Click Sign out

  3. Click "Not sure of your password? Set a new one"

  4. Enter your email address, and a new password. Then click Send Reset Email

  5. When you get this message, check your email

  6. Click the link in the email. Make sure it opens in new browser tab, leaving your Element client open

  7. Click Confirm changing my password

  8. You can now close this tab and return to Element

  9. Click I have verified my email address

  10. Click Return to login screen

  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.

Matrix Account Management

Deactivating a Matrix Account

Disclaimer: 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:

deactivate_account_warning_and_confirmation_prompt

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
{
    "erase": true
}
Matrix Account Management

Reactivating a Matrix Account

Disclaimer: 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.

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
{
    "password": "new_password"
    "deactivated": false
}

EMS Account Management

Unsure what an EMS account is, see the 'Understanding Your Element Accounts' page above.

EMS Account Management

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.

element_io_sign_in

Simply click Register and fill in the information requested to create and account. Note: Your password must be a minimum length of 12 characters.

element_io_sign_up

Click Next Step to move to email verification, if you don't recieve the email, you can request it be resent from this page.

element_io_email_verification

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.

element_io_email_confirm

element_io_email_verified

With your email verified and account created, repeat the steps to open the EMS Control Panel, or click the link. Login with your details, then accept the Terms and Conditions.

element_io_terms_and_conditions

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.

element_one_sign_up

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.

element_one_account_setup

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.

onpremise_trial_register

onpremise_trial_terms

onpremise_trial_email

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.

ems_account_register

ems_account_terms

EMS Account Management

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.

element_io_navigation_sign_in

ems_sign_in

Click Your Account, found in the top right, then select Account, or goes directly there from this link, Account Page.

your_account

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.

your_account_settings

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.

element_account_management

two_factor_authentication_settings

You will need to reauthenticate to confirm your identity, then follow the steps provided to setup a mobile authenticator.

identity_confirmation

mobile_authenticator_setup

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.

two_factor_authentication_settings_post_setup

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.

element_io_navigation_sign_in

ems_sign_in

Click Your Account, found in the top right, then select Account, or goes directly there from this link, Account Page.

your_account

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.

your_account_settings

verify_email_prompt

You will recieve an email, simply click the Confirm Email Address button in the email to verify this new address.

verification_email

EMS Account Management

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.

element_io_navigation_sign_in

ems_sign_in

Click Your Account, found in the top right, then select Account, or goes directly there from this link, Account Page.

your_account

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.

your_account_settings

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.

element_account_management

basic_authentication_settings

You will need to reauthenticate to confirm your identity, then follow the steps provided to setup a mobile authenticator.

identity_confirmation

Finally, you will be presented with the screen to update your password. Confirm it and then click Submit to change your account password.

password_update

EMS Account Management

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.

element_io_navigation_sign_in

ems_sign_in

Click Your Account, found in the top right, then select Account, or goes directly there from this link, Account Page.

your_account

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.

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.

Element Web/Desktop Client Settings

Documentation covering the options available within the Element Web/Desktop Clients' Settings.

Element Web/Desktop Client Settings

Accessing General Settings

Disclaimer: 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

general_settings

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.

Element Web/Desktop Client Settings

Appearance Settings

Disclaimer: 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

appearance_settings

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.

Element Web/Desktop Client Settings

Notification Settings

Disclaimer: 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

notification_settings

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'.

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:

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.

Element Web/Desktop Client Settings

Preference Settings

Disclaimer: 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

preference_settings

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.

Element Web/Desktop Client Settings

Keyboard Settings

Disclaimer: 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

keyboard_shortcuts

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.

Element Web/Desktop Client Settings

Sidebar Settings

Disclaimer: 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

sidebar_settings

The sidebar settings controls what Spaces to show down the sidebar on the left.

Home: Home is useful for getting an overview of everything.

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:

sidebar

Element Web/Desktop Client Settings

Voice & Video Settings

Disclaimer: 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

voice_and_video_settings

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.

request_media_permissions_prompt

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.

default_device_settings

Element Web/Desktop Client Settings

WIP Security & Privacy Settings

Disclaimer: 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

Element Web/Desktop Client Settings

Sessions

Disclaimer: 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

session_settings

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

security_recommendations

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

current_session

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.

sign_out_3_dot_menu

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.

current_session_details

Other Sessions

other_sessions

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.

sign_out_all_3_dot_menu

sessions_selected_bar

Along the grey bar, you can also filter the view of other sessions on various options:

session_filter_menu

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.

Element Web/Desktop Client Settings

Labs

Disclaimer: 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

labs_settings

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.

Element Web/Desktop Client Settings

Help & About

Disclaimer: 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

help_and_about_settings

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:

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.

Matrix Rooms

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.

Matrix Rooms

Getting Started: Creating a Room

Disclaimer: 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.

plus_button

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.

direct_message_prompt

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.

user_search_users_to_be_invited

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.

private_room_creation_prompt public_room_creation_prompt

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

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.

Matrix Rooms

WIP Getting Started: Using a Room

Disclaimer: This guide refers to using the Element Matrix clients, Element Web or Element Desktop apps

Joining a Room

Configuring a Room

Notifications

From this section, you can managed your personal notification settings. The options you choose

room_notifications_settings

Leaving a 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.

Matrix Rooms

Managing a Room: Room Info

Disclaimer: 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.

room_info_panel

People

From this section, you can invite more people to the room and view the existing members.

people_in_room

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.

user_profile

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.

files

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.

poll_history

active_polls_poll_details

Export Chat

From this section, you can export your rooms message history (including attachments if needed) in HTML, Plain Text or JSON format.

export_chat_prompt

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.

share_room_prompt

What's Next?

Room Settings

Now you've mastered this section, try the next in the Matrix Rooms: Managing a Room series, Room Settings, for details on available room settings.

Matrix Rooms

Managing a Room: Room Settings

Disclaimer: 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:

room_settings

Or by hovering over the room name from the room list, clicking the 3-dot menu, then selecting Settings:

room_3_dot_menu

You will be presented with the Room Settings screen, and various navigation options, for details on each of these screens, see the below sections:

room_settings_navigation_menu

General

From this section, you can customize how your room looks and is accessed:

general_settings

General

Check the FAQ Entry for details on What is the preferred resolution for room and space icons?

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.

Local Addresses

Set addresses for this room so users can find this room through your homeserver.

Other

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.

security-and-privacy-settings

Access

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.

roles_and_permissions_settings

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 Users

Setting 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.

banned_users

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.

Actions and Default Power Levels

Notifications

This section configures your personal notification settings and isn't a management option applicable to all room users. 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 and specifically Using a Room for notification configuration.

Poll History

This section is another way to access Poll History, you can also access simply via the Room Info pane. To learn more, check the Room Info doc from our 'Managing a Room' series.

Advanced

From this section, you can confirm the current room version as well as the Internal Room ID.

advanced_settings

What's Next?

Advanced Room Management

Now you've mastered this section, try the next in the Matrix Rooms: Managing a Room series, Advanced Room Management, for details on available room settings.

Matrix Rooms

Managing a Room: Advanced Room Management

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 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 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 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:

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:

`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.

Alternatively you can generate an access token for an account using the Admin API Login as a user API.

POST https://HOMESERVER_URL/_synapse/admin/v1/users/USER_ID/login
{}
{
    "access_token": "<opaque_access_token_string>"
}

The users' access token can be used by the Client-Server API to perform actions, such as joining rooms and changing room permissions.

To join a room you will use the Client-Server API Join API

POST https://HOMESERVER_URL/_matrix/client/v3/join/ROOM_ID
{}

Finally, you can set the power levels for users within a room using the Client-Server API Events API:

PUT https://HOMESERVER_URL/_matrix/client/v3/rooms/ROOM_ID/state/m.room.power_levels
{
    "users": {
        "@user:example.com": 100
    }
}
Important Notes

Any deactivated user that was reactivated via these steps should be deactivated once again following the process. You can do this a number of ways, see our Deactivating a Matrix Account documentation for further guidance.

The original Room Admin will still retain their admin power level, as Room Admins are not able to demote other admins, for deactivated user this isn't an issue however if the user is still active and you want to demote them you should repeat the final step. Using the Client-Server API Events API send that users' own username with the power level you want them to have.

Removing a Room

There is no way to unilaterally delete a room unless you own the homeserver is it on, however an invite-only room will no longer be able to be joined once all members of the room have left. As an admin it is possible to remove people from the room via the Room Info panel see the Managing a Room: Room Info page, once no other members remain, leaving the room will offer a final prompt to confirm the action.

Tombstoning a Room

An alternative to everyone leaving a room, and a new one being created is to Tombstone it. This acts like closing a room and pointing it to a replacement. You can find the steps for this on our FAQ Page.

Deleting a Room

If you manage a homeserver you can delete a room from it, you can find the steps for doing this if you're an EMS customer on our FAQ Page. Rooms across multiple homeservers will only be deleted from your homeserver.

Matrix Spaces

Documentation covering from basic usage and creation of spaces to space management.

Matrix Spaces

Understanding Matrix Spaces

Matrix Spaces are a way to group multiple rooms together. Rooms can be in multiple spaces at once, and spaces themselves can also be included within other spaces.

Much like rooms, Spaces can be made available publicly or kept private. From the Element Matrix clients, Element Web or Element Mobile / Desktop Apps, spaces can be found within the vertical navigation menu along the left. When viewing a space, all rooms and chats are filtered to show you only those within the selected space.

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 Space.

Matrix Spaces

Getting Started: Creating a Space

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.

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:

Bridges

Documentation covering how to use the various Matrix / Element bridges

Bridges

Setting up Hookshot without E2EE support in encrypted rooms

If your Hookshot instance does not have E2EE support enabled but you still want to add it to an encrypted room, you can do this with a couple of caveats:

To set this up:

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.

Bridges

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

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 Bridge

In 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:

start_new_chat

inviting_bot_to_dm

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.

bot_joined_dm

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

Authentication

Info

Management

These commands only work for bridge administrators.

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_command

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.

invite_by_bot_to_room

Once you've joined the room, you can then communicate with others within the channel.

messaging_in_matrix

messaging_in_irc

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.

list_command

Staying active

You can use the !active command to mark yourself as active, which will exclude you from any idleness kicks.

active_command

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_command

changing_nickname

irc_nickname_change

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_command

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.

irc_user_dm_invite

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, hoover over its name, then click the 3-dot menu then Leave.

room_3_dot_menu

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 under Historical.

quit_command

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.

You can also remove your stored password using, you will then need to use !reconnect to rejoin without the credential:

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.

reconnect_and_bridgeversion_commands

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.

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

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.

room_setting_menu

advanced_settings

Bridges

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.

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.

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.

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.

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.

Bridges

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.

Bridges

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:

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.

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.

SCR-20231103-ktgi.png

You will be taken into a new room with the WhatsApp bridge bot. The bot automatically joins the room.

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.

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.

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.

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.)

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.

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.

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.

SCR-20231107-kfqi.png

Bridges

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:

Setting up

Sign into Element Web using your Element username and password.

(If asked to verify your login, see docs on verifying 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.

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.

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.

Element Android/iOS Client 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.

                                   +--------------------+  +-------------------+
                  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:

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:

{
  "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.

Element Android/iOS Client Settings

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.

ntfy_environment_diagram

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.

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/ntfywill 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 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:

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.

Advanced Administration

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 page from the Element Web/Desktop 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:

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:

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.

Advanced Administration

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 page from the Element Web/Desktop 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:

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:

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.

Advanced Administration

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.

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 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, for example on Windows you'd use:

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:

python -m pip install requests

You will then be able to run scripts you create by using:

python .\myPythonProject\scriptName.py

Writing a python script

At it's most basic, you will need to setup the below template within your script:

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:

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.

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 to get all users, Query User Account to get each users' external_ids and finally Create or Modify Account to remove that specific external_id.

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