Element Cloud Documentation

Documentation for Element and EMS by the EMS team

Frequently Asked Questions

Element General

Can spaces be deleted?

Spaces are rooms and can be deleted in the same way using the delete room Synapse Admin API.

What are the permissions required to start a video call?

In a room with more than two members, voice and video calls are done using the Jitsi integration. Users need "Modify widgets" permissions to add the Jitsi widget to the room and initiate a call.

Once the call is initiated, anyone in the room can join.

What is the preferred resolution for room and space icons?

Room and space icons can be shown in a full-screen lightbox, so the resolution should be high. The homeserver will create a smaller thumbnail that is displayed when viewing rooms and spaces normally.

Matrix General

Can I sign in to multiple Matrix accounts in Element Desktop?

If you have multiple Matrix accounts - for example, an EMS account and a matrix.org account - you cannot log in to both simultaneously in the Element Desktop client today. However, you can launch multiple Element instances locally via its Profiles feature.

What is an Identity Server, and how does it work?

The best response to 'What is an Identity Server' is detailed in section 2. of the vector.im Identity Server privacy policy, available here: https://element.io/is-privacy-notice.

New Vector runs two identity servers, one at matrix.org and another at vector.im. These servers run in a closed federation - this means that if you add (or remove) your data from one, it is added to (or removed from) the other automatically, too.

The behavior and role of Identity Servers are changing. Historically, Identity Servers provided three sets of functionality:

  1. They let users publish their third-party identifiers (email/telephone number) to a directory to allow other Matrix users to discover them.
  2. Letting users send invites to a Matrix chat room to an email address instead of a Matrix ID.
  3. Letting homeservers send emails/SMS text messages to verify that they belong to a given Matrix user so that the user can log in to the homeserver using a third-party identifier instead of a Matrix ID.

Identity Servers continue to provide the functionality described in 1. However, the features described in 2. and 3. are now provided by the homeserver instead and will be deprecated and phased out of the Identity Server in the future.

For a period in 2019, while privacy functionality was being enhanced on vector.im and matrix.org, these Identity Servers were restricted to only provide services for users on New Vector homeservers. Once privacy improvements landed, this restriction was lifted.

Element Matrix Services

Account Management

Please discontinue my account

It is best if EMS customers delete their host or account themselves. Here's how:

Delete the host from the host management page at https://ems.element.io/user/hosting by clicking the Delete host button (and confirming deletion in the resulting dialog). This will delete the host and cancel all associated subscriptions.

Or delete the EMS account entirely. This is done from the user account page https://ems.element.io/user/account by clicking on the Delete account button and confirming. This will delete all hosts and subscriptions before removing the user's account.

Integrations

Bots? What's the reason for using them?

Bots allow you to get information and perform actions in line with your chat. There are a bunch that can be found at https://matrix.org/docs/projects/bots/.

Can I host my own Telegram bridge?

Unfortunately, you are not currently able to host your own bridges to work with your EMS-hosted homeserver. As of December 2020, we have added a Telegram bridge to EMS. See our blog post: EMS brings more interoperability to messaging.

If you have federation enabled for your homeserver, you can also bridge into publicly accessible rooms, such as https://t2bot.io/, or integrations available on public homeservers such as matrix.org.

Do DMs count towards the 20-channel limit for the paid Slack bridge?

Yes, but we're currently reviewing the bridging pricing models, and soon we'll likely be offering Slack (as well as all of our other bridges) on a usage basis rather than on a room/workspace capped basis.

When this launches, existing customers will be able to stay on their existing plan or choose to move to the new model.

How do I add a GitHub integration?

To create a GitHub integration in a room, click on the i icon at the top right, accept the privacy policy, click Add widgets, bridges & bots, click Add integrations and select GitHub from the Bots list. When prompted, log in to GitHub and select the repositories and functions you want.

Note that your server needs to have federation enabled for integrations to work.

How do I add RSS integration to my Matrix server?

To create RSS integration in a room, click on the i icon at the top right, accept the privacy policy, click Add widgets, bridges & bots, click Add integrations and select RSS Bot from the Bots list. Then, enter the RSS URL and click Subscribe.

Note that your server needs to have federation enabled for integrations to work.

How do I bridge to Libera Chat IRC rooms with more than 100 users?

Please talk to your account manager, or open a support ticket by emailing support@matrix.org. The bridge team will consider requests on a case-by-case basis.

What is the difference between the free and paid Slack bridge?

They're mostly the same. The big difference is that the free one doesn't bridge DMs / puppet your account. See also Do DMs count towards the 20 channel limit for the paid Slack bridge?

With Jitsi video conferencing, how is the data being transferred?

Jitsi conferencing data goes directly from the browser to the Jitsi server, and it does not use the Matrix protocol. If you add a Jitsi widget to a room, that widget will be stored in the room state as Matrix events, but the Jitsi communication itself is from the client to the Jitsi server used.

Miscellaneous

Are all my messages stored on my homeserver?

Messages are stored on your server. However, if you are communicating with users registered on other servers, then relevant messages/events will also exist on their server.

Is there a maximum file size per upload?

The file upload limit for EMS hosts is currently set at 100MB.

How do I send "System Alerts" or post from the @server user?

The web console has a form to do this. "System status messages" - You can use this form to send messages to all users of your server. For example, this could be used to send "messages of the day", or important policy updates, etc.

What are the benefits of paying for an EMS homeserver?

EMS aims to take the hassle out of hosting and managing your own Matrix stack. There is a significant technical overhead (in terms of technical knowledge required) as well as ongoing time and resources to ensure that your server continues running and is kept up to date with all of the latest security updates etc. With EMS, you don't have to worry about that, as it is all taken care of for you at the touch of a button.

We also provide a (growing) suite of proprietary host administration tools in the form of the EMS Synapse admin dashboard to help give you better insight and control of your server.

What are the limitations in terms of storage?

We’ve shied away from hard limits for storage and instead adopted a fair use policy. If you use the server for business conversations and share a few images as part of your discussions, you will never have problems. However, if you share thousands of images daily per user, you will hit a limit.

Pricing & Payment

Do you offer other payment options like PayPal, Crypto, or IBAN/SEPA?

Currently, we only accept Credit or Debit/bank account cards as payment. "Debit cards" should work with any regular bank account.

How do I update my payment info?

To update your payment info, go to https://ems.element.io/user/billing. From here, you can update your payment details.

If I join a room with a lot of external users from my homeserver, will I be charged for those?

No, you are only ever charged for users that are registered on your server and who have been active for more than two days in a month. These users make up your Monthly Active User (MAU) total. Users that are registered on other servers (that you communicate with over federation), guest users, and users who are only briefly active on your server are not counted.

Server Configuration & Management

Are custom appservices supported?

Uploading custom (YAML) registration files for appservices is not currently supported for EMS hosts.

We are actively working on improving bridging support for EMS hosts and hope that this will be something that you see substantial improvement in over the coming months.

Are you able to use a custom domain like "matrix.example.com"?

Yes, absolutely! However, you need to set this at host creation time as the homeserver name is "baked in" to all of the events that the homeserver creates.

You can set both the homeserver name, e.g., example.com (so your Matrix user IDs would be of the form @foo:example.com), and your (Element) client address, which might be something like webchat.example.com. However, to prove that you own the domain in question, you will need to place some JSON / text into two well-known files on the webserver for your domain. In the setup wizard, you will be guided through this process when setting up the custom domain for your server.

Can I add all my users to a Space by default?

Yes, this is available for Gold and Enterprise customers. Please talk to your Account Manager or open a support ticket.

Can I change the default room notification level for my users?

This is currently not possible, unfortunately.

Can I customize the Element web login page?

Yes, you can modify the look and feel of your client to suit you.

Please see our blog article on custom branding for your Element instance here https://element.io/blog/custom-branding/ and Client Look & Feel for more details.

You will be able to enter the customization preferences from the managed host page of your EMS account - https://ems.element.io/user/hosting.

Can I use a subdomain instead of the root domain with my EMS server?

Yes. However, this is not recommended. For the same reason your email address probably is not someone@email.example.com, you probably don't want your Matrix IDs to be @someone:matrix.example.com.

Please see https://matrix-org.github.io/synapse/latest/setup/installation.html#choosing-your-server-name for additional details on your server name.

Can I use EMS-hosted well-knowns with the root of my domain?

Yes, you can, but there are some limitations:

CNAME and .well-known?

The client file needs to contain:

{
    "m.homeserver": {
        "base_url": "https://yourEMShost.ems.host"
    },
    "m.identity_server": {
        "base_url": "https://vector.im"
    }
}

The server file needs to contain:

{
    "m.server": "yourEMShost.ems.host:443"
}
CNAME doesn't work with Cloudflare?

You can use the CNAME with CloudFlare, but you have to change the Proxy status to DNS only.

Could you expand on "over federation"?

