Quick Start Guide

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

• Onboarding
• The Left Panel
• The Middle Panel
• The Right Panel
• Frequently Asked Questions

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.

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.

   

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.

   

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.

   

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

   

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.

   

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.

   

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

   

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

   

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.

   

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

Here you can update settings such as your display name, profile picture, language and password. You can also manage notifications, security and privacy, and general settings about your account.

Avatars are selected on the General tab. This is what will show as your display picture to other users. When you hover over the circle, the word upload will show. Click this and you will be taken to your system s files where you can select a file you want to upload.

Display Names are added or updated in the General tab, type your desired name into the box and click save.

Contact Details are added or removed on the General tab. Email addresses and phone numbers are optional, to reset your account or have forgotten your password.

Language preference can be selected using the drop down menu.

B. Spaces

Organize groups of people and rooms together by using Spaces. A selected space will only show the list of rooms and people that are part of it.

• On Web / Desktop, Set up a new space by clicking "+ Create a space"
• On iOS / Android, Tap the space icon and select "create"

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.

C. Search Bar

Find people and rooms who are already part of your lists.

D. Rooms

This is where group discussions take place. Naming conventions help conversations be focused on a specific topic, and aid discoverability.

When searching for a room, make sure to select the right server for it to be discoverable. You can only join a private room by receiving and accepting an invite.

Find a public room

• On Web / Desktop, Find a room by using the "Compass" icon to explore already created public rooms and press "join".
• On iOS / Android, Tap the compose icon and select “Explore rooms”. Press "join" to participate.

Create a room

• On Web / Desktop, Create a new room by clicking the "+" next to Rooms in the left panel.
• On iOS / Android, Tap the compose icon and select Add room.

Leave a room

• On Web / Desktop, Leave a room by clicking the three dots and choose the "leave room" option.
• On iOS / Android, Leave a room by clicking the "room name" at the top of the room and choose the "leave room" option.

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.

F. People

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

• On Web / Desktop, Start a new chat by using the + button next to "People" in the left panel and type in their username or Matrix ID.
• On iOS / Android, Tap the compose button and select “Start chat”.

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.

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

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.

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

And see Threads in a room on the Thread panel.

Tap on a message to bring up options then "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.

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.

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.

Additionally, security and privacy settings give you the freedom around encryption, room access and chat history.

Manage widgets, bridges and bots are optional advanced extras to improve room productivity.

B. Show notification messages

Displays room notifications to keep on top of important conversations.

C. Search conversations

Brings up the search functionality within the current (or other) rooms.

Frequently Asked Questions

Account management

How do I reset my password?

• Please note that we cannot reset passwords or reactivate matrix.org accounts. If you have an email address attached to your account, you can reset your password here.

Do I need an email address to register?

• Using an email address when creating a Matrix account is optional; it will make it easier for others to discover you and can help you to reset your password if needed.
  
  It's ultimately up to the administrator of the server to decide whether or not you need to use an email address when creating a Matrix account.
  
  For accounts on the matrix.org homeserver, supplying an email address during registration is optional, but matrix.org reserves the right to occasionally require it for abuse mitigation as referred to in the privacy policy.

What is the username used for?

• We will use your username to create an ID (Matrix ID) allowing to disambiguate you from others with the same display name. It will allow us to keep your email confidential. 🙂

Can I register with a phone number?

• Not anymore. Sorry!

Chat

How can I mention someone?

• Just type their name and they will be notified accordingly. You can autocomplete by pressing the tab button, you don’t need any prefix for the mention to work!

With what type of mentions will I get notified?

• By default you’ll be notified if your display name and your user name are mentioned. You can add other names, nicknames or keywords on which you want to be notified from your settings, in the Notifications section.

How do I send a file?

• Simple, just drag the file into Element and it will automatically upload. Alternatively you can click on the paperclip icon in the text input field and browse your filesystem.

Can I upload a file from a mobile device?

• Yes you can! On a mobile device simply press the arrow which is pointing upwards (on iOS) or the + symbol (on android) while in a chat and select your file.

How can I invite a contact to use Element?

• You can invite someone to a room by using the "Invite to this room" button in the right hand side "Room members list" using their Matrix ID (if they have one) or by email. Those without a Matrix ID will be able to preview the room if the room allows for that.

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

• Yes! Element shows who has read a message by displaying their avatar to the right of the message. Hovering over these avatars (or clicking on them on mobile) will give you the user’s info and reading time.