If you have federation turned on in your server configuration, you are able to communicate with users registered on other servers (e.g., matrix.org).

You are only ever charged for users that are registered on your server and who have been active for more than two days in a month. These users make up your Monthly Active User (MAU) total. Users that are registered on other servers (that you communicate with over federation), guest users, and users who are only briefly active on your server are not counted.

DNS is not resolving

This problem is most likely caused by a delay in DNS replication downstream of your DNS servers.

How can I manage my #general room?

You can gain admin permissions in this room by calling this Synapse Admin API or by contacting EMS Support at https://ems.element.io/support.

Gold and Enterprise customers can also request changes to the list of default rooms their users are automatically added to.

How do I change the name/brand of the Element Web client?

You can rename the Element client from Element to for example Company Chat with the Client name field on https://ems.element.io/user/hosting#/hosts. See Client Look & Feel for additional details.

How do I change the server's custom domain?

You can only set a custom domain name for a server at setup time. This is because the server's domain name is "baked-in" to all of the events generated by the server.

So, you would need to deprovision an existing server and create a new one, selecting your custom DNS preferences from the advanced settings section of host setup configuration if you wish to change the current host DNS.

How do I delete users when administering the server?

You can deactivate users from the admin dashboard for your host at https://ems.element.io/user/hosting.

Select the Server Admin tab and then the User Info sub-tab. From here, you can search for the relevant user and hit the Deactivate account button.

How do I enable the public room directory?

The public room directory is enabled on your EMS server if both Federation and Guest users are enabled.

How do I migrate from EMS to self-hosted if I choose to do so in the future?

Currently, the process of migrating away is manual. However, we hope to have an automated, self-serve system in the not too distant future. For the time being, if you wish to migrate away, please email ems-support@element.io (while your EMS server is still up and running) and ask for a snapshot of your Synapse database. We will then generate a snapshot for you and create a link to download the data. You can then use this to restore the database / Synapse instance on your own infrastructure.

Note that migrating from EMS to self-hosted is only possible if you use your own domain (Custom DNS) with your EMS server.

I deleted my host, now my server name is taken, and I cannot rebuild

This is part of a security measure. We generally prevent hosts from returning to the pool after they were initially claimed to prevent people from attempting to imitate old servers/users. Contact support from https://ems.element.io/support while signed in to get the hostname released.

Online users are displayed as offline?

Unfortunately, we are not able to offer user presence as a feature at the moment. This is due to potential performance impact and excess resource usage on hosts when this feature is enabled. The Synapse team is aware of this, and it is on their roadmap to address. However, we do not currently have a timeline for when it will be available again.

What does "Include bridged accounts" on the user management page mean?

When you bridge to external services, external users get an "appservice user" on your EMS server. If you have any bridges and check this checkbox, users from across your bridges will also be shown.

Element Matrix Services

Element Matrix Services

Add Additional Users

  1. Click Your Account and Manage Servers or click this link https://ems.element.io/user/hosting.
  2. Click the Hosts tab.
  3. Change Total Monthly Active User Seats to the number of users you want and click Save at the bottom.
    • Note that you cannot decrease your user count later.

For server on our legacy plans, Say you want a total of 10 Monthly Active Users on your EMS Nickel server. Add 5 in the Additional users field. Then click Save.
temp

Element Matrix Services

Add Users

  1. Click Your Account and Manage Servers or click this link: https://ems.element.io/user/hosting

  2. Click Server Admin

  3. Select your host

  4. Click Add user Enter the username and click Add
    temp

  5. Select Make new user server admin if you want this user to be able to use the Synapse Admin API to perform administrative tasks on your server. Be careful with this as this option has a lot of power on your server.

  6. The username and password for the new user is displayed. You will only be able to see this information once so send the password to the user in a secure manner and then delete it
    temp

Element Matrix Services

Client Look & Feel

This feature allows you to customize the home and welcome page on your EMS provided Element Web client.