How can I search for a file or message?

• To search a room from Desktop, click on the magnifying glass located near the top of the screen. You can then type in a keyword or filename that you are searching for with the ability to select whether you want to search within the specific chat room or across all conversations. For encrypted rooms, search only works on Desktop (not Element web and mobile) and you need to have "Message search" enabled in the Element Security & Privacy settings.
  
  On Element iOS, tap the room name at the top, then "Search room."
  
  On Element Android, tap the three dots in the top right corner, then "Search."

Settings

How do I change my account settings?

• Click on the drop down menu under your name in the top left corner of the web or desktop app and select. From here you can change all of your account and general Element preferences.

How do I change my notification settings?

• Element allows you to customize your notifications at two levels: across the app and per room. You can configure how you will be notified for given events by default in the Notifications section of your Settings (accessible from the drop down menu under your name in the top left corner of the web/desktop app).
  
  You can configure keywords, default notification settings for group, one-to-one chat rooms, invites and calls. The notifications can be:
  
  

  • Turned off: you won’t be notified when the selected event happens.
  • Turned on: you will get a message popping up when the selected event happens, but no sound.
  • “Noisy”: you will get a visual highlight (red badge and/or text highlight), a sound and/or vibration (depending on the device) when the selected event happens.
    
    

  Then 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. This is very handy when you wish to temporarily mute a room, or make sure you’re not missing anything from a given discussion. You can select the following options:
  
  

  • Mute: you won’t be notified, even if your name or a keyword is mentioned.
  • Mentions only: you will only be notified for the items that are meant to be ‘noisy’, i.e. your name and keywords.
  • All messages: you will get a (silent) notification for every message happening in the room; your ‘noisy’ events (e.g. your name being mentioned) will still be noisy (red badge and sound).
  • All messages (noisy): every message will make a noise on top of the visual notification. Your noisy events will still be differentiated by a red badge.

How do I set up email notifications?

• You can set Element up to email you when you have missed some activity (new messages, new invites…). You can do this in the Notification section of your Settings and turn on the toggle labelled as ‘Enable email notifications’.

How can I change my display name?

• You can change your display name in General section of your Settings (accessible from the drop down menu under your name in the top left corner of the web/desktop app).

How do I reset my password?

• The Element team won't be able to reset passwords or reactivate matrix.org accounts.
  
  If you have forgotten your password, please visit app.element.io and click on the link ‘Set a new password’. You will need to input the email address which is registered to your Element account and choose a new password. An email will then be sent to confirm your request to reset your password. Please follow the link in the email to complete the process and regain access to your account.
  
  If you haven't set an email address for your Element account, please contact your homeserver administrator who may choose to reset your password for you.

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

• It's ultimately up to the administrator of the server to decide whether or not you need to use an email address when creating a Matrix account, and optionally restrict this to certain email addresses or domains.
  
  If you can, we strongly recommend that you set an email address in order to be able to reclaim your account if you’ve lost your password. It is also useful for people to find you, and easier to remember than (yet another) ID. If you haven’t done so at registration, don’t worry; you can add as many email addresses as you like, at any point, in the General section of your Settings
  
  If you have forgotten your password and did not register an email address with your account, your homeserver administrator may choose to reset the password for you. If not, we're sorry to say that there is no other way to access your account. 🙁

Rooms

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

• You can change the settings for any one-to-one chat or group room by clicking on the cog icon next to the room name.

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

• You can restrict the access of a room to people who have been invited by selecting the “Private (invite only)" option in the "Security & Privacy" settings of the room. People knowing the link of the room won’t be able to access it if an invite hasn’t been explicitly sent to their email address or ID.
  
  By adding the room to a Space, you can also select "Space members" to only allow anyone that is a member of the Space to join.

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

• You can restrict the access of a room to people with whom you shared a link to the room by selecting the “anyone who knows the room link” option in the room settings. Selecting this option will not make the room publicly visible to the rest of the community.

Can I make a room publicly discoverable?

• You can get your room listed into your server’s directory by checking the button labeled "Publish this room to the public in example.com's room directory?". By checking this box, it will be discoverable to anyone searching for a room on the server. However, they will be able to join only if you haven’t restricted the access only to people with an invitation.

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

• If your room is listed in the directory, people will know it exists but they will only be able to join it if you allowed the access to it to anyone knowing the link.

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

• It depends on how you configured the history visibility for the room. By default every member of the room can read its history. But you can decide that new joiners will only see the history they are part of, I.E. Members will only be able to see the history of the room since they were invited (or joined, both options are available). ‍
  
  However it is important to note that these settings are not retroactive and only apply from the time they are selected: if you have a discussion with the history being visible to every member since the start, then change it to discuss an important matter so that people only see the history from the time they joined, new members will have access to all the history before you changed the option.

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

• Making the history visible to anyone means that people can see what is being said in a room before joining it. So typically, if you are browsing the room directory and see a room which might be interesting, you will have the opportunity to “peek” into it, having a view of what has been said without joining it. This gives users the opportunity to gauge a room before joining. It is a useful option for rooms publicly listed and hosting public discussions, or for people you share your room link with, so that they have an idea of what they’re going into before joining.

What is a room address?

• By default the room has an ugly identifier which is barely human readable. Setting an address for a room allows you to give it a simple reference, making it easier to share a link to it. The addresses are linked to the server you are registered on (e.g. Matrix.org if your ID is @username:matrix.org). A room can have different addresses on the same homeserver and addresses on different homeservers. They are just a user friendly entry point, but are required the moment you want to make the room accessible in other ways than by inviting users.

What is a favorite room?

• The favorite section allows you to pin and order important rooms which will be displayed at the top of your Element room list.

What is a low priority room?

• The low priority section allows you to declutter your room list by moving rooms you consider less important to the bottom.

What is the “historical” section?

• The “historical” section lists all the rooms you’ve left and allows you to access the history you have there. You won’t see the new activity in these rooms, only what happened before you left.

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

• In the roles and permissions section of the room’s settings, you’ll be able to configure the privilege levels required to perform various actions in the room, e.g. send a message, ban / kick members, redact messages, update the room’s settings, invite new members, etc..

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?

• Here is Element’s privacy policy. If you have additional questions, contact our DPO.

How do I report on content in Element?

• Report inappropriate content on Element by hovering on the message and clicking the more options button (three dots) and "Report content".

How do I submit an abuse report?

• To report a general abuse issue, please contact abuse@element.io ‍
  
  
• To report an abuse issue on the Matrix.org homeserver please contact abuse@element.io
  
  
• To report an issue outside of matrix.org homeserver, please contact the administrators of that homeserver.

How do I request a DMCA takedown?

• Please read our Copyright Policy for our approach to copyright. To send DMCA takedown notices, contact dmca@element.io

End-to-end encryption

What is encryption?

• Encryption means scrambling a message in such a way that only those knowing the secret key can unscramble it. We use encryption to keep your messages and files private.

What is end-to-end encryption?

• End-to-end encryption means your messages and files are encrypted before they leave your device, and stay encrypted until they reach the other participants' devices. End-to-end encrypted messages can only be read by the participants in the conversation.

Who can read my messages?

• Thanks to end-to-end encryption, your messages can only be read by the participants in the conversation and nobody else. This means your messages can't be read by anyone at Element, or by any other third party. It also means that if you lose your keys, you won't be able to read your messages.

Why can't I read a message?

• If you can't read a message it's because your device doesn't have the right key. If your device doesn't have the right key, there are three ways you might be able to get hold of the key: ‍
  
  
  • Restore all of your keys from key backup
  • Request the specific key from another device via key share
  • Upload keys from a manual backup (advanced)

What is Key Backup?

• When key backup is enabled, your device will maintain a secure copy of its keys on your Matrix homeserver. To ensure those keys can only ever be accessed by you, they are encrypted on your device, with a key that you either store yourself, or secure with a passphrase and upload to your Matrix homeserver. It is important to understand that to protect your privacy your keys will never touch our systems unencrypted.

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

• Yes. Your keys are encrypted before they are uploaded to your Matrix homeserver, so we never see them unencrypted.

How do I set up key backup?

• Go to User Settings -> Security & Privacy and click Start using Key Backup.

How do I restore from key backup?

• Go to User Settings -> Security & Privacy and click Restore from Backup.

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

• When Element sees a message it can't decrypt, it automatically asks your other devices if they have a copy of the necessary key. Keys will be shared automatically with trusted devices - if the device with the key hasn't trusted the device requesting the key, the device with the key will pop up a prompt asking you to confirm the key share manually.

What is a 'device'?