The guide assumes you already have a website on any domain with https enabled.

  1. Create two files on your web server, for example https://twily.org/ems_home.html and https://twily.org/ems_welcome.html
    temp

  2. Edit ems_home.html. This can be as simple as a couple of lines of HTML, for example:

    <h1>Demo Company LTD</h1>
    <h2>Rooms to join</h2>
    <ul>
        <li><a href='/#/room/#welcome:ems-demo-staging.ems.host'>Welcome to Demo web chat (#welcome)</a></li>
        <li><a href='/#/room/#support:ems-demo-staging.ems.host'>Support (#support)</a></li>
        <li><a href='/#/room/#offtopic:ems-demo-staging.ems.host'>Off topic conversation (#offtopic)</a></li>
    </ul>
    

    Or you can add a more complex html and styling.

  3. Looks like this in your web browser:
    temp

  4. Edit ems_welcome.html. This is a bit more complex, but can be almost anything you want as long as it has links to Login (/#/login) and Create account (/#/register). The default design is based on this template. You can get creative with the CSS and the !important tag.

  5. Add links to your files on the EMS control panel and click Save.
    temp

  6. Check that it looks correct and that everything works. You do not need to click save or rebuild in the EMS control panel if you make changes to the files. As long as the URL does not change, refreshing the Element Web Client page is enough.

  7. With some hacking you can make it look as you want. (and the following example is why I am a developer, not a designer...)
    temp
    temp
    temp

Element Matrix Services

EMS Server With Custom Domain

For this guide, I will be using the domain twily.org. I will set up EMS so that the Matrix usernames becomes @someone:twily.org, and the Element client will be at https://chat.twily.org/

From the guide at Get Your Own EMS Server, I will be replacing the EMS hostname ems-demo-staging.ems.host with ems-custom-demo-staging.ems.host

The guide assumes you already have a website on the root of your domain with https enabled.
temp

  1. Follow step 1 - 10 from Get Your Own EMS Server

  2. On step 10 from Get Your Own EMS Server, turn ON Custom DNS
    temp

  3. In the Custom Homeserver domain field, enter twily.org
    temp

  4. Create two files on your website according to the instructions given.
    The path cannot be changed, but up to 30 redirects are supported.
    While not required, you should also add the header Content-Type application/json to both files.

    1. https://twily.org/.well-known/matrix/server
      temp

      {
          "m.server": "ems-custom-demo-staging.ems.host:443"
      }
      
    2. https://twily.org/.well-known/matrix/client
      temp
      You need to enable the CORS header Access-Control-Allow-Origin: * on the web server for this file. See https://enable-cors.org/ for instructions on how to do this.

      {
          "m.homeserver": {
              "base_url": "https://ems-custom-demo-staging.ems.host"
          },
          "m.identity_server": {
              "base_url": "https://vector.im"
          }
      }
      
  5. Click Check again to verify that your .well-known files are configured correctly
    temp

  6. You can also verify your .well-known files from the command line. Note the lines access-control-allow-origin: * and content-type: application/json

    1. On Mac or Linux, using your terminal

      $ curl -i https://twily.org/.well-known/matrix/client
      HTTP/2 200 
      date: Fri, 31 Jul 2020 09:11:21 GMT
      content-type: application/json
      content-length: 129
      set-cookie: __cfduid=x...; expires=Sun, 30-Aug-20 09:11:21 GMT; path=/; domain=.twily.org; HttpOnly; SameSite=Lax
      access-control-allow-origin: *
      cf-cache-status: DYNAMIC
      cf-request-id: 0...
      expect-ct: max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
      server: cloudflare
      cf-ray: 5...
      
      {
          "m.homeserver": {
              "base_url": "https://ems-custom-demo-staging.ems.host"
          },
          "m.identity_server": {
              "base_url": "https://vector.im"
          }
      }
      
      $ curl -i https://twily.org/.well-known/matrix/server
      HTTP/2 200 
      date: Fri, 31 Jul 2020 09:11:25 GMT
      content-type: application/json
      content-length: 52
      set-cookie: __cfduid=x...; expires=Sun, 30-Aug-20 09:11:25 GMT; path=/; domain=.twily.org; HttpOnly; SameSite=Lax
      access-control-allow-origin: *
      cf-cache-status: DYNAMIC
      cf-request-id: 0...
      expect-ct: max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
      server: cloudflare
      cf-ray: 5...
      
      {
          "m.server": "ems-custom-demo-staging.ems.host:443"
      }  
      
    2. On Windows, using PowerShell

      PS C:\Users\twilight> Invoke-WebRequest -Uri https://twily.org/.well-known/matrix/client
      
      
      StatusCode        : 200
      StatusDescription : OK
      Content           : {
                              "m.homeserver": {
                                  "base_url": "https://ems-custom-demo-staging.ems.host"
                              },
                              "m.identity_server": {
                                  "base_url": "https://vector.im"
                              }
                          }
      RawContent        : HTTP/1.1 200 OK
                          Connection: keep-alive
                          Access-Control-Allow-Origin: *
                          CF-Cache-Status: DYNAMIC
                          cf-request-id: 0...
                          Expect-CT: max-age=604800, report-uri="https://repor...
      Forms             : {}
      Headers           : {[Connection, keep-alive], [Access-Control-Allow-Origin, *], [CF-Cache-Status, DYNAMIC], [cf-request-id, 0...]...}
      Images            : {}
      InputFields       : {}
      Links             : {}
      ParsedHtml        : System.__ComObject
      RawContentLength  : 129
      
      
      PS C:\Users\twilight> Invoke-WebRequest -Uri https://twily.org/.well-known/matrix/server
      
      
      StatusCode        : 200
      StatusDescription : OK
      Content           : {
                              "m.server": "ems-custom-demo-staging.ems.host:443"
                          }
      RawContent        : HTTP/1.1 200 OK
                          Connection: keep-alive
                          Access-Control-Allow-Origin: *
                          CF-Cache-Status: DYNAMIC
                          cf-request-id: 0...
                          Expect-CT: max-age=604800, report-uri="https://repor...
      Forms             : {}
      Headers           : {[Connection, keep-alive], [Access-Control-Allow-Origin, *], [CF-Cache-Status, DYNAMIC], [cf-request-id, 0...]...}
      Images            : {}
      InputFields       : {}
      Links             : {}
      ParsedHtml        : System.__ComObject
      RawContentLength  : 52
      
  7. You can continue without the .well-known files in place, but your server will have limited functionality until this is fixed

  8. In the Custom Client domain field, enter chat.twily.org. This can be any domain, except the same as Custom Homeserver domain
    temp

  9. Create a CNAME DNS record with your DNS provider according to the instructions given
    temp
    chat.twily.org. CNAME ems-custom-demo-staging.element.io.

  10. This shows how this is done with CloudFlare DNS. Depending on your DNS provider this might be different. Consult the documentation for your provider. Note that Proxy must be turned off with CloudFlare.
    temp

  11. Back on EMS, click Check again. Note that sometimes it might take a while for your new DNS record to propagate. You can still continue, but functionality will be limited. Check back with the Hosts tab on https://ems.element.io/user/hosting and click Rebuild Host once the DNS record is in place.
    temp

  12. You can also verify your CNAME DNS record using the command line

    1. On Mac or Linux, using your terminal

      $ dig chat.twily.org CNAME
      
      ; <<>> DiG 9.10.6 <<>> chat.twily.org CNAME
      ;; global options: +cmd
      ;; Got answer:
      ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 57888
      ;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
      
      ;; OPT PSEUDOSECTION:
      ; EDNS: version: 0, flags:; udp: 512
      ;; QUESTION SECTION:
      ;chat.twily.org.   IN CNAME
      
      ;; ANSWER SECTION:
      chat.twily.org.  299 IN CNAME ems-custom-demo-staging.element.io.
      
      ;; Query time: 32 msec
      ;; SERVER: 8.8.4.4#53(8.8.4.4)
      ;; WHEN: Fri Jul 31 10:21:56 BST 2020
      ;; MSG SIZE  rcvd: 91
      
    2. On Windows, using PowerShell

      PS C:\Users\twilight> Resolve-DnsName -Name chat.twily.org -Type CNAME
      
      Name                           Type   TTL   Section    NameHost
      ----                           ----   ---   -------    --------
      chat.twily.org                 CNAME  299   Answer     ems-custom-demo-staging.element.io
      
  13. Continue from step 11 on Get Your Own EMS Server

Element Matrix Services

Get Your Own EMS Server

  1. Go to https://ems.element.io/

  2. Click Sign up or Sign in
    temp

  3. Enter your email address
    temp

  4. Click the confirmation link in the email
    temp

  5. Enter your name or company name and a password on https://ems.element.io/user/account. Then click Billing address and payment method
    temp

  6. Enter your billing address and credit card information on https://ems.element.io/user/billing
    temp

  7. Click Your Account, then Manage Servers to get started setting up your EMS server

  8. Click the Setup tab, and choose your Host Size
    temp

  9. Select your hostname and click Check. Keep in mind that this cannot be changed later
    temp

  10. Configure your host settings, then click Next. If you want to use Custom DNS (ie. have your usernames be @someone:yourdomain.com instead of @someone:yourhost.ems.host and have your Element client on your own domain), see EMS Server With Custom Domain
    temp

  11. Select Monthly or Annual billing and confirm your payment options. Then click Purchase
    temp

  12. Sit tight for a few minutes while your server is being built
    temp

  13. When it's done, click Manage hosts to configure additional settings and add users
    temp

Element Matrix Services

Import Database and Media Dump

This article is structured for an export from EMS, but may also be applicable in other circumstances.

For support on Synapse or matrix-media-repo, ask in the Matrix rooms #synapse:matrix.org and #mediarepo:t2bot.io

Prerequisites

You need these items to complete the import. If you are migrating from EMS, EMS support will provide all five to you

Import process

  1. Following official documentation, install and configure

    1. PostgreSQL
    2. Synapse
    3. matrix-media-repo
  2. When generating your Synapse configuration file, you MUST use the same domain as your EMS server.

  3. Do not start Synapse yet.

  4. In the Synapse config file (usually homeserver.yaml), set:

    1. pepper to the value received. If you do not to this you have to reset all passwords.
    2. Signing key. This is stored in a file. See this config file option for path. Alternatively, add the old key to old_signing_keys.
  5. Download the database and media exports provided.

  6. Decrypt and extract the exports

    gpg --no-symkey-cache --output postgres-export.sql.gz --decrypt postgres-export.sql.gz.gpg
    gpg --no-symkey-cache --output export-part-1.tgz --decrypt export-part-1.tgz.gpg
    gzip --decompress postgres-export.sql.gz
    tar zxvf export-part-1.tgz
    
  7. Import the database dump

    1. If your Synapse database is not empty, empty it
      WARNING - THIS WILL IMMEDIATELY AND IRRECOVERABLY DELETE DATA. WE TAKE NO RESPONSIBILITY IF YOU DELETE THE WRONG DATABASE OR THE WRONG DATA

      Connect to the database with psql, then run the following queries:

      DO $$ DECLARE
      r RECORD;
      BEGIN
          FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = current_schema()) LOOP
              EXECUTE 'DROP TABLE ' || quote_ident(r.tablename) || ' CASCADE';
          END LOOP;
      END $$;
      
      DROP sequence cache_invalidation_stream_seq;
      DROP sequence state_group_id_seq;
      DROP sequence user_id_seq;
      
    2. Disconnect from the database, then import the database dump

      psql --username=USERNAME --host=HOSTNAME DATABASE_NAME < postgres-export.sql
      
    3. Verify that sequence was set correctly. Connect to the database and run the query

      SELECT * FROM state_group_id_seq;
      

      last_value should be greater than 1

  8. Import media according to documentation here.

  9. Start Synapse.

  10. Optionally, install Element Web or use another Matrix client.

Element Matrix Services

Migrate From Self-Hosted to EMS

Notes

Before starting with this guide, please contact EMS support from https://ems.element.io/support or by emailing ems-support@element.io

Preparation

This section outlines what you should do ahead of the migration in order to ensure the migration goes as quickly as possible and without issues.

SSH to your matrix server

You might want to run everything in a tmux or a screen session to avoid disruption in case of a lost SSH connection.

Generate password for gpg encryption

pwgen -s 64 1

Alternatively, you can use our GPG key. Note, this expires on 2023-04-28, if this is soon, please talk to your EMS contact.
ems-support-public.pgp

GPG

If gpg is being uncooperative, use the command gpgconf --kill gpg-agent.

Create a folder to store everything

mkdir -p /tmp/synapse_export
cd /tmp/synapse_export

The guide from here on assumes your current working directory is /tmp/synapse_export.

Set restrictive permissions on the folder

If you are working as root: (otherwise set restrictive permissions as needed):

chmod 000 /tmp/synapse_export

Copy Synapse config

Copy the following files and send to EMS Support:

Stop Synapse

DO NOT START IT AGAIN AFTER THIS
Doing so can cause issues with federation and inconsistent data for your users.

While you wait for the database to export or files to transfer, you should edit or create the well-known files and DNS records to point to your EMS host. This can take a while to update so should be done as soon as possible in order to ensure your server will function properly when the migration is complete.

Database export

PostgreSQL

Dump, compress and encrypt

Replace:

pg_dump -O -h <dbhost> -U <dbusername> -d <dbname> | gzip > customer_db_export.sql.gz
gpg --symmetric --no-symkey-cache customer_db_export.sql.gz
rm customer_db_export.sql.gz

If required, split into smaller files

Please only do this if you have a slow connection and are worried about transferring a single large file.

split -b 100m customer_db_export.sql.gz.gpg customer_db_export.sql.gz.gpg.part-
rm customer_db_export.sql.gz.gpg

SQLIte

Compress and encrypt

tar -zcvf homeserver.db.tar.gz /path/to/homeserver.db
gpg --symmetric --no-symkey-cache homeserver.db.tar.gz
rm homeserver.db.tar.gz

If required, split into smaller files

Please only do this if you have a slow connection and are worried about transferring a single large file.

split -b 100m homeserver.db.tar.gz homeserver.db.tar.gz.part-
rm homeserver.db.tar.gz

Media export

If you are using SQLIte as database

Skip ahead to and follow Backup media export.

Download the export tool

Download the latest version of export_synapse_for_import-linux-x64 (or export_synapse_for_import-win-x64.exe) from https://github.com/turt2live/matrix-media-repo/releases

wget https://github.com/turt2live/matrix-media-repo/releases/download/vx.x.x/export_synapse_for_import-linux-x64
chmod +x export_synapse_for_import-linux-x64

Run the export

Replace:

./export_synapse_for_import-linux-x64 -h
./export_synapse_for_import-linux-x64 -dbHost <dbhost> -dbPort 5432 -dbName <dbname> -dbUsername <dbusername> -mediaDirectory /path/to/synapse/media_store -serverName <yourdomain.tld> -destination ./customer_media_export
mv logs customer_media_export
mv media-repo.yaml customer_media_export
rm export_synapse_for_import-linux-x64

Compress and encrypt

tar -zcvf customer_media_export.tar.gz customer_media_export
gpg --symmetric --no-symkey-cache customer_media_export.tar.gz
rm customer_media_export.tar.gz
rm -r customer_media_export

If required, split into smaller files

Please only do this if you have a slow connection and are worried about transferring a single large file.

split -b 100m customer_media_export.tar.gz.gpg customer_media_export.tar.gz.gpg.part-
rm customer_media_export.tar.gz.gpg

Backup media export

Compress and encrypt

Replace * /path/to/synapse/media_store (the path to where synapse stores your media)

tar -zcvf customer_backup_media_export.tar.gz /path/to/synapse/media_store
gpg --symmetric --no-symkey-cache customer_backup_media_export.tar.gz
rm customer_backup_media_export.tar.gz

If required, split into smaller files

Please only do this if you have a slow connection and are worried about transferring a single large file.

split -b 100m customer_backup_media_export.tar.gz.gpg customer_backup_media_export.tar.gz.gpg.part-
rm customer_backup_media_export.tar.gz.gpg

Transfer

Download the files, then upload to the Google Drive folder shared by EMS or a location as agreed with your EMS contact.

On your local computer:

scp -r -P 1234 -i ~/.ssh/matrix-server youruser@1.2.3.4:/tmp/synapse_export /some/local/folder

Cleanup

We strongly recommend that you leave the export and Synapse untouched until the import is finished and everything is verified working.

Note on users and Element

Element does have support for changing the delegated homeserver URL. All your users will have to sign out and sign in again to Element. You should ensure everyone has Key Backup configured and working.

Your users will not be able to decrypt messages send in their encrypted rooms while your server is offline for the migration.

Force logout of old sessions after migration

If you do not log out all sessions for your users before the migration, you can force this later. Below is a sample config file for nginx that tells all clients trying to connect to it to sign out.

Note that the headers are important, otherwise this will not work one one or more of the Element clients. Valid HTTPS is required.

This is not tested on any other Matrix clients, but it should work in theory if the client follows the Matrix Spec.

server {
    listen [::]:443 ssl http2;
    listen 443 ssl http2;

    server_name old.delegated.url.com;

    location / {
        if ($request_method = 'OPTIONS') {
            add_header 'Access-Control-Allow-Origin' '*';
            add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
            add_header 'Access-Control-Allow-Headers' 'authorization,DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
            add_header 'Access-Control-Max-Age' 1728000;
            add_header 'Content-Type' 'text/plain; charset=utf-8';
            add_header 'Content-Length' 0;
            return 204;
        }
        if ($request_method = 'POST') {
            add_header 'Access-Control-Allow-Origin' '*' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
            add_header 'Access-Control-Allow-Headers' 'authorization,DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range' always;
            add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;
        }
        if ($request_method = 'GET') {
            add_header 'Access-Control-Allow-Origin' '*' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
            add_header 'Access-Control-Allow-Headers' 'authorization,DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range' always;
            add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;
        }

        default_type application/json;
        return 401 '{"errcode":"M_UNKNOWN_TOKEN","error":"Server moved, please log in again."}';
    }

    ssl_session_timeout 1d;
    ssl_session_cache shared:MozSSL:10m;  # about 40000 sessions
    ssl_session_tickets off;
    ssl_protocols TLSv1.3;
    ssl_prefer_server_ciphers on;
    add_header Strict-Transport-Security "max-age=63072000" always;
    ssl_stapling on;
    ssl_stapling_verify on;

    error_log /var/log/nginx/old.delegated.url.com.error.log;
    access_log /var/log/nginx/old.delegated.url.com.access.log;

    ssl_certificate /etc/letsencrypt/live/old.delegated.url.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/old.delegated.url.com/privkey.pem;
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;

    server_name old.delegated.url.com;

    if ($host = old.delegated.url.com) {
        return 301 https://$host$request_uri;
    }

    return 404;
}
Element Matrix Services

Reset User Password

Resetting an account password will log out all sessions. Before doing this, make sure that


  1. Click Your Account and Manage Servers or click this link https://ems.element.io/user/hosting.

  2. Click Server Admin, select your host, then Users

  3. Click the user you want to manage
    temp

  4. Click Reset password, enter a new password and click Go
    temp

Integrations

Integrations

Admin Bot

Matrix brings lots of possibilities for collaboration through federation of different homeservers. This calls for moderation tools which consider the decentral power levels of Matrix rooms.

Admin Bot is only available on homeservers with the Element Enterprise Cloud plan.

Admin Bot is a service account which works in addition to the EMS Server Admin UI and Synapse Admin API.

Most administrative tasks in a Matrix room require a local account with the power level "Administrator" (100) to be a room member.

The Admin Bot extension ensures this by inviting and promoting the account adminbot in every Matrix room created on your server. This way you can moderate content in these rooms, invite and promote room members and kick or ban unwanted members.

Use case examples

Good to know

Setup

  1. Go to the Integrations tab on the EMS homeserver page.
  2. If you have more than one homesever, select the homeserver to add Admin Bot to.
  3. In the section Extensions, click on Admin Bot. If this is not visible, check that the homeserver is using the Element Enterprise Cloud plan.
  4. Click on Set Up Integration and confirm the pricing in a modal.

The Admin Bot integration page ends with a &quot;Set Up Integration&quot; button.

Usage

Admin Bot improves your ability to use the Server Admin tab on the EMS homeserver page and Synapse Admin API by having a local admin in every room.

The Element Web client shows the service accounts adminbot and auditbot joining a recently created room.

Furthermore, you can use Element Web to log into the adminbot account:

  1. Go to the Integrations tab on the EMS homeserver page.
  2. If you have more than one homeserver, select the one you want to administrate.
  3. In the section Extensions, click on Admin Bot. If this is not visible, check that the homeserver is using the Element Enterprise Cloud plan.
  4. If this is the first time you log in using this browser, click Secure Backup Phrase (click to view) and copy the phrase to your clipboard.
    The Secure Backup Phrase is displayed in a read-only text input field.
  5. Click on Log in as Admin bot. You will need to enter the Secure Backup Phrase on first login with a new browser in order to access Secure Storage and encrypted messages.

Removal

Removing the integration will not cause the user adminbot to leave rooms. This is a separate step to make mistakes easier to recover from. If the integration was accidentally deactivated and Admin Bot left rooms as the last local Administrator in that room, such rooms can no longer be moderated by anyone and need to be abandoned. Those room also couldn't be rejoined by Admin Bot.

You can deactivate the adminbot account using the EMS Admin GUI or Synapse Admin API, if you want it to leave all rooms.

Integrations

Audit Bot

Audit Bot is for compliance with the law or your organization's guidelines. This service account allows you to read every conversation on your server, including encrypted conversations.

Audit Bot is only available on homeservers with the Element Enterprise Cloud plan.

Use case examples

Good to know

Setup

  1. Go to the Integrations tab on the EMS homeserver page.
  2. If you have more than one homesever, select the homeserver to add Audit Bot to.
  3. In the section Extensions, click on Audit Bot. If this is not visible, check that the homeserver is using the Element Enterprise Cloud plan.
  4. Click on Set Up Integration and confirm the pricing in a modal.

Optional export

Audit Bot can be configured to write all decrypted events in all rooms to an S3-compatible storage of your choice. This is a continous export which will start with the configuration of a bucket and stop if you clear the configuration. Messages from the past are not exported retrospectively.

Usage

You can use Element Web to log into the auditbot account:

  1. Go to the Integrations tab on the EMS homeserver page.
  2. If you have more than one homeserver, select the one you want to administrate.
  3. In the section Extensions, click on Audit Bot. If this is not visible, check that the homeserver is using the Element Enterprise Cloud plan.
  4. If this is the first time you log in using this browser, click Secure Backup Phrase (click to view) and copy the phrase to your clipboard.
    The Secure Backup Phrase is displayed in a read-only text input field.
  5. Click on Log in as Audit bot. You will need to enter the Secure Backup Phrase on first login with a new browser in order to access Secure Storage and encrypted messages.

Removal

Removing the integration will not cause the user auditbot to leave rooms. This is a separate step to make mistakes easier to recover from. If the integration was accidentally deactivated and Audit Bot left rooms as the last local Administrator in that room, such rooms can no longer be moderated by anyone and need to be abandoned. Those room also couldn't be rejoined by Audit Bot.

You can deactivate the auditbot account using the EMS Admin GUI or Synapse Admin API, if you want it to leave all rooms.

Integrations

Create a Conference Call in a Room

Setting up

  1. Create a room
    temp

  2. Click Room Info, then Add apps, bridges & bots
    temp

  3. Read and accept the Terms of Service for the Integration Manager
    temp

  4. Select Jitsi from the list of available widgets
    temp

  5. Save the URL if you wish, this is also easily available later. Then click Save
    temp

  6. Click the X to close the integration manager
    temp

  7. To join the room conference, expand the Jitsi section at the top. Then click Join Conference
    temp

  8. Allow camera and microphone access. Note this might be different depending on your browser and operating system
    temp

  9. You are now in the conference
    temp

Inviting external participants

  1. Click the info button in the bottom right corner
    temp

  2. Click Copy
    temp

  3. Send the link to the external participant. They can just copy and paste it to their browser to join
    temp

Screen sharing

  1. Click the screen sharing in the bottom left corner
    temp

  2. Give permissions when asked

    • In macOS
      you need to grant the Screen Recording Privacy permission, and
      screen sharing does not work with the Element Desktop app
  3. Select the application or screen you want to share, then click Allow. Note this might be different depending on your browser and operating system
    temp

  4. Everyone can now see your screen
    temp

Integrations

Discord Bridge

Setup

First, you need to register a Discord application for your bridge. Discord applications can be registered and managed in the Discord Developer Portal.

  1. Click on the New Application button in the upper right corner.
  2. Give it a name (visible when authorizing the bridge), read Discord's Terms and click Create.
  3. Note the Client ID. It's required for the bridge.
  4. Navigate to the Bot tab. The navigation can be found on the left.
  5. Click Add Bot. You may also need to click Yes, do it! to confirm your action.
  6. Note the Bot Token. It's required for the bridge.

Connect Discord server(s)

You need to authorize your Discord App to each Discord server you wish to bridge. Give the following URL to a Discord server admin, if you aren't the Discord server admin.

The authorization URL is https://discordapp.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&scope=bot&permissions=607250432. Replace YOUR_CLIENT_ID with your Client ID mentioned above.

Usage

Bridge a room

  1. In a web browser, navigate to the Discord room you wish to bridge. The URL includes the server ID (also called guild ID) and the channel ID. The URL format is https://discord.com/channels/GUILD_ID/CHANNEL_ID.
    Discord showing Channel ID in URL bar
  2. In a Matrix room you want to bridge, invite @discord:example.ems.host (replace the domain with the one of your homeserver).
  3. Post the message !discord bridge GUILD_ID CHANNEL_ID after replacing the two placeholders.
    Element showing the Discord bridge command
  4. A privileged Discord user will need to approve the bridge request by responding with !matrix approve
    Discord message showing the approve command
  5. Messages from Discord are now bridged to Matrix and vice versa.
    Element showing a message bridges from Discord

Unbridge

To unbridge a room post !discord unbridge in the Matrix room.

Integrations

Google SAML

Note, other SAML providers may also work with EMS. Contact EMS support to discuss your options.

Setup

To enable authentication with Google SAML, the following needs to be done:

Update metadata

When the certificate expires (by default after 5 years) a new metadata file is required. The file can be downloaded from Google:

Upload metadata to EMS

The previously downloaded metadata XML is required by EMS to establish a secure connection to your GSuite environment.

Integrations

LDAP Active Directory

This guide assumes you already have a forest/domain configured and that your environment is properly secured.

This is a basic configuration. You may want to set additional options or permissions in your forest/domain.

Setup

To enable authentication with LDAP and Active Directory, the following needs to be done:

Configure Your EMS Server

Bind URI: ldaps://ldap.example.com:636
Base: OU=matrix,DC=example,DC=com
Bind DN: CN=emsadmin,CN=Users,DC=example,DD=com
Bind Password: supersecret
UID: SamAccountName
Display Name: See below
Email: mail
Import-Module ActiveDirectory
Get-ADUser test_user -Properties *
Integrations

OpenID Connect

Your homeserver can be configured to authenticate its users with an OpenID Connect provider. Here we list the most popular providers and how to configure them.

Google

For detailed information, read Google's guide on OpenID.

  1. Create a new application on Google.
  2. Click Create credentials and OAuth client ID.
  3. Select the application type Web application.
  4. Choose a name for you and your users to recognize.
  5. Add an authorized redirect URI with your homeserver URL, like https://my-host.ems.host/_synapse/client/oidc/callback.
  6. Save and note the client ID and client secret. Those are needed when adding the OpenID Connect integration in our interface.

In the Element Matrix Services configuration form

Use the preset Google for a simplified form or use Custom with the following values:

If you want shorter usernames and are not worried about username collisions within your domain, please consider using SAML2 to authenticate with Google.

GitHub

For detailed information, read GitHub's guide on OpenID.

  1. Create a new application on GitHub.com.
  2. Choose a name for you and your users to recognize.
  3. Choose a homepage URL. You can pick any URL. If your company maintains a guide on how to use Matrix, this would be most helpful.
  4. The Authorization callback URL needs to be https://my-host.ems.host. Adapt the URL to match your homeserver's address.
  5. Save and note the client ID and client secret. Those are needed when adding the OpenID Connect integration in our interface.

In the Element Matrix Services configuration form

Use the preset GitHub for a simplified form or use Custom with the following values:

GitLab

For detailed information, read GitLab's guide on OpenID.

  1. Create a new application on GitLab.com.
  2. Choose a name for you and your users to recognize.
  3. Choose a homepage URL. You can pick any URL. If your company maintains a guide on how to use Matrix, this would be most helpful.
  4. The Redirect URL needs to be https://my-host.ems.host/_synapse/client/oidc/callback. Adapt the URL to match your homeserver's address.
  5. Check the scopes read_user, openid and profile.
  6. Save and note the client ID and client secret. Those are needed when adding the OpenID Connect integration in our interface.

To connect your own GitLab instance, simply adapt the URL path.

In the Element Matrix Services configuration form

Integrations

Public IRC Bridges

Matrix.org (and others) host a number of IRC bridges for public networks.

A list of these networks can be found on the offical documentation.

Please note that matrix.org does not operate all of the networks listed, and is not responsible for content sent over the bridges.

Integrations

Public Slack Bridge

Matrix.org provides a public free Slack bridge, which is free to use forever but comes with some limitations:

This guide explains how to use the free Slack bridge from the Matrix.org Integration Manager to integrate your Matrix room with a Slack room.

Note that EMS offers a paid Slack bridge with more features.

It requires your homeserver to be able to federate with Matrix.org.

An EMS server is not required.

Setup

  1. Create a new room in Matrix, with encryption off
    temp
    temp

  2. Click Room Info in the top right corner of the room
    temp

  3. Click Add widgets, bridges & bots
    temp

  4. Choose Slack from the list of available bridges and integrations
    temp

  5. Click Add Bridge
    NOTE if you have purchased your Slack bridge from EMS: Ensure it says Slack integration on <your ems domain> here.
    temp

  6. Click Add to Slack
    temp

  7. Enter your Slack workspace URL, and click Continue
    temp

  8. Enter your Slack email address and password, then click Sign in
    temp

  9. Click Allow
    temp

  10. Close the Slack tab and return to Element
    temp

  11. Click List channels
    temp

  12. Click the Slack channel you want to bridge to the Matrix room
    temp

  13. Slack is now added to the Matrix room
    temp

  14. Go to the channel you selected on Slack, click the + below the message box, enter invite, and select Add apps to this channel

  15. Add the Element Bridge

  16. The Matrix room and Slack channel are now bridged
    temp
    temp

Integrations

Signal Bridge

This guide explains how to use the Signal bridge from the EMS Integration Manager to integrate your Signal chats with your EMS server.

It requires your EMS server to have federation on.

The following instructions are done with the Element Desktop on the Element side and on Element iOS for the Signal side. Element Android should be almost identical to Element Web.

Purchase the Signal integration

  1. Open the EMS control panel at: https://ems.element.io/user/hosting
    Click the Integrations tab and if you have more than one server, select the server you wish to add the Signal integration to
    temp

  2. Click on Signal Bridge in the list of available Bridges temp

  3. Enter the maximum number of users in Maximum Signal users.
    Please note: this is the maximum number of Signal users who actually send messages over the bridge each month. You are only billed for the number of Signal users who are active. Once you exceed the maximum, then the bridge will be disabled until you increase the maximum.
    If you enter less than 5, you will get a warning
    temp
    If you enter 5 or greater in Maximum Signal users, you will not see a warning
    temp
    Once you have entered Maximum Signal users, click Purchase (remember you can always go back to this step and increase the maximum number of Signal users if you need more in the future).

  4. A dialogue will remind you of the price per user and ask if you wish to proceed. Click Purchase if you wish to proceed with the Signal Integration
    temp

  5. You will have to wait a few minutes while your host is reprovisioned with the Signal bridge. Once reprovisioning is finished, you are able to bridge Signal to your EMS server using your Element client.

Bridge Signal to your Element account

  1. Once the bridge is running, open your Element app. Click on the + next to People temp

  2. Create a Direct Message conversation by typing @signalbot:example.ems.host (replace the domain with the one of your homeserver). Then clickGo
    temp

  3. The bridge account will join your room and tell you how to use it temp

  4. Open Signal on your mobile device (iOS or Android) and tap on your avatar to go to Settings and then Linked Devices and then Link New Device to start the Signal QR code scanner. You will use this QR code scanner to scan a QR code displayed by your Element client in the next step
    temp

  5. From your Element client, send a link message to the bot to connect to your Signal account
    temp

  6. A QR code will be displayed. Quickly scan the QR code with Signal on your mobile device. You have about a minute before it times out. If it times out, just send the link message again to generate another QR code
    temp

  7. On your Element client, you will see Successfully logged in as <your_phone_number> e.g. Successfully logged in as +1 555-555-5555 and you will see invitations for each of your Signal chats in your Element client. Each Signal chat is a separate Matrix room. Join one or more chats and start chatting from either your Element app on desktop, iOS or Android or your Signal on mobile.

Sending a message to a Signal User

To send a message to a Signal user, you must first be connected to the bridge (see above).

  1. On your Element client, open the "Signal bridge bot" room.
  2. Say pm followed by the phone number for your contact.
  3. You will be invited to a DM with that user, and can send messages to them.

Why do Signal user names show up as phone numbers?

Some signal users may appear as a phone number rather than their real name. This can because of one of the following reasons:

  1. The user has not spoken to you on Signal yet, and so has not sent their profile information.
  2. The user has not added you as a contact on their phone.
  3. The Signal bridge has not yet synchronized the profile information of the user from Signal (this should happen fairly soon after your first interaction).

EMS does not support the bridge as a primary device and the register command is not supported

The EMS Signal Bridge is implemented as a secondary device bridge in order to prevent Signal from ratelimiting the bridge. This means that the register command is not supported and you still need Signal installed on your iOS or Android device.

Integrations

Slack Bridge

The EMS Slack bridge is a paid integration for EMS homeservers. In addition to the features provided by the matrix.org bridge, it:

Purchase the Slack integration

  1. Open the EMS control panel at: https://ems.element.io/user/hosting

  2. Click the Integrations tab and if you have more than one server, select the server you wish to add the Slack integration to
    temp

  3. Click on Slack Bridge in the list of available Bridges temp

  4. Enter the maximum number of users in Maximum Slack users.
    Please note: this is the maximum number of Slack users who actually send messages over the bridge each month. You are only billed for the number of Slack users who are active. Once you exceed the maximum, then the bridge will be disabled until you increase the maximum.

Once you have entered Maximum Slack users, click Purchase (remember you can always go back to this step and increase the maximum number of Slack users if you need more in the future).

  1. A dialogue will remind you of the price per user and ask if you wish to proceed. Click Purchase if you wish to proceed with the Slack Integration
    temp

  2. You will have to wait a few minutes while your host is reprovisioned. Once reprovisioning is finished, you are able to bridge Slack to your EMS server using your Element client.

Setup

The setup process for the EMS Slack bridge is the same as the public Slack bridge hosted by matrix.org, explained here

Initiate a DM with a Slack user from Matrix

Integrations

Teams Bridge

Introduction

This guide explains how to set up a Teams bridge with your Element host. You will need to be an administrator of your Teams group to set the bridge up. Connecting to a Teams workspace that you do not control is currently not supported.

Setup

The setup process requires fetching a few details from your Teams workspace.

Get link to team item on the Team context menu

Bot Username and Password

The bridge requires a Teams user to be registered as a bot to send messages on behalf of Matrix users. You just need to allocate one user from the Teams interface to do this.

  1. First, you must go to the Azure Active Directory page.
  2. Click users.
  3. Click New user.
  4. Ensure Create user is selected.
    • Enter a User name ex. matrixbridge.
    • Enter a Name ex. Matrix Bridge.
    • Enter an Initial password.
    • Create the user.
    • Optionally, set more profile details like an avatar.
  5. You will now need to log in as this new bot user to set a permanent password (Teams requires you to reset the password on login).
  6. After logging in you should be prompted to set a new password.
  7. Enter the bot username and password into the integration form.

Welcome room

Users can be automatically prompted to link their Teams account to their Element account when they join an Element workspace. Ticking the Send a welcome message to new users of the bridge checkbox will make the bridge bot user start a DM with any new joining Element users and let them know how to get connected. If you wish to disable this behavior, leave this box unchecked.

Max Teams users

The bridge is billed based upon the number of participating Teams-side users, so you should set the maximum number of users you'd expect to see using the bridge to ensure your costs meet expectations. If the number of active Teams users exceeds this value, the bridge will be blocked, until you increase the limit. Whatever you set the limit to, you will only be charged for the number of remote users actively using the bridge.

Integrations

Telegram Bridge

This guide explains how to use the Telegram bridge from the EMS Integration Manager to integrate your Telegram chats with your EMS server.

It requires your EMS server to have federation on.

The following instructions are done with the Element Desktop on the Element side and on Element iOS for the Telegram side. Element Android should be almost identical to Element Web.

Purchase the Telegram integration

  1. Open the EMS control panel at: https://ems.element.io/user/hosting

  2. Click the Integrations tab and if you have more than one server, select the server you wish to add the Telegram integration to.
    temp

  3. Click on Telegram Bridge in the list of available Bridges.
    temp

  4. Enter the maximum number of users in Maximum Telegram users.
    Please note: this is the maximum number of Telegram users who actually send messages over the bridge each month. You are only billed for the number of Telegram users who are active. Once you exceed the maximum, then the bridge will be disabled until you increase the maximum.

Once you have entered Maximum Telegram users, click Purchase (remember you can always go back to this step and increase the maximum number of Telegram users if you need more in the future).

  1. A dialogue will remind you of the price per user and ask if you wish to proceed. Click Purchase if you wish to proceed with the Telegram Integration.
    temp

  2. You will have to wait a few minutes while your host is reprovisioned. Once reprovisioning is finished, you are able to bridge Telegram to your EMS server using your Element client.

Bridge Telegram to your Element account

  1. Once the bridge is running, open your Element app. Click on the + next to People.
    temp

  2. Create a Direct Message conversation by typing @telegram:example.ems.host (replace the domain with the one of your homeserver). Then click Go.

  3. Wait for the bridge account to join your room.

  4. Open Telegram on your mobile device (iOS or Android) and tap on ≡, go to Settings, and then Devices, and then Scan QR Code to start the Telegram QR code scanner. You will use this QR code scanner to scan a QR code displayed by your Element client in the next step.

  5. From your Element client, send a login-qr message to the bot to connect to your Telegram account.

  6. A QR code will be displayed. Quickly scan the QR code with Telegram on your mobile device.

  7. On your Element client, you will see Successfully logged in as <username>.

Sending a message to an Telegram User

To send a message to a Telegram user, you must first be connected to the bridge (see above).

  1. On your Element client, open the "Telegram bridge bot" room.

  2. Say pm followed by the phone number or username. The phone number must exist in your Telegram contacts.

  3. You will be invited to a DM with that user, and can send messages to them.

Bridging Matrix users without a Telegram acccount

By default, a Matrix user will have to connect their Telegram account for their messages to be bridged to Telegram. If you provide a bot token, we will use this bot to relay the messages of any Matrix users to Telegram.

Follow these steps to register a bot account with Telegram.

  1. With your Telegram account, message @BotFather.

  2. Create a new bot by sending the message /newbot to BotFather.

  3. Wait for BotFather to provide you a bot token.

Integrations

WhatsApp Bridge

This guide explains how to use the WhatsApp bridge from the EMS Integration Manager to integrate your WhatsApp chats with your EMS server.

It requires your EMS server to have federation on.

The following instructions are done with the Element Desktop on the Element side and on Element iOS for the WhatsApp side. Element Android should be almost identical to Element Web.

Purchase the WhatsApp integration

  1. Open the EMS control panel at: https://ems.element.io/user/hosting

  2. Click the Integrations tab and if you have more than one server, select the server you wish to add the WhatsApp integration to
    temp

  3. Click on WhatsApp Bridge in the list of available Bridges temp

  4. Enter the maximum number of users in Maximum WhatsApp users.
    Please note: this is the maximum number of WhatsApp users who actually send messages over the bridge each month. You are only billed for the number of WhatsApp users who are active. Once you exceed the maximum, then the bridge will be disabled until you increase the maximum.

    • If you enter less than 5, you will get a warning
      temp
    • If you enter 5 or greater in Maximum WhatsApp users, you will not see a warning
      temp
    • Once you have entered Maximum WhatsApp users, click Purchase (remember you can always go back to this step and increase the maximum number of WhatsApp users if you need more in the future).
  5. A dialogue will remind you of the price per user and ask if you wish to proceed. Click Purchase if you wish to proceed with the WhatsApp Integration
    temp

  6. You will have to wait a few minutes while your host is reprovisioned with the WhatsApp bridge. Once reprovisioning is finished, you are able to bridge WhatsApp to your EMS server using your Element client.

Bridge WhatsApp to your Element account

  1. Once the bridge is running, open your Element app. Click on the + next to People temp

  2. Create a Direct Message conversation by typing @whatsappbot:example.ems.host (replace the domain with the one of your homeserver). Then clickGo
    temp

  3. The bridge account will join your room and tell you how to use it temp

  4. Open WhatsApp on your mobile device (iOS or Android) and go to Settings and then Linked Devices and then Link a Device and tap OK to start the WhatsApp QR code scanner. You will use this QR code scanner to scan a QR code displayed by your Element client in the next step
    temp

  5. From your Element client, send a login message to the bot to connect to your WhatsApp account
    temp

  6. A QR code will be displayed. Quickly scan the QR code with WhatsApp on your mobile device. You have about a minute before it times out. If it times out, just send the login message again to generate another QR code
    temp

  7. On your Element client, you will see Successfully logged in, synchronizing chats... and you will see invitations for each of your WhatsApp chats in your Element client. Each WhatsApp chat is a separate Matrix room. Join one or more chats and start chatting from either your Element app on desktop, iOS or Android or your WhatsApp on mobile.

Sending a message to an WhatsApp User

To send a message to a WhatsApp user, you must first be connected to the bridge (see above).

  1. On your Element client, open the "WhatsApp bridge bot" room.
  2. Say pm followed by the international formatted phone number for your contact.
  3. You will be invited to a DM with that user, and can send messages to them.

For the EMS bridge to work, you must login to WhatsApp on iOS or Android every 14 days

From WhatsApp's documentation:

Your phone won’t need to stay online to use WhatsApp on linked devices, but if you don’t use your phone for over 14 days, your linked devices will become disconnected.

This means that you cannot uninstall the iOS or Android WhatsApp app and that you must login to that app every 14 days. If you don't, the Element WhatsApp Bridge will stop working.

Element

Element

Add Email to Your Account

  1. Go to Element All settings
    temp

  2. Enter your email address and click Add
    temp

  3. When you get this message, check your email
    temp

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

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

  6. Go back to Element and click Continue
    temp

  7. Enter your account password, then click Continue
    temp

  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
    temp

Element

Change Account Password

Resetting the account password will log out all your sessions. Before doing this, make sure that


If you know your current password

  1. Go to Element All settings
    temp

  2. Enter your current password and your new password
    temp

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

  4. Click Continue.
    Note: This warning is outdated, see this issue
    temp

  5. Click OK
    temp

  6. You now need to sign in again on all your other devices

If you do not know your current password

Note, 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. (support@matrix.org does not reset passwords in any circumstance)

  1. Sign out of Element
    temp

  2. Click Sign out
    temp

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

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

  5. Click Continue.
    Note: This warning is outdated, see this issue
    temp

  6. When you get this message, check your email
    temp

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

  8. Click Confirm changing my password
    temp

  9. You can now close this tab and return to Element
    temp

  10. Click i have verified my email address
    temp

  11. Click Return to login screen
    temp

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

Element

Submit Debug Logs

  1. Search for other issues of the same problem on

  2. If you cannot find any, create one by clicking New issue, then Get started in the Bug report section.
    temp
    temp

  3. Go to the section for your device

Element Web and Desktop

  1. Go to Element All settings
    temp

  2. Under Help & About, click Submit debug logs
    temp

  3. Enter a GitHub issue link and a description. Then click Send logs
    temp

  4. Click OK
    temp

Element iOS

  1. Tap the cog in the top left of Element
    temp

  2. Scroll down to the OTHER section, then tap Report bug
    temp

  3. Enter a GitHub issue link and a description, make sure Send logs is checked, then click Send
    temp

Element Android

  1. Tap the three stacked dots in the top right
    temp

  2. Tap Report bug
    temp

  3. Enter a GitHub issue link and a description, make sure Send logs, and Send crash logs are checked, then tap the send arrow in the top right
    temp

Cross Signing

Cross Signing

Check Status

  1. Go to Element Security & Privacy settings
    temp

  2. Expand the Advanced section
    temp

  3. Look for All keys backed up
    temp

Cross Signing

Export and Import E2E Room Keys

Element Web and Desktop

Export

  1. Go to Element Security & Privacy settings
    temp

  2. Click Export E2E room keys
    temp

  3. Enter a secure passphrase and click Export
    temp

  4. Choose to save the file
    temp

  5. Select a directory on your computer
    temp

Import

  1. Go to Element Security & Privacy settings
    temp

  2. Click Import E2E room keys
    temp

  3. Click Browse
    temp

  4. Select your export
    temp

  5. Enter your passphrase and click Import
    temp

Element iOS

Export

  1. Tap the cog in the top left of Element
    temp

  2. Tap Security
    temp

  3. Tap Export keys manually
    temp

  4. Enter a secure passphrase and tap Export
    temp

  5. Choose Save to Files
    temp

  6. Choose a location then tap Save
    temp

Import

This is a temporary solution until this issue is resolved

  1. Tap the + in the bottom right corner
    temp

  2. Tap Create room
    temp

  3. Tap the room name (Empty room) at the top
    temp

  4. Tap the room name again
    temp

  5. Under Advances, enable encryption
    temp

  6. Tab Done in the top right
    temp

  7. Tab the + to send a file
    temp

  8. Tap Send file
    temp

  9. Browse to and select your export
    temp

  10. Tap the file you just sent
    temp

  11. Tap Import
    temp

  12. Enter your passphrase and tap Import
    temp

Element Android

Export

  1. Tap your user picture in the top right
    temp

  2. Tap the cog
    temp

  3. Tap Security & Privacy
    temp

  4. Tap Export E2E room keys
    temp

  5. Select a location and a file name, then tap SAVE
    temp

  6. Enter a secure passphrase, then tap EXPORT
    temp

Import

  1. Tap your user picture in the top right
    temp

  2. Tap the cog
    temp

  3. Tap Security & Privacy
    temp

  4. Tap Import E2E room keys
    temp

  5. Browse to and select your export
    temp

  6. Enter your passphrase and tap IMPORT
    temp

Cross Signing

Reset Cross Signing

Only do this if you have forgotten or lost your cross signing backup passphrase.

Please read through the entire document before starting to make sure you understand the consequences of doing this.

If you have an active session

  1. You may wish to backup your keys before doing this just to be on the safe side if something goes wrong: See Export and Import E2E Room Keys

  2. Go to Element Security & Privacy settings
    temp

  3. Click Reset in the Cross-signing section

  4. Click Clear cross-signing keys
    temp

  5. Click Generate a Security Key or Enter a Security Phrase. Then Continue
    temp

  6. Take note of your key then click Continue
    temp

  7. Enter your account password and click Continue
    temp

  8. You can delete any untrusted sessions in Element Security & Privacy settings. Select the sessions you want to remove and click Delete 1 session
    temp

  9. Optionally, Sign out old devices no longer needed

If you DO NOT have an active session

Doing this will destroy all your keys and you will NOT be able to access any historical encrypted messages.

  1. Log in to Element
    temp

  2. Click Skip
    temp

  3. Click Skip again
    temp

  4. Do not connect to Key Backup or verify session when asked

  5. Note that you will not be able to decrypt any previous messages after doing this
    temp

  6. Follow the steps from If you have an active session

Sign out old devices

  1. Go to Element Security & Privacy settings
    temp

  2. Select the devices you wish to sign out

  3. Click Sign out n selected devices

  4. Authenticate with your Matrix account password or via SSO

Cross Signing

Set up Cross Signing

On first login to a new account

  1. Sign up or log in
    temp

  2. Click Generate a Security Key or Enter a Security Phrase. Then click Continue
    temp

  3. Take note of your key, then click Continue
    temp

If you did not set it up on first login, or if you did not get asked

  1. If you do not have key backup configured, you will be asked to set it up the first time you enter an encrypted room. Click Start using Key Backup
    temp

  2. Click Generate a Security Key or Enter a Security Phrase. Then Continue
    temp

  3. Take note of your key, then click Continue
    temp

  4. Enter your account password, then click Continue
    temp

If you clicked Don't ask me again

  1. Go to Element Security & Privacy settings
    temp

  2. Click Start using Key Backup
    temp

  3. Click Generate a Security Key or Enter a Security Phrase. Then Continue
    temp

  4. Take note of your key, then click Continue
    temp

  5. Enter your account password, then click Continue
    temp

Cross Signing

Verify new Login

When you log in to a new device/session, you must verify the login and connect it to cross signing and secret storage to access your backed up encryption keys for historical messages. This assumes you already have configured cross signing, see Set up Cross Signing.

  1. Log in to Element with your username and password
    Element Web login screen

  2. Choose one of the methods below for cross signing

Compare emojis using another login

  1. Click Use another login
    Element login screen
  2. On another device/session that is connected to cross signing, click Accept
    New session Verification request
  3. Click Start
    Choose method to Verify other login
  4. Compare the emojis on your new and old sessions. They should be the same emojis and in the same order. Click They match on both sessions
    Compare emojis
  5. If all was successful, you should get this green shield on both sessions. Click Got it. Your new device/session is now verified and will download your backed up message encryption keys
    Session verified green shield

Scan QR code on another login

Login is here demonstrated on Element Android

  1. On your phone, tap Verify this login
    Verify this login from Element Android
  2. Your phone is now waiting for you to accept from another device
    Waiting for another session to accept verification request
  3. On another device/session that is connected to cross signing, click Accept
    New session Verification request
  4. On your phone, tab Scan with this device
    Scan with this device
  5. Using your phone, scan the QR code shown on your other session
    QR code scanner on Element Android
    QR code for verification shown on the other session
  6. Your phone waits for you to confirm green shield on your other session. Click Yes
    Element Android waiting for other session
    Verify by scanning - both sessions should show the same green shield
  7. Tap Done on your phone
    Element Android - session verified
  8. If all was successful, you should get this green shield on both sessions. Click Got it. Your new device/session is now verified and will download your backed up message encryption keys
    Session verified green shield

Using your Security Key

  1. Click Use Security Key
    Verify this login, choose between using another device or entering security key
  2. Enter your Security key when prompted and click Continue
    Enter Security Key
  3. If all was successful, you should get this green shield on both sessions. Click Got it. Your new device/session is now verified and will download your backed up message encryption keys
    Session verified green shield

Non-English

Non-English

Deutsch: Nutzung der eigenen Domain mit EMS

Matrix ist ein Chat-Protokoll, mit dem Nutzer*innen auf verschiedenen Servern miteinander chatten können. Deshalb ist, wie bei E-Mail-Adressen, der Server fester Bestandteil einer jeden Nutzer-Adresse: @jennifer:unternehmen.de.

Nach dem @-Zeichen folgt der Benutzername und nach dem Doppelpunkt folgt die Server-Adresse.

Dies ist auch der Fall, wenn sie die Kommunikation mit anderen Matrix-Servern verbieten und ausschließlich intern chatten.

Gerne können Sie Ihre eigene Domain mit Element Matrix Services (EMS) nutzen. Damit werden die Matrix-Adressen Ihrer Anwender kürzer und auf Ihre Organisation anpasst.

Alternativ bietet Ihnen EMS ohne Aufpreis eine Subdomain. Hierbei ist keine Einrichtung Ihrerseits notwendig. Dann sehen die Adressen Ihrer Anwender*innen beispielsweise so aus: @jennifer:unternehmen.ems.host.

Hier sind die Vorteile der Optionen:

Vorteile einer eigenen Domain Vorteiler einer EMS-Subdomain
Nutzer- und Chat-Raum-Adressen sind kürzer und auf Ihre Organisation angepasst Sie können sofort mit einer verfügbaren Subdomain starten
Benötigt die Ablage von zwei Dateien auf Ihrer Webseite oder einen DNS-Eintrag (Anleitung für Ihr IT-Team ist unten im Text) Keine Anpassung in Ihrer IT notwendig
Migration zu anderen Anbietern oder in die eigene IT-Landschaft möglich Migration zu anderen Anbietern und in die eigene IT später nicht leicht möglich[^1]
Ihre Domain muss erreichbar bleiben Keine Verantwortung auf Ihrer Seite

[^1]: Bei der Einrichtung eines Matrix Servers muss eine Domain festgelegt werden. Ein Wechsel der Domain ist momentan nicht möglich. Die Domain wird Teil der Nutzer- und Chat-Adressen. Dies betrifft auch Server, welche nicht mit anderen Servern föderieren.

Reihenfolge der Einrichtung

Sie haben sich entschieden Ihre eigene Domain zu nutzen? Sehr gut!

  1. Bestellen Sie den Matrix-Server bei EMS unter Angabe ihrer eigenen Domain. Sie müssen auch eine EMS-Serveradresse im Format unternehmen.ems.host wählen.
  2. Folgen Sie der Anleitung im Abschnitt “Einrichtung auf Ihrem Webspace”.
  3. Überprüfen Sie auf https://ems.element.io/user/hosting, dass Ihre Domain erfolgreich eingerichtet wurde.

Einrichtung auf Ihrem Webspace

Diese Schritte müssen Sie tätigen, um Ihre eigene Domain zu verwenden.

Sollten Sie eine englische Anleitung bevorzugen, finden Sie diese hier: https://matrix-org.github.io/synapse/latest/delegate.html

Damit Anwendungen Ihren Matrix-Server bei EMS finden, müssen Sie auf Ihrer Domain einen Hinweis auf dessen Ort hinterlassen. Sie haben dafür die zwei folgenden Optionen.

Ablage von .well-known Dateien (empfohlene Option)

Erstellen Sie zwei statische JSON-Dateien auf Ihrer Webseite. Diese müssen unter den folgenden Pfaden öffentlich aus dem Internet erreichbar sein.

Statt matrix.org, sind hier die entsprechenden Pfade auf Ihrer Domain gemeint.

Ist der Ordner .well-known auf Ihrem Webspace nicht vorhanden, erstellen Sie ihn. Manche Programme blenden Ordner aus, wenn sie mit einem Punkt starten. Er könnte also schon existieren. Erstellen Sie darin einen Ordner matrix.

Die JSON-Dateien client und server dürfen keine Dateiendung haben und müssen die folgenden Inhalte haben. Ersetzen Sie “unternehmen” mit Ihrem EMS-Hostnamen. Diesen finden Sie auf https://ems.element.io/user/hosting vor “.ems.host”, z.B. “unternehmen.ems.host”. Wurde Ihr Server vor dem Sommer 2020 angelegt, hat er vermutlich die Endung “.modular.im”.

GET /.well-known/matrix/client

{
    "m.homeserver": {
        "base_url": "https://unternehmen.ems.host"
    },
    "m.identity_server": {
        "base_url": "https://vector.im"
    }
}

GET /.well-known/matrix/server

{
    "m.server": "unternehmen.ems.host:443"
}

Ersetzen Sie in beiden Beispielen unternehmen.ems.host durch Ihre EMS-Serveradresse.

Fehlerbehebung

Um zu überprüfen, ob alles korrekt eingerichtet wurde, geben Sie Ihre Domain auf der folgenden Webseite ein.

https://federationtester.matrix.org/ (Nur in englischer Sprache)

Eine grüne Fläche mit dem Wort “SUCCESS” signalisiert eine erfolgreiche Einrichtung. Auch in EMS sollten Sie nun unter https://ems.element.io/user/hosting eine erfolgreiche Prüfung der Domain vorfinden.

Ist eine rote Nachricht “Connection Errors” zu sehen, war eine Verbindung zum Server nicht möglich. Haben Sie den Server bei EMS schon bestellt? Ist Ihre Webseite nicht über HTTPS erreichbar? Hier sollte der .well-known Ordner und die darin enthaltene Datei öffentlich aus dem Internet zugänglich sein.

Sehen Sie die Nachricht “No SRV Records”, wurde der DNS-Eintrag nicht gefunden. Dieser Eintrag ist nur notwendig, sollten Sie keine Datei auf Ihrem Webspace veröffentlichen können. Überprüfen Sie, ob Sie alles richtig eingegeben haben und das Formular Ihres Domain-Anbieters gespeichert haben. Ist alles richtig, brauchen Sie vielleicht nur etwas zu warten. Nach dem Ändern von DNS-Einträgen braucht es ein paar Minuten, bis sich die Änderung im Internet verteilt.