• For historical reasons, when we say 'device' we don't mean your phone or your laptop - you actually create a new 'device' each time you log in on Matrix (and destroy it again when you log out).

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

• Element uses trust to represent an additional layer of security within the app, over and above username and password authentication. ‍
  
  If somebody is sending messages as Alice, we know that they have access to Alice's account - either they've logged in with Alice's username and password, or they're using a logged in session, perhaps on Alice's phone. ‍
  
  Usually, that somebody is going to be Alice. Unfortunately, in the real world, passwords can be guessed or sniffed and phones can be stolen. Element's trust mechanism is designed to mitigate this. ‍
  
  Element uses cross-signed device verification to help ensure the identity of conversation participants and their devices, with minimal effort.
  
  In Element, you can see every device that has joined an encrypted conversation. If a new and unexpected device joins, you can use device verification to check that it's really Alice. And if you suspect that a trusted device has fallen into the wrong hands, you can revoke that trust and remove its access to the ongoing encrypted conversation.

Are all of my messages encrypted?

• No, messages are only encrypted in rooms with encryption enabled. You can enable encryption by going to Room Settings.

Can I search in encrypted rooms?

• Please note that search in encrypted rooms is only possible on Desktop if it's enabled in "Security & Privacy" settings on Element.

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

• If an encrypted room has a green symbol next to the room name, it means your device trusts every other device in the room. This is the gold standard. ‍
  
  If instead there is a red symbol next to the room name, it means one or more devices are untrusted. ‍
  
  Verifying every device is, alas, still time-consuming — we’re working hard on a solution to this.

Reporting bugs and requesting features

How do I submit a bug report?

• From a mobile you can ‘rageshake’ (shake your phone when the app is open).
  
  Alternatively for iOS: Go to ‘Settings’ (cog in the top left) and select ‘Report bug’ under the ‘Other’ section.
  
  Or from Android: Go to ‘Settings’ (three dots in the top right) and select ‘Report bug.’
  
  For desktop and web: Go to ‘Settings’ under your profile, click on ‘Feedback” and submit a report.

How do I request a new feature?

• Please submit an Element feature report as an issue on GitHub:

  • Element Web and Desktop: ‍
  • Element iOS: ‍
  • Element Android: https://github.com/vector-im/element-android/issues ‍
    
    

  Before opening a new issue, please look for already open similar issues.

Threads Beta

Why does my homeserver need to support threads?

• In order to reliably update the list of threads in a room and their contents, your homeserver needs to support threads via MSC3440. If your home server runs Synapse, this is available in version 1.55 and above. You can ask your homeserver administrator to upgrade your server to ensure that threads are supported.
  
  If your homeserver doesn't support threads, you will still be able to read and contribute to threads, but the feature might be unreliable - you might not see all threads in a room, and some messages might be missing, especially older messages. For that reason, we strongly recommend to upgrade your homeserver.

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

• The room list unread badge will behave exactly in the same way as it did before threads. The badge shows the number of messages between a user’s last read receipt and the last event in that room.
  
  Sometimes, when reading a room, you might observe the room list unread badge decrease by a greater number than the visible messages shown in the room timeline. That ghost count is due to new messages tucked away in threads and hidden from the main timeline - the room list badge will not show them anymore, but an unread dot will still be shown in the thread list until you’ve opened the thread.
  
  This limitation will be improved by future enhancements to homeservers which will help clients track thread read activity better.
  
  If you have selected a different notification option like “Mentions & Keywords” or “None”, you should expect Element to honour this setting in the same way it did before the introduction of threads.

How can I avoid missing messages posted to threads?

• If at least one thread in the room has unread messages, you should see a notification dot on the thread icon in the room header. Clicking it will take you to the thread list which is sorted by the last reply to a thread. You’ll notice a dot on the right side of the thread tile indicating that a thread contains events you haven’t read yet.

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

• This is not a supported feature for the beta release. For the moment, Element will always show a dot and not an unread count regardless of your room notification options.

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

• Yes, but we’re currently scoping out ways to have more granular settings for notifications in the context of threads.

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

• Clients can not always sync the read state between themselves reliably for the beta release. It is possible that a thread you’ve already read on mobile will still have a notification dot on Element Web, or vice-versa.

Where are the read receipts in my threads?

• They are currently not supported for the beta release.

Are push/email notifications supported?

• Yes, following links from push or email notifications will show the event in the right context in Element.