# Element Cloud Documentation

# Element X status on EMS Cloud

This page outlines the current plan for making sliding sync (required for Element X) available for EMS cloud customers. The page will be updated if anything changes.

See the Element blog post “[Element X: Ignition](https://element.io/blog/element-x-ignition/)” for more information on Element X.

### Hosts using traditional password authentication

All EMS hosts using traditional password authentication now have the sliding sync proxy and you can start using Element X.

### Hosts using delegated authentication/SSO including Element One users

A pre-requisite of support for Element X is adding support for the Matrix Authentication Service (MAS) to Element Matrix Services (EMS).

Whilst significant progress has been made in developing MAS work to add support for it to EMS is not due until 2025 - we'd advise checking the [Element Blog](https://element.io/blog/) for the latest updates where we'll announce its support in the future.

# Frequently Asked Questions

## Account Management

<details id="bkmrk-can-i-migrate-from-e"> <summary>Can I migrate from Element One to Element Home/Cloud?</summary>

Unfortunately, Element One and Home are different products and do not currently have an upgrade path. You can set up an Element Home/Cloud host, then manually invite your new Element Home account to all rooms from your Element One account. Bridged rooms have to be manually re-bridged from your Home host.

The same applies to migration from Element Home/Cloud to Element One.

</details><details id="bkmrk-how-do-i-enable-2fa-"> <summary>How do I enable 2FA on my EMS account?</summary>

- Sign in to your EMS account on [https://ems.element.io/](https://ems.element.io/)
- Click `Your Account` in the top-right
- Click `Account`
- Click `Authentication Settings`
- Click `Signing in` in the `Account security` card
- Click `Set up Authenticator Application`
- Follow the instructions on the page to complete the 2FA setup

**Please note:**

- Only one 2FA device is supported. If you add multiple 2FA devices, you will be unable to sign in.
- This only applies to your account in the EMS control panel and your Element One account. Not to Matrix accounts on dedicated EMS servers.

</details><details id="bkmrk-please-discontinue-m"> <summary>Please discontinue my account</summary>

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](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.

You can manage or cancel your Element One subscription on [https://ems.element.io/user/hosting#/elementone](https://ems.element.io/user/hosting#/elementone).

Or delete the EMS account entirely. This is done from the user account page [https://ems.element.io/user/account](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.

</details>## Integrations

<details id="bkmrk-bots%3F-what%27s-the-rea"> <summary>Bots? What's the reason for using them?</summary>

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/](https://www.matrix.org/ecosystem/integrations/).

</details><details id="bkmrk-can-i-host-my-own-te"> <summary>Can I host my own Telegram bridge?</summary>

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](https://element.io/blog/telegram-bridging/).

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

</details><details id="bkmrk-do-dms-count-towards"> <summary>Do DMs count towards the 20-channel limit for the paid Slack bridge?</summary>

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.

</details><details id="bkmrk-how-do-i-add-a-githu"> <summary>How do I add a GitHub integration?</summary>

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.

</details><details id="bkmrk-how-do-i-add-rss-int"> <summary>How do I add RSS integration to my Matrix server?</summary>

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.

</details><details id="bkmrk-how-do-i-bridge-to-l"> <summary>How do I bridge to Libera Chat IRC rooms with more than 100 users?</summary>

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.

</details><details id="bkmrk-what-is-the-differen"> <summary>What is the difference between the free and paid Slack bridge?</summary>

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?](#bkmrk-do-dms-count-towards)

</details><details id="bkmrk-with-jitsi-video-con"> <summary>With Jitsi video conferencing, how is the data being transferred?</summary>

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.

</details>## Miscellaneous

<details id="bkmrk-are-all-my-messages-"> <summary>Are all my messages stored on my homeserver?</summary>

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.

</details><details id="bkmrk-how-do-i-send-%22syste"> <summary>How do I send "System Alerts" or post from the @server user?</summary>

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.

</details><details id="bkmrk-how-do-i-update-exte"> <summary>How do I update External IDs for my users?</summary>

When managing SSO integrations, you might need to edit the external IDs for your Matrix users. This can be done using the [Synapse Admin API](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#create-or-modify-account). You can follow this knowledge base page for further details, [How do I migrate to SSO while keeping my original accounts?](https://ems-docs.element.io/books/ems-knowledge-base/page/how-do-i-migrate-to-sso-while-keeping-my-original-accounts).

</details><details id="bkmrk-is-there-a-maximum-f"> <summary>Is there a maximum file size per upload?</summary>

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

</details><details id="bkmrk-what-are-the-benefit"> <summary>What are the benefits of paying for an EMS homeserver?</summary>

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.

</details><details id="bkmrk-what-are-the-limitat"> <summary>What are the limitations in terms of storage?</summary>

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.

</details>## Pricing &amp; Payment

<details id="bkmrk-do-you-offer-other-p"> <summary>Do you offer other payment options like PayPal, Crypto, or IBAN/SEPA?</summary>

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

</details><details id="bkmrk-how-do-i-update-my-p"> <summary>How do I update my payment info?</summary>

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

</details><details id="bkmrk-if-i-join-a-room-wit"> <summary>If I join a room with a lot of external users from my homeserver, will I be charged for those?</summary>

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.

</details>## Server Configuration &amp; Management

<details id="bkmrk-are-custom-appservic"> <summary>Are custom appservices supported?</summary>

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.

</details><details id="bkmrk-are-you-able-to-use-"> <summary>Are you able to use a custom domain like "matrix.example.com"?</summary>

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.

</details><details id="bkmrk-can-i-add-all-my-use"> <summary>Can I add all my users to a Space by default?</summary>

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

</details><details id="bkmrk-can-i-change-the-def"> <summary>Can I change the default room notification level for my users?</summary>

This is currently not possible, unfortunately.

</details><details id="bkmrk-can-i-customize-the-"> <summary>Can I customize the Element web login page?</summary>

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/](https://element.io/blog/custom-branding/) and [Client Look &amp; Feel](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](https://ems.element.io/user/hosting).

</details><details id="bkmrk-can-i-use-a-subdomai"> <summary>Can I use a subdomain instead of the root domain with my EMS server?</summary>

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://element-hq.github.io/synapse/latest/setup/installation.html#choosing-your-server-name](https://element-hq.github.io/synapse/latest/setup/installation.html#choosing-your-server-name) for additional details on your server name.

</details><details id="bkmrk-can-i-use-ems-hosted"> <summary>Can I use EMS-hosted well-knowns with the root of my domain?</summary>

Yes, you can, but there are some limitations:

- You will not be able to serve a website on the domain.
- Using a CNAME DNS record on the root of a domain is not compliant with the DNS Specification (per [Domain Name System RFC 1034, paragraph 3.6.2](https://joinup.ec.europa.eu/collection/ict-standards-procurement/solution/dns-rfc-1034-rfc-1035-domain-name-system/about) specifically). But you may still be able to do this successfully if: 
    - Your DNS provider allows setting a CNAME record on the root of your domain. Be aware that certain other DNS records for your domain will not be returned properly, including SOA, NS, and TXT records. (Such as SPF, DMARC, and DKIM, which are used for securing email), OR
    - Your DNS provider offers a DNS Spec compliant workaround for using CNAME on root. This includes ALIAS records and CloudFlare CNAME Flattening (note that proxy must be turned off). 
        - When using this, please note that the EMS Control Panel will not recognize your DNS record as correct, but your EMS server will function correctly and without limitations (beyond the yellow warning in the EMS Control Panel)
- If your DNS provider does not allow CNAME records on root or a DNS Spec compliant solution like ALIAS records, you can use an A record instead. To do this, finish setting up your EMS server without adding the DNS record when asked. After setup is complete, check the IP address of your EMS server, for example, with `$ dig example.ems.host` in the Mac/Linux terminal or `Resolve-DnsName -Name example.ems.host` in Windows PowerShell, then add an A record on the root of your domain pointing to this IP address. 
    - **Please note that EMS does not officially support this, and we reserve the right to change the IP address of your EMS server without notice.**
    - You will see the same error in the EMS Control Panel as above, but your EMS server will work with this configuration.
- Using a subdomain for your EMS server. By doing this, you will not see any of the limitations and do not need any of the workarounds listed above. However, please consider [Can I use a subdomain instead of the root domain with my EMS server?](#bkmrk-can-i-use-a-subdomai)

</details><details id="bkmrk-cname-and-.well-know"> <summary>CNAME and .well-known?</summary>

- You need to create a CNAME record with your DNS provider. This needs to be: **chat.example.com. CNAME yourEMShost.element.io.**(please note that proxy must be turned off if you are using CloudFlare)
- You need to set up a website on your domain, e.g., `example.com`.
- This website needs HTTPS enabled.
- You need to create two files on the webserver. These need to be located at exactly: 
    - `https://example.com/.well-known/matrix/client`
    - `https://example.com/.well-known/matrix/server`
- You need to enable the CORS header `Access-Control-Allow-Origin: *` on the webserver for the client file. See [https://enable-cors.org/](https://enable-cors.org/) for instructions on how to do this.

The client file needs to contain:

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

```

The server file needs to contain:

```json
{
    "m.server": "yourEMShost.ems.host:443"
}

```

</details><details id="bkmrk-cname-doesn%27t-work-w"> <summary>CNAME doesn't work with Cloudflare?</summary>

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

</details><details id="bkmrk-could-you-expand-on-"> <summary>Could you expand on "over federation"?</summary>

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.

</details><details id="bkmrk-dns-is-not-resolving"> <summary>DNS is not resolving</summary>

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

</details><details id="bkmrk-how-can-i-manage-my-"> <summary>How can I manage my #general room?</summary>

You can gain admin permissions in this room by calling [this](https://element-hq.github.io/synapse/latest/admin_api/rooms.html#make-room-admin-api) Synapse Admin API or by contacting EMS Support at [https://ems.element.io/support](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.

</details><details id="bkmrk-how-do-i-change-the-"> <summary>How do I change the name/brand of the Element Web client?</summary>

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](https://ems.element.io/user/hosting#/hosts). See [Client Look &amp; Feel](client-look-feel) for additional details.

</details><details id="bkmrk-how-do-i-change-the--1"> <summary>How do I change the server's custom domain?</summary>

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.

</details><details id="bkmrk-delete-room-or-space"> <summary>How do I delete a room or a space?</summary>

Go to [https://ems.element.io/user/hosting#/admin](https://ems.element.io/user/hosting#/admin), click `Rooms`, and find the room or space you want to delete. Then click the &lt;svg stroke="currentColor" fill="#de4437" stroke-width="0" viewBox="0 0 512 512" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg"&gt;<path d="M133.1 128l23.6 290.7c0 16.2 13.1 29.3 29.3 29.3h141c16.2 0 29.3-13.1 29.3-29.3L379.6 128H133.1zm61.6 265L188 160h18.5l6.9 233h-18.7zm70.3 0h-18V160h18v233zm52.3 0h-18.6l6.8-233H324l-6.7 233zM364 92h-36l-26.3-23c-3.7-3.2-8.4-5-13.2-5h-64.8c-4.9 0-9.7 1.8-13.4 5L184 92h-36c-17.6 0-30 8.4-30 26h276c0-17.6-12.4-26-30-26z"></path> button to delete it.

</details><details id="bkmrk-how-do-i-delete-user"> <summary>How do I delete users when administering the server?</summary>

You can deactivate users from the admin dashboard for your host at [https://ems.element.io/user/hosting](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.

</details><details id="bkmrk-how-do-i-enable-the-"> <summary>How do I enable the public room directory?</summary>

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

</details><details id="bkmrk-how-do-i-reactivate-"> <summary>How do I reactivate a user?</summary>

- Go to the [Server Admin](https://ems.element.io/user/hosting#/admin) tab of the EMS Control Panel
- Click the &lt;svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"&gt;<path d="M9.16667 15H10.8333C11.2917 15 11.6667 14.625 11.6667 14.1667C11.6667 13.7083 11.2917 13.3333 10.8333 13.3333H9.16667C8.70833 13.3333 8.33333 13.7083 8.33333 14.1667C8.33333 14.625 8.70833 15 9.16667 15ZM2.5 5.83333C2.5 6.29167 2.875 6.66667 3.33333 6.66667H16.6667C17.125 6.66667 17.5 6.29167 17.5 5.83333C17.5 5.375 17.125 5 16.6667 5H3.33333C2.875 5 2.5 5.375 2.5 5.83333ZM5.83333 10.8333H14.1667C14.625 10.8333 15 10.4583 15 10C15 9.54167 14.625 9.16667 14.1667 9.16667H5.83333C5.375 9.16667 5 9.54167 5 10C5 10.4583 5.375 10.8333 5.83333 10.8333Z" fill="currentColor"></path> button
- Select `Include deactivated accounts`
- Click the user you wish to reactivate from the list
- Click `Reactivate account`

</details><details id="bkmrk-how-do-i-migrate-fro"> <summary>How do I migrate from EMS to self-hosted if I choose to do so in the future?</summary>

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.

</details><details id="bkmrk-i-deleted-my-host%2C-n"> <summary>I deleted my host, now my server name is taken, and I cannot rebuild</summary>

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](https://ems.element.io/support) while signed in to get the hostname released.

</details><details id="bkmrk-online-users-are-dis"> <summary>Online users are displayed as offline?</summary>

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.

</details><details id="bkmrk-what-does-%22include-b"> <summary>What does "Include bridged accounts" on the user management page mean?</summary>

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.

</details>

# Element Matrix Services



# Add Additional Users

1. Click `Your Account` and `Manage Servers` or click this link <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a>.
1. Click the Hosts tab.
1. Change `Total Monthly Active User Seats` to the number of users you want and click `Save` at the bottom.  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-04/scaled-1680-/image-1651236785028-51-31-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-04/image-1651236785028-51-31-pm.png)
    - Note that you cannot decrease your user count later.

# Add Users

1. Click `Your Account` and `Manage Servers` or click this link: <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a>

1. Click `Server Admin`

1. Select your host

1. Click `Add user` Enter the username and click `Add`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702382821288-34-01-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702382821288-34-01-pm.png)

1. Select `Make new user server admin` if you want this user to be able to use the <a href="https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html" target="_blank" rel="noopener noreferrer">Synapse Admin API</a> to perform administrative tasks on your server. Be careful with this as this option has a lot of power on your server.

1. 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  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702382889442-37-05-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702382889442-37-05-pm.png)

# Apply coupon/discount

Coupons can only be applied by new customers before purchasing any products. However, if you are an existing customer and want to add a coupon, please contact support at <https://ems.element.io/support>.

Terms and Conditions apply. See the page for your coupon or ask your Element contact or support.

- Create your EMS account normally
- If you have agreed to pay by invoice/bank transfer, stop here and let your Element contact know you have created your account so they can enable invoice payment for you
- Add your billing address and payment card on <https://ems.element.io/user/billing>, or click `Your Account`, then `Billing`  
    [![](https://ems-docs.element.io/uploads/images/gallery/2022-11/scaled-1680-/image-1667843563093-36-13-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-11/image-1667843563093-36-13-pm.png)
- Go to <https://ems.element.io/user/account>, or click `Your Account`, then `Account`
- If you are a business, you must enter your company name and if applicable, VAT ID here  
    [![](https://ems-docs.element.io/uploads/images/gallery/2023-07/scaled-1680-/image-1689152455628-59-46-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-07/image-1689152455628-59-46-am.png)
- Click `Show Discounts`
- Enter your coupon code and click `Apply coupon`  
    [![](https://ems-docs.element.io/uploads/images/gallery/2022-11/scaled-1680-/image-1667843574754-43-32-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-11/image-1667843574754-43-32-pm.png)  
    [![](https://ems-docs.element.io/uploads/images/gallery/2022-11/scaled-1680-/image-1667843583549-43-46-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-11/image-1667843583549-43-46-pm.png)
- [Continue host setup normally](get-your-own-ems-server). The discount will automatically be applied to all applicable products  
    [![](https://ems-docs.element.io/uploads/images/gallery/2022-11/scaled-1680-/image-1667843601268-48-08-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-11/image-1667843601268-48-08-pm.png)

# Client Look & Feel

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

## Blog posts

See also our blog posts on the subject:

- [Build your own custom branded chat platform at the touch of a button!](https://element.io/blog/custom-branding/)
- [A white label messaging app to create your own brand messenger](https://element.io/blog/a-white-label-messaging-app-to-create-your-own-brand-messenger-2/)

## Create home and login template

1. Create the files you want to use.

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

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

        You can also add a more complex HTML and styling.

    2. It looks like this in your web browser:  
        [![](https://ems-docs.element.io/uploads/images/gallery/2022-10/scaled-1680-/image-1665155682392.png)](https://ems-docs.element.io/uploads/images/gallery/2022-10/image-1665155682392.png)

    3. Edit `ems_welcome.html`. This is a bit more complex, but it can be almost anything you want as long as it has links to `Log in` (`/#/login`) and `Create account` (`/#/register`). The default design is based on <a href="https://github.com/element-hq/element-web/blob/master/res/welcome.html" target="_blank" rel="noopener noreferrer">this template</a>. You can get creative with the CSS and the `!important` tag. 

        <details>
            <summary>Click to see ems_welcome contents</summary>

        The only change I made from the template is adding `<p>This is some demo text!</p>` on line 177.

        ```html
        <style type="text/css">

        /* we deliberately inline style here to avoid flash-of-CSS problems, and to avoid
        * voodoo where we have to set display: none by default
        */

        h1::after {
            content: "!";
        }

        .mx_Parent {
            display: -webkit-box;
            display: -webkit-flex;
            display: -ms-flexbox;
            display: flex;
            -webkit-box-orient: vertical;
            -webkit-box-direction: normal;
            -webkit-flex-direction: column;
            -ms-flex-direction: column;
            flex-direction: column;
            -webkit-box-pack: center;
            -webkit-justify-content: center;
            -ms-flex-pack: center;
            justify-content: center;
            -webkit-box-align: center;
            -webkit-align-items: center;
            -ms-flex-align: center;
            align-items: center;
            text-align: center;
            padding: 25px 35px;
            color: #2e2f32;
        }

        .mx_Logo {
            height: 54px;
            margin-top: 2px;
        }

        .mx_ButtonGroup {
            margin-top: 10px;
        }

        .mx_ButtonRow {
            display: -webkit-box;
            display: -webkit-flex;
            display: -ms-flexbox;
            display: flex;
            -webkit-justify-content: space-around;
            -ms-flex-pack: distribute;
            -webkit-box-align: center;
            -webkit-align-items: center;
            -ms-flex-align: center;
            align-items: center;
            justify-content: space-between;
            box-sizing: border-box;
            margin: 12px 0 0;
        }

        .mx_ButtonRow > * {
            margin: 0 10px;
        }

        .mx_ButtonRow > *:first-child {
            margin-left: 0;
        }

        .mx_ButtonRow > *:last-child {
            margin-right: 0;
        }

        .mx_ButtonParent {
            display: -webkit-box;
            display: -webkit-flex;
            display: -ms-flexbox;
            display: flex;
            padding: 10px 20px;
            -webkit-box-orient: horizontal;
            -webkit-box-direction: normal;
            -webkit-flex-direction: row;
            -ms-flex-direction: row;
            flex-direction: row;
            -webkit-box-pack: center;
            -webkit-justify-content: center;
            -ms-flex-pack: center;
            justify-content: center;
            -webkit-box-align: center;
            -webkit-align-items: center;
            -ms-flex-align: center;
            align-items: center;
            border-radius: 4px;
            width: 150px;
            background-repeat: no-repeat;
            background-position: 10px center;
            text-decoration: none;
            color: #2e2f32 !important;
        }

        .mx_ButtonLabel {
            margin-left: 20px;
        }

        .mx_Header_title {
            font-size: 24px;
            font-weight: 600;
            margin: 20px 0 0;
        }

        .mx_Header_subtitle {
            font-size: 12px;
            font-weight: normal;
            margin: 8px 0 0;
        }

        .mx_ButtonSignIn {
            background-color: #368BD6;
            color: white !important;
        }

        .mx_ButtonCreateAccount {
            background-color: #0DBD8B;
            color: white !important;
        }

        .mx_SecondaryButton {
            background-color: #FFFFFF;
            color: #2E2F32;
        }

        .mx_Button_iconSignIn {
            background-image: url('welcome/images/icon-sign-in.svg');
        }
        .mx_Button_iconCreateAccount {
            background-image: url('welcome/images/icon-create-account.svg');
        }
        .mx_Button_iconHelp {
            background-image: url('welcome/images/icon-help.svg');
        }
        .mx_Button_iconRoomDirectory {
            background-image: url('welcome/images/icon-room-directory.svg');
        }

        /*
        .mx_WelcomePage_loggedIn is applied by EmbeddedPage from the Welcome component
        If it is set on the page, we should show the buttons. Otherwise, we have to assume
        we don't have an account and should hide them. No account == no guest account either.
        */
        .mx_WelcomePage:not(.mx_WelcomePage_loggedIn) .mx_WelcomePage_guestFunctions {
            display: none;
        }

        .mx_ButtonRow.mx_WelcomePage_guestFunctions {
            margin-top: 20px;
        }
        .mx_ButtonRow.mx_WelcomePage_guestFunctions > div {
            margin: 0 auto;
        }

        @media only screen and (max-width: 480px) {
            .mx_ButtonRow {
                flex-direction: column;
            }

            .mx_ButtonRow > * {
                margin: 0 0 10px 0;
            }
        }

        </style>

        <div class="mx_Parent">
            <a href="https://element.io" target="_blank" rel="noopener">
                <img src="welcome/images/logo.svg" alt="" class="mx_Logo"/>
            </a>
            <h1 class="mx_Header_title">_t("Welcome to Element")</h1>
            <!-- XXX: Our translations system isn't smart enough to recognize variables in the HTML, so we manually do it -->
            <h4 class="mx_Header_subtitle">_t("Decentralised, encrypted chat &amp; collaboration powered by $matrixLogo")</h4>
            <p>This is some demo text!</p>
            <div class="mx_ButtonGroup">
                <div class="mx_ButtonRow">
                    <a href="#/login" class="mx_ButtonParent mx_ButtonSignIn mx_Button_iconSignIn">
                        <div class="mx_ButtonLabel">_t("Sign In")</div>
                    </a>
                    <a href="#/register" class="mx_ButtonParent mx_ButtonCreateAccount mx_Button_iconCreateAccount">
                        <div class="mx_ButtonLabel">_t("Create Account")</div>
                    </a>
                </div>
                <!-- The comments below are meant to be used by Ansible as a quick way
                    to strip out the marked content when desired.
                    See https://github.com/element-hq/element-web/issues/8622.
                    TODO: Strip out these comments and rely on the guest flag -->
                <!-- BEGIN Ansible: Remove these lines when guest access is disabled -->
                <div class="mx_ButtonRow mx_WelcomePage_guestFunctions">
                    <div>
                        <a href="#/directory" class="mx_ButtonParent mx_SecondaryButton mx_Button_iconRoomDirectory">
                            <div class="mx_ButtonLabel">_t("Explore rooms")</div>
                        </a>
                    </div>
                </div>
                <!-- END Ansible: Remove these lines when guest access is disabled -->
            </div>
        </div>
        ```

        </details>

    4. It looks like this in your web browser:  
        [![](https://ems-docs.element.io/uploads/images/gallery/2022-10/scaled-1680-/image-1665155688548.png)](https://ems-docs.element.io/uploads/images/gallery/2022-10/image-1665155688548.png)

## Serve the files

You must host the files somewhere where they are publickly accessible and you need to enable the CORS header `Access-Control-Allow-Origin: *` on the web server for these files. See <a href="https://enable-cors.org/" target="_blank" rel="noopener noreferrer">https://enable-cors.org/</a> for instructions on how to do this.

## Configure your EMS server

1. Add the URLs to the `Client look & feel` section in the EMS Control Panel. Click `Save`.  
    [![](https://ems-docs.element.io/uploads/images/gallery/2022-10/scaled-1680-/image-1665159064784-09-09-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-10/image-1665159064784-09-09-pm.png)  
    <sup>Unfortunately, we have a bug in the validator affecting files hosted on Matrix. Just ignore the error.</sup>

    - Note if you are hosting the files on your own web server, you only need to change your EMS server configuration or reprovision if the URLs have changed. Changes to the contents of existing files are applied automatically
2. Once your host finishes reprovisioning, check your Element Web to ensure the changes are applied correctly.

    1. Welcome page image and Welcome page content  
        [![](https://ems-docs.element.io/uploads/images/gallery/2022-10/scaled-1680-/image-1665159230891-12-16-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-10/image-1665159230891-12-16-pm.png)

    2. Client logo  
        [![](https://ems-docs.element.io/uploads/images/gallery/2022-10/scaled-1680-/image-1665155735797.png)](https://ems-docs.element.io/uploads/images/gallery/2022-10/image-1665155735797.png)

    3. Home page content  
        [![](https://ems-docs.element.io/uploads/images/gallery/2022-10/scaled-1680-/image-1665159253171-12-49-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-10/image-1665159253171-12-49-pm.png)

## Image Credits

- [Client logo image](https://www.pexels.com/photo/close-up-photography-of-tiger-3660441/) by [Charles Miller](https://www.pexels.com/@charles-miller-1020744/) used under the terms of [Free to use License](https://www.pexels.com/license/).
- [Welcome page image](https://www.pexels.com/photo/animal-world-attention-branch-cat-267074/) by [Pixabay](https://www.pexels.com/@pixabay/) used under the terms of [Free to use (CC0) License](https://www.pexels.com/creative-commons-images/).

# Domains and IP addresses

This document contains a list of all domains users of your EMS hosted cloud server needs permission to connect to. The list may include content delivery or telemetry endpoints which may not be required, but not allowing them may have unintended effects. Blocking any endpoints is not a supported environment.

This page was last updated on January 30, 2024. **Subject to change at any time without notice.**

**We do not guarantee any IP addresses or CNAME values for EMS services. Both can change at any time without notice. We also cannot make any guarantees about external services, for example `api.github.com`.**

**Dependencies for services hosted by third parties, for example `status.element.io`, are outside our control and may change at any time without notice.**

## Domains

### Base Domains

- `https://sentry.tools.element.io:443/tcp`

#### Homeserver

This is the endpoint where your clients connect to the EMS Matrix homeserver. It is required for all services

- `https://ems-hostname.ems.host:443/tcp`

If your EMS server was set up before mid-2020, you also need `https://ems-hostname.modular.im:443/tcp`

#### Element

This is where your Element Web client is hosted. It is required for most services.

- `https://ems-hostname.element.io:443/tcp`

If your EMS server was set up before mid-2020, you also need `https://ems-hostname.riot.im:443/tcp`

##### Custom Element Web DNS

If you have Custom DNS configured for your Element Web client, `https://custom-dns-element-web.com:443/tcp` will be required in addition to `https://ems-hostname.element.io:443/tcp` for all services accessed through Element.

##### Element Desktop

For Element Desktop, neither `https://ems-hostname.element.io:443/tcp` or `https://custom-dns-element-web.com:443/tcp` are required when accessing any service through Element.

#### Identity Server

See [What is an Identity Server, and how does it work?](https://ems-docs.element.io/link/6#bkmrk-what-is-an-identity-) in the FAQ.

- `https://vector.im:443/tcp`

### Element Call

<https://call.element.io/>

- `https://call.element.io:443/tcp`
- `https://call.ems.host:443/tcp`
- `https://livekit-jwt.call.element.io:443/tcp`
- `https://posthog-element-call.element.io:443/tcp`

#### SFU

- `wss://sfu.call.element.io`

#### Google STUN

- `stun.l.google.com:19302/udp`
- `stun1.l.google.com:19302/udp`

### Element Web

<https://ems-hostname.element.io>

[Base domains](#bkmrk-base-domains) only

### EMS Control Panel

<https://ems.element.io/user/hosting>

- `https://custom-dns-homeserver.com:443/tcp`
- `https://ems.element.io:443/tcp`
- `https://id.element.io:443/tcp`
- `https://js.stripe.com:443/tcp`
- `https://m.stripe.com:443/tcp`
- `https://m.stripe.network:443/tcp`
- `https://matomo.riot.im:443/tcp`
- `https://pay.stripe.com:443/tcp`
- `https://sentry.matrix.org:443/tcp`

### EMS Documentation

<https://element-hq.github.io/synapse/latest/>  
<https://element-hq.github.io/synapse/latest/>  
<https://ems-docs.element.io/>  
<https://matrix-org.github.io/matrix-hookshot/latest/index.html>

- `https://api.github.com:443/tcp`
- `https://element-hq.github.io:443/tcp`
- `https://ems-docs.element.io:443/tcp`
- `https://fonts.googleapis.com:443/tcp`
- `https://github.com:443/tcp`
- `https://img.shields.io:443/tcp`
- `https://matrix-org.github.io:443/tcp`
- `https://sonarcloud.io:443/tcp`
- `https://user-images.githubusercontent.com:443/tcp`
- `https://web-docs.element.dev:443/tcp`

### EMS Status page

<https://status.element.io/>

- `https://dka575ofm4ao0.cloudfront.net:443/tcp`, possibly `*.cloudfront.net`
- `https://fonts.gstatic.com:443/tcp`
- `https://polyfill.io:443/tcp`
- `https://status.element.io:443/tcp`
- `https://www.google.com:443/tcp`
- `https://www.gstatic.com:443/tcp`
- `https://www.recaptcha.net:443/tcp`

### Hookshot (Dedicated)

[Base domains](#bkmrk-base-domains) only

### Identity Server

- `https://matrix.org:443/tcp`, for loading a logo/image on email verification page, not required

### Integration Server

- `https://integrations.element.io:443/tcp`
- `https://integrations.ems.host:443/tcp`
- `https://scalar.vector.im:443/tcp`

### Integration Widgets

The integration Server is required for all widgets

#### Ethercalc

- `https://ethercalc.net:443/tcp`
- `wss://ethercalc.net`

#### Etherpad

- `https://etherpad.integrations.element.io:443/tcp`
- `wss://etherpad.integrations.element.io`

#### Feeds

[Base domains](#bkmrk-base-domains) and [Integration Server domains](#bkmrk-integration-server) only

#### GitHub

[Base domains](#bkmrk-base-domains) and [Integration Server domains](#bkmrk-integration-server) only

##### Connect/Authenticate

- `https://api.github.com:443/tcp`
- `https://avatars.githubusercontent.com:443/tcp`
- `https://collector.github.com:443/tcp`
- `https://github.com:443/tcp`
- `https://github.githubassets.com:443/tcp`

#### Google Calendar

[Base domains](#bkmrk-base-domains) and [Integration Server domains](#bkmrk-integration-server) only

#### Grafana

[Base domains](#bkmrk-base-domains) and [Integration Server domains](#bkmrk-integration-server) only

#### Jitsi

<https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker/#external-ports>

- `https://meet.element.io:10000/udp`
- `https://meet.element.io:20000-20050/udp`
- `https://meet.element.io:443/tcp`
- `https://meet.element.io:80/tcp`
- `https://www.gravatar.com:443/tcp`
- `wss://meet.element.io`

#### Spotify

- `https://apresolve.spotify.com:443/tcp`
- `https://embed-cdn.spotifycdn.com:443/tcp`
- `https://encore.scdn.co:443/tcp`
- `https://gew1-spclient.spotify.com:443/tcp`
- `https://i.scdn.co:443/tcp`
- `https://open.spotify.com:443/tcp`
- `https://p.scdn.co:443/tcp`
- `https://spclient.wg.spotify.com:443/tcp`
- `https://web-sdk-assets.spotifycdn.com:443/tcp`

#### Sticker packs

- `https://matrix.org:443/tcp`

#### TradingView

- `https://economic-calendar.tradingview.com:443/tcp`
- `https://s.tradingview.com:443/tcp`
- `https://s3-symbol-logo.tradingview.com:443/tcp`
- `https://s3.tradingview.com:443/tcp`
- `https://static.tradingview.com:443/tcp`
- `https://www.tradingview-widget.com:443/tcp`
- `wss://pushstream.tradingview.com`
- `wss://widgetdata.tradingview.com`

#### Youtube

- `https://fonts.gstatic.com:443/tcp`
- `https://googleads.g.doubleclick.net:443/tcp`
- `https://i.ytimg.com:443/tcp`
- `https://jnn-pa.googleapis.com:443/tcp`
- `https://rr5---sn-aigzrn7e.googlevideo.com:443/tcp`, possibly `*.googlevideo.com`
- `https://static.doubleclick.net:443/tcp`
- `https://www.google.com:443/tcp`
- `https://www.gstatic.com:443/tcp`
- `https://www.youtube.com:443/tcp`
- `https://youtube.com:443/tcp`
- `https://yt3.ggpht.com:443/tcp`

### Legacy call in Element client

[Base domains](#bkmrk-base-domains) only

### Location Service (Maptiler)

- `https://api.maptiler.com:443/tcp`

#### Open in OpenStreetMap

- `https://matomo.openstreetmap.org:443/tcp`
- `https://tile.openstreetmap.org:443/tcp`
- `https://www.openstreetmap.org:443/tcp`

### Sliding Sync

[Base domains](#bkmrk-base-domains) only

### Synapse

[Base domains](#bkmrk-base-domains) only

### Well-Known

If you have Custom DNS for your homeserver:

- `https://custom-dns-homeserver.com:443/tcp`

### Notification Service Element Proxy

### Other

## IP Addresses

**We do not guarantee any IP addresses or CNAME values for EMS services. Both can change at any time without notice. We also cannot make any guarantees about external services, for example `api.github.com`.**

But for your convenience, here are the IP addresses and CNAME values as seen on January 30, 2024.

<details>
<summary>Click to expand</summary>

```bash
$ dig +noall +answer all api.github.com
api.github.com.		9	IN	A	140.82.121.5

$ dig +noall +answer all api.maptiler.com
api.maptiler.com.	140	IN	A	104.17.88.87
api.maptiler.com.	140	IN	A	104.17.91.87
api.maptiler.com.	140	IN	A	104.17.90.87
api.maptiler.com.	140	IN	A	104.17.87.87
api.maptiler.com.	140	IN	A	104.17.89.87

$ dig +noall +answer all apresolve.spotify.com
apresolve.spotify.com.	293	IN	A	35.186.224.25

$ dig +noall +answer all avatars.githubusercontent.com
avatars.githubusercontent.com. 2561 IN	A	185.199.108.133
avatars.githubusercontent.com. 2561 IN	A	185.199.109.133
avatars.githubusercontent.com. 2561 IN	A	185.199.111.133
avatars.githubusercontent.com. 2561 IN	A	185.199.110.133

$ dig +noall +answer all call.element.io
call.element.io.	279	IN	A	172.67.12.112
call.element.io.	279	IN	A	104.22.49.198
call.element.io.	279	IN	A	104.22.48.198

$ dig +noall +answer all call.ems.host
call.ems.host.		263	IN	CNAME	k8s-core-coreingr-23262e92df-35e512c9110f05c6.elb.eu-north-1.amazonaws.com.
k8s-core-coreingr-23262e92df-35e512c9110f05c6.elb.eu-north-1.amazonaws.com. 23 IN A 13.48.142.24

$ dig +noall +answer all collector.github.com
collector.github.com.	3588	IN	CNAME	glb-db52c2cf8be544.github.com.
glb-db52c2cf8be544.github.com. 48 IN	A	140.82.113.22

$ dig +noall +answer all dka575ofm4ao0.cloudfront.net
dka575ofm4ao0.cloudfront.net. 23 IN	A	13.225.20.102
dka575ofm4ao0.cloudfront.net. 23 IN	A	13.225.20.200
dka575ofm4ao0.cloudfront.net. 23 IN	A	13.225.20.12
dka575ofm4ao0.cloudfront.net. 23 IN	A	13.225.20.70

$ dig +noall +answer all economic-calendar.tradingview.com
economic-calendar.tradingview.com. 20 IN A	89.43.104.119

$ dig +noall +answer all element-hq.github.io
element-hq.github.io.	3579	IN	A	185.199.108.153
element-hq.github.io.	3579	IN	A	185.199.110.153
element-hq.github.io.	3579	IN	A	185.199.109.153
element-hq.github.io.	3579	IN	A	185.199.111.153

$ dig +noall +answer all embed-cdn.spotifycdn.com
embed-cdn.spotifycdn.com. 286	IN	CNAME	tls13.spotifycdn.map.fastly.net.
tls13.spotifycdn.map.fastly.net. 16 IN	A	199.232.150.250

$ dig +noall +answer all ems-docs.element.io
ems-docs.element.io.	280	IN	CNAME	k8s-core-coreingr-b3bd03665a-d205ac2886bcb3d3.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-b3bd03665a-d205ac2886bcb3d3.elb.eu-central-1.amazonaws.com. 40 IN A 3.72.129.101

$ dig +noall +answer all ems.element.io
ems.element.io.		280	IN	CNAME	k8s-core-coreingr-baea756bc1-7748860684099c0d.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-baea756bc1-7748860684099c0d.elb.eu-central-1.amazonaws.com. 40 IN A 3.64.237.143

$ dig +noall +answer all encore.scdn.co
encore.scdn.co.		287	IN	CNAME	encore.spotifycdn.com.
encore.spotifycdn.com.	287	IN	CNAME	default.cdn-gslb.spotify.com.
default.cdn-gslb.spotify.com. 47 IN	CNAME	common-eipb-ak.spotifycdn.com.edgesuite.net.
common-eipb-ak.spotifycdn.com.edgesuite.net. 21587 IN CNAME squadcdn.scdn.co.splitter-eip.akadns.net.
squadcdn.scdn.co.splitter-eip.akadns.net. 47 IN	CNAME i.scdn.co-noeip.akamaized.net.
i.scdn.co-noeip.akamaized.net. 347 IN	CNAME	a1520.dscc.akamai.net.
a1520.dscc.akamai.net.	7	IN	A	2.18.121.83
a1520.dscc.akamai.net.	7	IN	A	2.18.121.91

$ dig +noall +answer all ethercalc.net
ethercalc.net.		280	IN	A	172.67.129.164
ethercalc.net.		280	IN	A	104.21.1.167

$ dig +noall +answer all etherpad.integrations.element.io
etherpad.integrations.element.io. 280 IN CNAME	k8s-core-coreingr-baea756bc1-7748860684099c0d.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-baea756bc1-7748860684099c0d.elb.eu-central-1.amazonaws.com. 40 IN A 3.64.237.143

$ dig +noall +answer all fonts.googleapis.com
fonts.googleapis.com.	23	IN	A	64.233.167.95

$ dig +noall +answer all fonts.gstatic.com
fonts.gstatic.com.	245	IN	A	108.177.15.94

$ dig +noall +answer all gew1-spclient.spotify.com
gew1-spclient.spotify.com. 236	IN	CNAME	edge-web-gew1.dual-gslb.spotify.com.
edge-web-gew1.dual-gslb.spotify.com. 86	IN A	35.186.224.18

$ dig +noall +answer all github.com
github.com.		6	IN	A	140.82.121.4

$ dig +noall +answer all github.githubassets.com
github.githubassets.com. 767	IN	A	185.199.108.154
github.githubassets.com. 767	IN	A	185.199.109.154
github.githubassets.com. 767	IN	A	185.199.110.154
github.githubassets.com. 767	IN	A	185.199.111.154

$ dig +noall +answer all googleads.g.doubleclick.net
googleads.g.doubleclick.net. 224 IN	A	173.194.76.156
googleads.g.doubleclick.net. 224 IN	A	173.194.76.157
googleads.g.doubleclick.net. 224 IN	A	173.194.76.155
googleads.g.doubleclick.net. 224 IN	A	173.194.76.154

$ dig +noall +answer all i.scdn.co
i.scdn.co.		287	IN	CNAME	image-scdn.cdn-gslb.spotify.com.
image-scdn.cdn-gslb.spotify.com. 47 IN	CNAME	scdnco.spotify.map.fastly.net.
scdnco.spotify.map.fastly.net. 17 IN	A	199.232.150.248

$ dig +noall +answer all i.ytimg.com
i.ytimg.com.		132	IN	A	173.194.76.119
i.ytimg.com.		132	IN	A	142.251.168.119
i.ytimg.com.		132	IN	A	64.233.167.119
i.ytimg.com.		132	IN	A	64.233.184.119
i.ytimg.com.		132	IN	A	66.102.1.119
i.ytimg.com.		132	IN	A	74.125.71.119
i.ytimg.com.		132	IN	A	74.125.206.119
i.ytimg.com.		132	IN	A	142.250.110.119
i.ytimg.com.		132	IN	A	64.233.166.119
i.ytimg.com.		132	IN	A	108.177.15.119
i.ytimg.com.		132	IN	A	74.125.133.119

$ dig +noall +answer all id.element.io
id.element.io.		279	IN	CNAME	k8s-core-coreingr-baea756bc1-7748860684099c0d.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-baea756bc1-7748860684099c0d.elb.eu-central-1.amazonaws.com. 39 IN A 3.64.237.143

$ dig +noall +answer all img.shields.io
img.shields.io.		285	IN	A	172.64.195.2
img.shields.io.		285	IN	A	172.64.194.2

$ dig +noall +answer all integrations.element.io
integrations.element.io. 279	IN	CNAME	k8s-core-coreingr-baea756bc1-7748860684099c0d.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-baea756bc1-7748860684099c0d.elb.eu-central-1.amazonaws.com. 39 IN A 3.64.237.143

$ dig +noall +answer all integrations.ems.host
integrations.ems.host.	263	IN	CNAME	k8s-core-coreingr-b3a4d5441e-11aa9fe745bc6bd9.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-b3a4d5441e-11aa9fe745bc6bd9.elb.eu-central-1.amazonaws.com. 23 IN A 3.73.156.240

$ dig +noall +answer all jnn-pa.googleapis.com
jnn-pa.googleapis.com.	260	IN	A	142.250.110.95
jnn-pa.googleapis.com.	260	IN	A	64.233.184.95
jnn-pa.googleapis.com.	260	IN	A	74.125.71.95
jnn-pa.googleapis.com.	260	IN	A	66.102.1.95
jnn-pa.googleapis.com.	260	IN	A	64.233.167.95
jnn-pa.googleapis.com.	260	IN	A	108.177.15.95
jnn-pa.googleapis.com.	260	IN	A	142.251.168.95
jnn-pa.googleapis.com.	260	IN	A	173.194.76.95
jnn-pa.googleapis.com.	260	IN	A	64.233.166.95
jnn-pa.googleapis.com.	260	IN	A	142.251.173.95
jnn-pa.googleapis.com.	260	IN	A	74.125.133.95
jnn-pa.googleapis.com.	260	IN	A	74.125.206.95

$ dig +noall +answer all js.stripe.com
js.stripe.com.		13	IN	CNAME	dexeqbeb7giwr.cloudfront.net.
dexeqbeb7giwr.cloudfront.net. 43 IN	A	13.227.219.58
dexeqbeb7giwr.cloudfront.net. 43 IN	A	13.227.219.97
dexeqbeb7giwr.cloudfront.net. 43 IN	A	13.227.219.101
dexeqbeb7giwr.cloudfront.net. 43 IN	A	13.227.219.27

$ dig +noall +answer all livekit-jwt.call.element.io
livekit-jwt.call.element.io. 279 IN	CNAME	k8s-core-coreingr-b3bd03665a-d205ac2886bcb3d3.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-b3bd03665a-d205ac2886bcb3d3.elb.eu-central-1.amazonaws.com. 39 IN A 3.72.129.101

$ dig +noall +answer all m.stripe.com
m.stripe.com.		48	IN	A	44.238.119.32
m.stripe.com.		48	IN	A	35.155.200.145
m.stripe.com.		48	IN	A	44.225.16.159
m.stripe.com.		48	IN	A	34.215.148.109
m.stripe.com.		48	IN	A	44.241.18.241
m.stripe.com.		48	IN	A	34.213.37.126
m.stripe.com.		48	IN	A	34.208.13.71
m.stripe.com.		48	IN	A	34.214.18.208

$ dig +noall +answer all m.stripe.network
m.stripe.network.	41	IN	CNAME	stripecdn.map.fastly.net.
stripecdn.map.fastly.net. 11	IN	A	151.101.128.176
stripecdn.map.fastly.net. 11	IN	A	151.101.64.176
stripecdn.map.fastly.net. 11	IN	A	151.101.192.176
stripecdn.map.fastly.net. 11	IN	A	151.101.0.176

$ dig +noall +answer all matomo.openstreetmap.org
matomo.openstreetmap.org. 107	IN	A	184.104.226.110

$ dig +noall +answer all matomo.riot.im
matomo.riot.im.		280	IN	A	104.26.5.138
matomo.riot.im.		280	IN	A	104.26.4.138
matomo.riot.im.		280	IN	A	172.67.70.226

$ dig +noall +answer all matrix-org.github.io
matrix-org.github.io.	3600	IN	A	185.199.110.153
matrix-org.github.io.	3600	IN	A	185.199.108.153
matrix-org.github.io.	3600	IN	A	185.199.109.153
matrix-org.github.io.	3600	IN	A	185.199.111.153

$ dig +noall +answer all matrix.org
matrix.org.		215	IN	A	172.67.19.90
matrix.org.		215	IN	A	104.20.201.37
matrix.org.		215	IN	A	104.20.200.37

$ dig +noall +answer all meet.element.io
meet.element.io.	580	IN	CNAME	k8s-global-88e07f8a34-1957068544.eu-central-1.elb.amazonaws.com.
k8s-global-88e07f8a34-1957068544.eu-central-1.elb.amazonaws.com. 40 IN A 54.93.211.59
k8s-global-88e07f8a34-1957068544.eu-central-1.elb.amazonaws.com. 40 IN A 3.124.80.226
k8s-global-88e07f8a34-1957068544.eu-central-1.elb.amazonaws.com. 40 IN A 3.121.134.149

$ dig +noall +answer all modular.im
modular.im.		280	IN	A	104.26.15.131
modular.im.		280	IN	A	104.26.14.131
modular.im.		280	IN	A	172.67.68.192

$ dig +noall +answer all open.spotify.com
open.spotify.com.	297	IN	CNAME	open.spotify.com.edgesuite.net.
open.spotify.com.edgesuite.net.	21597 IN CNAME	a1676.dscb.akamai.net.
a1676.dscb.akamai.net.	17	IN	A	104.97.14.88
a1676.dscb.akamai.net.	17	IN	A	104.97.14.106

$ dig +noall +answer all p.scdn.co
p.scdn.co.		266	IN	CNAME	scdnco.spotify.map.fastly.net.
scdnco.spotify.map.fastly.net. 30 IN	A	199.232.150.248

$ dig +noall +answer all pay.stripe.com
pay.stripe.com.		30	IN	A	198.202.176.141

$ dig +noall +answer all polyfill.io
polyfill.io.		201	IN	A	151.101.1.26
polyfill.io.		201	IN	A	151.101.129.26
polyfill.io.		201	IN	A	151.101.65.26
polyfill.io.		201	IN	A	151.101.193.26

$ dig +noall +answer all posthog-element-call.element.io
posthog-element-call.element.io. 280 IN	CNAME	k8s-core-coreingr-b3bd03665a-d205ac2886bcb3d3.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-b3bd03665a-d205ac2886bcb3d3.elb.eu-central-1.amazonaws.com. 40 IN A 3.72.129.101

$ dig +noall +answer all pushstream.tradingview.com
pushstream.tradingview.com. 56	IN	CNAME	pushstream-eu.tradingview.com.
pushstream-eu.tradingview.com. 56 IN	A	93.123.102.208

$ dig +noall +answer all riot.im
riot.im.		104	IN	A	172.67.70.226
riot.im.		104	IN	A	104.26.4.138
riot.im.		104	IN	A	104.26.5.138

$ dig +noall +answer all rr5---sn-aigzrn7e.googlevideo.com
rr5---sn-aigzrn7e.googlevideo.com. 1660	IN CNAME rr5.sn-aigzrn7e.googlevideo.com.
rr5.sn-aigzrn7e.googlevideo.com. 1660 IN A	173.194.5.42

$ dig +noall +answer all s.tradingview.com
s.tradingview.com.	24	IN	A	52.222.139.19
s.tradingview.com.	24	IN	A	52.222.139.111
s.tradingview.com.	24	IN	A	52.222.139.34
s.tradingview.com.	24	IN	A	52.222.139.36

$ dig +noall +answer all s3-symbol-logo.tradingview.com
s3-symbol-logo.tradingview.com.	193 IN	CNAME	s3-symbol-logo.b-cdn.net.
s3-symbol-logo.b-cdn.net. 35	IN	A	207.211.214.145

$ dig +noall +answer all s3.tradingview.com
s3.tradingview.com.	39	IN	A	52.222.139.42
s3.tradingview.com.	39	IN	A	52.222.139.40
s3.tradingview.com.	39	IN	A	52.222.139.55
s3.tradingview.com.	39	IN	A	52.222.139.94

$ dig +noall +answer all scalar.vector.im
scalar.vector.im.	280	IN	CNAME	k8s-core-coreingr-baea756bc1-7748860684099c0d.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-baea756bc1-7748860684099c0d.elb.eu-central-1.amazonaws.com. 40 IN A 3.64.237.143

$ dig +noall +answer all sentry.matrix.org
sentry.matrix.org.	580	IN	CNAME	k8s-global-88e07f8a34-1957068544.eu-central-1.elb.amazonaws.com.
k8s-global-88e07f8a34-1957068544.eu-central-1.elb.amazonaws.com. 40 IN A 3.124.80.226
k8s-global-88e07f8a34-1957068544.eu-central-1.elb.amazonaws.com. 40 IN A 3.121.134.149
k8s-global-88e07f8a34-1957068544.eu-central-1.elb.amazonaws.com. 40 IN A 54.93.211.59

$ dig +noall +answer all sentry.tools.element.io
sentry.tools.element.io. 165	IN	CNAME	k8s-core-coreingr-b3bd03665a-d205ac2886bcb3d3.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-b3bd03665a-d205ac2886bcb3d3.elb.eu-central-1.amazonaws.com. 25 IN A 3.72.129.101

$ dig +noall +answer all sfu.call.element.io
sfu.call.element.io.	280	IN	CNAME	k8s-core-coreingr-b3bd03665a-d205ac2886bcb3d3.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-b3bd03665a-d205ac2886bcb3d3.elb.eu-central-1.amazonaws.com. 40 IN A 3.72.129.101

$ dig +noall +answer all sonarcloud.io
sonarcloud.io.		29	IN	A	54.192.137.29
sonarcloud.io.		29	IN	A	54.192.137.113
sonarcloud.io.		29	IN	A	54.192.137.14
sonarcloud.io.		29	IN	A	54.192.137.16

$ dig +noall +answer all spclient.wg.spotify.com
spclient.wg.spotify.com. 298	IN	CNAME	edge-web.dual-gslb.spotify.com.
edge-web.dual-gslb.spotify.com.	148 IN	A	35.186.224.25

$ dig +noall +answer all static.doubleclick.net
static.doubleclick.net.	250	IN	A	173.194.76.149
static.doubleclick.net.	250	IN	A	173.194.76.148

$ dig +noall +answer all static.tradingview.com
static.tradingview.com.	277	IN	CNAME	d34vo3dglcgqwn.cloudfront.net.
d34vo3dglcgqwn.cloudfront.net. 37 IN	A	65.9.86.55
d34vo3dglcgqwn.cloudfront.net. 37 IN	A	65.9.86.43
d34vo3dglcgqwn.cloudfront.net. 37 IN	A	65.9.86.54
d34vo3dglcgqwn.cloudfront.net. 37 IN	A	65.9.86.53

$ dig +noall +answer all status.element.io
status.element.io.	280	IN	CNAME	lkh3j7gmv7x4.stspg-customer.com.
lkh3j7gmv7x4.stspg-customer.com. 40 IN	CNAME	status-element-io-ba0b601b-1586-41ca-9c10-db2237fdc2ed.saas.atlassian.com.
status-element-io-ba0b601b-1586-41ca-9c10-db2237fdc2ed.saas.atlassian.com. 40 IN A 18.239.83.57
status-element-io-ba0b601b-1586-41ca-9c10-db2237fdc2ed.saas.atlassian.com. 40 IN A 18.239.83.106
status-element-io-ba0b601b-1586-41ca-9c10-db2237fdc2ed.saas.atlassian.com. 40 IN A 18.239.83.90
status-element-io-ba0b601b-1586-41ca-9c10-db2237fdc2ed.saas.atlassian.com. 40 IN A 18.239.83.101

$ dig +noall +answer all tile.openstreetmap.org
tile.openstreetmap.org.	285	IN	CNAME	dualstack.n.sni.global.fastly.net.
dualstack.n.sni.global.fastly.net. 15 IN A	151.101.1.91
dualstack.n.sni.global.fastly.net. 15 IN A	151.101.129.91
dualstack.n.sni.global.fastly.net. 15 IN A	151.101.65.91
dualstack.n.sni.global.fastly.net. 15 IN A	151.101.193.91

$ dig +noall +answer all user-images.githubusercontent.com
user-images.githubusercontent.com. 1389	IN A	185.199.109.133
user-images.githubusercontent.com. 1389	IN A	185.199.111.133
user-images.githubusercontent.com. 1389	IN A	185.199.108.133
user-images.githubusercontent.com. 1389	IN A	185.199.110.133

$ dig +noall +answer all vector.im
vector.im.		31	IN	A	104.21.28.52
vector.im.		31	IN	A	172.67.144.66

$ dig +noall +answer all web-docs.element.dev
web-docs.element.dev.	300	IN	CNAME	vector-im.github.io.
vector-im.github.io.	3600	IN	A	185.199.110.153
vector-im.github.io.	3600	IN	A	185.199.111.153
vector-im.github.io.	3600	IN	A	185.199.109.153
vector-im.github.io.	3600	IN	A	185.199.108.153

$ dig +noall +answer all web-sdk-assets.spotifycdn.com
web-sdk-assets.spotifycdn.com. 268 IN	CNAME	tls13.spotifycdn.map.fastly.net.
tls13.spotifycdn.map.fastly.net. 24 IN	A	199.232.150.250

$ dig +noall +answer all widgetdata.tradingview.com
widgetdata.tradingview.com. 60	IN	CNAME	widgetdata-eu.tradingview.com.
widgetdata-eu.tradingview.com. 60 IN	A	92.223.127.141

$ dig +noall +answer all www.google.com
www.google.com.		271	IN	A	66.102.1.106
www.google.com.		271	IN	A	66.102.1.147
www.google.com.		271	IN	A	66.102.1.99
www.google.com.		271	IN	A	66.102.1.103
www.google.com.		271	IN	A	66.102.1.105
www.google.com.		271	IN	A	66.102.1.104

$ dig +noall +answer all www.gravatar.com
www.gravatar.com.	288	IN	A	192.0.73.2

$ dig +noall +answer all www.gstatic.com
www.gstatic.com.	24	IN	A	108.177.15.94

$ dig +noall +answer all www.openstreetmap.org
www.openstreetmap.org.	94	IN	A	184.104.179.139
www.openstreetmap.org.	94	IN	A	184.104.179.140
www.openstreetmap.org.	94	IN	A	184.104.179.141

$ dig +noall +answer all www.recaptcha.net
www.recaptcha.net.	272	IN	A	74.125.206.94

$ dig +noall +answer all www.tradingview-widget.com
www.tradingview-widget.com. 60	IN	A	52.222.139.32
www.tradingview-widget.com. 60	IN	A	52.222.139.106
www.tradingview-widget.com. 60	IN	A	52.222.139.108
www.tradingview-widget.com. 60	IN	A	52.222.139.128

$ dig +noall +answer all www.youtube.com
www.youtube.com.	252	IN	CNAME	youtube-ui.l.google.com.
youtube-ui.l.google.com. 252	IN	A	74.125.206.190
youtube-ui.l.google.com. 252	IN	A	64.233.166.136
youtube-ui.l.google.com. 252	IN	A	74.125.71.93
youtube-ui.l.google.com. 252	IN	A	74.125.206.136
youtube-ui.l.google.com. 252	IN	A	64.233.167.91
youtube-ui.l.google.com. 252	IN	A	74.125.71.91
youtube-ui.l.google.com. 252	IN	A	64.233.166.190
youtube-ui.l.google.com. 252	IN	A	64.233.166.93
youtube-ui.l.google.com. 252	IN	A	64.233.167.136
youtube-ui.l.google.com. 252	IN	A	64.233.167.190
youtube-ui.l.google.com. 252	IN	A	74.125.71.190
youtube-ui.l.google.com. 252	IN	A	74.125.71.136
youtube-ui.l.google.com. 252	IN	A	74.125.206.91
youtube-ui.l.google.com. 252	IN	A	64.233.166.91
youtube-ui.l.google.com. 252	IN	A	74.125.206.93
youtube-ui.l.google.com. 252	IN	A	64.233.167.93

$ dig +noall +answer all youtube.com
youtube.com.		198	IN	A	74.125.133.136
youtube.com.		198	IN	A	74.125.133.93
youtube.com.		198	IN	A	74.125.133.190
youtube.com.		198	IN	A	74.125.133.91

$ dig +noall +answer all yt3.ggpht.com
yt3.ggpht.com.		253	IN	CNAME	photos-ugc.l.googleusercontent.com.
photos-ugc.l.googleusercontent.com. 253	IN A	64.233.166.132
```

</details>

The values for your base domains will depend on your region and custom domain, here are the values for our Element.io EMS server with the EMS domain `element.ems.host`, Custom homeserver domain `element.io`, and custom Element Web domain `chat.element.io`:

```bash
$ dig +noall +answer all chat.element.io
chat.element.io.	300	IN	A	104.22.49.198
chat.element.io.	300	IN	A	172.67.12.112
chat.element.io.	300	IN	A	104.22.48.198

$ dig +noall +answer all element.element.io
element.element.io.	300	IN	CNAME	k8s-core-coreingr-b3a4d5441e-11aa9fe745bc6bd9.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-b3a4d5441e-11aa9fe745bc6bd9.elb.eu-central-1.amazonaws.com. 60 IN A 3.73.156.240

$ dig +noall +answer all element.ems.host
element.ems.host.	242	IN	CNAME	k8s-core-coreingr-b3a4d5441e-11aa9fe745bc6bd9.elb.eu-central-1.amazonaws.com.
k8s-core-coreingr-b3a4d5441e-11aa9fe745bc6bd9.elb.eu-central-1.amazonaws.com. 60 IN A 3.73.156.240

$ dig +noall +answer all element.io
element.io.		300	IN	A	104.22.48.198
element.io.		300	IN	A	104.22.49.198
element.io.		300	IN	A	172.67.12.112
```

Your `.element.io` and `.ems.host` IP will be in AWS' IP ranges in your hosting region (Frankfurt/eu-central-1, Stockholm/eu-north-1, London/eu-west-2, or Ohio/us-east-2).

# EMS Server With Custom Domain

For this guide, I will be using the domain
<a href="https://element.io/" target="_blank" rel="noopener noreferrer">element.io</a>. I will set up EMS so that the
Matrix usernames becomes `@someone:element.io`, and the Element client will be at
<a href="https://chat.element.io/" target="_blank" rel="noopener noreferrer">https://chat.element.io/</a>

From the guide at [Get Your Own EMS Server](get-your-own-ems-server), I will be replacing the EMS hostname
`ems-demo-staging.ems.host` with `element.ems.host`

Custom domains are only supported with Element Enterprise Cloud plans.

## Prerequisites

- You own and control the domain you want to use
- If you do not have a website on the domain you want to use with your EMS server:
  - You can create a CNAME DNS record for the domain. Some providers call this ALIAS or CNAME Flattening when used on
    the root of the domain (domain root = `yourdomain.com`, not `something.yourdomain.com`)
- If you have a website on the domain you want to use with your EMS server:
  - Your website has HTTPS enabled using a valid certificate issued by a commonly recognized provider. For example,
    Comodo or LetsEncrypt.
  - You can serve plain-text JSON files at these exact paths
    - `https://yourdomain.com/.well-known/matrix/client`
    - `https://yourdomain.com/.well-known/matrix/server`
    - Note that these files do not and cannot have a file extension
  - You can add the header `Access-Control-Allow-Origin: *` to the client file on the web server

## See also

- [FAQ: Can I use a subdomain instead of the root domain with my EMS server?](https://ems-docs.element.io/link/6#bkmrk-can-i-use-a-subdomai)
- [FAQ: Can I use EMS-hosted well-knowns with the root of my domain?](https://ems-docs.element.io/link/6#bkmrk-can-i-use-ems-hosted)

## Setup

Some providers for DNS and website hosting providers need special configuration. See
[Provider specific instructions](#bkmrk-provider-specific-in) at the bottom for known solutions.

1. Follow steps 1 - 10 from [Get Your Own EMS Server](get-your-own-ems-server)

2. On step 10 from [Get Your Own EMS Server](get-your-own-ems-server), turn ON `Custom DNS`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702383058866-07-59-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702383058866-07-59-am.png)

3. In the `Custom Homeserver domain` field, enter `element.io`  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-08/scaled-1680-/image-1659627256442-57-31-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-08/image-1659627256442-57-31-pm.png)

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 add the header `Content-Type application/json` to both files.

    1. `https://element.io/.well-known/matrix/server`  
    [![](https://ems-docs.element.io/uploads/images/gallery/2022-08/scaled-1680-/image-1659627292963-32-20-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-08/image-1659627292963-32-20-pm.png)

        ```json
        {
            "m.server": "element.ems.host:443"
        }
        ```

    2. `https://element.io/.well-known/matrix/client`  
    [![](https://ems-docs.element.io/uploads/images/gallery/2022-08/scaled-1680-/image-1659627321046-32-38-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-08/image-1659627321046-32-38-pm.png)  
    You need to enable the CORS header `Access-Control-Allow-Origin: *` on the web server for this file. See
    <a href="https://enable-cors.org/" target="_blank" rel="noopener noreferrer">https://enable-cors.org/</a> for
    instructions on how to do this. If you are using redicrects, the CORS headers must be set on all steps/hops.

        ```json
        {
            "m.homeserver": {
                "base_url": "https://element.ems.host"
            },
            "m.identity_server": {
                "base_url": "https://vector.im"
            },
            "org.matrix.msc4143.rtc_foci": [
                {
                    "type": "livekit",
                    "livekit_service_url": "https://jwt.call.element.io"
                }
            ]
        }
        ```

    <details id="bkmrk-nginx-well-known">
        <summary>Optional Nginx-specific configuration</summary>

    If your web server is running Nginx, you can set this in the Nginx config instead of creating actual files.

    ```plaintext
    server {
        server_name element.io

        ...

        # Matrix well-known files
        location /.well-known/matrix/client {
            return 200 '{"m.homeserver":{"base_url":"https://element.ems.host"},"m.identity_server":{"base_url":"https://vector.im"},"org.matrix.msc4143.rtc_foci":[{"type":"livekit","livekit_service_url":"https://jwt.call.element.io"}]}';
            add_header Content-Type application/json;
            add_header 'Access-Control-Allow-Origin' '*';
        }
        location /.well-known/matrix/server {
            return 200 '{"m.server": "element.ems.host:443"}';
            add_header Content-Type application/json;
        }
    }
    ```

    </details>

5. Click `Check again` to verify that your `.well-known` files are configured correctly  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-08/scaled-1680-/image-1659627418181-36-42-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-08/image-1659627418181-36-42-pm.png)

    <details>
        <summary>You can also verify your `.well-known` files from the command line</summary>

    Note the lines `access-control-allow-origin: *` and `content-type: application/json`

    1. On Mac or Linux, using the `terminal`  

        ```bash
        $ curl -i https://element.io/.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=.element.io; 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://element.ems.host"
            },
            "m.identity_server": {
                "base_url": "https://vector.im"
            },
            "org.matrix.msc4143.rtc_foci": [
                {
                    "type": "livekit",
                    "livekit_service_url": "https://jwt.call.element.io"
                }
            ]
        }

        $ curl -i https://element.io/.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=.element.io; 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": "element.ems.host:443"
        }  
        ```

    2. On Windows, using `PowerShell`  

        ```powershell
        PS C:\Users\twilight> Invoke-WebRequest -Uri https://element.io/.well-known/matrix/client


        StatusCode        : 200
        StatusDescription : OK
        Content           : {
                                "m.homeserver": {
                                    "base_url": "https://element.ems.host"
                                },
                                "m.identity_server": {
                                    "base_url": "https://vector.im"
                                },
                                "org.matrix.msc4143.rtc_foci": [
                                    {
                                        "type": "livekit",
                                        "livekit_service_url": "https://jwt.call.element.io"
                                    }
                                ]
                            }
        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://element.io/.well-known/matrix/server


        StatusCode        : 200
        StatusDescription : OK
        Content           : {
                                "m.server": "element.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
        ```

    </details>

6. You can continue without the `.well-known` files in place, but your server will have limited functionality until this is fixed

7. In the `Custom Client domain` field, enter `chat.element.io`. This can be any domain, except the same as `Custom Homeserver domain`  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-08/scaled-1680-/image-1659627867813-44-13-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-08/image-1659627867813-44-13-pm.png)

8. Create a CNAME DNS record with your DNS provider according to the instructions given  
`chat.element.io. CNAME element.element.io.`  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-08/scaled-1680-/image-1659627663519-40-24-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-08/image-1659627663519-40-24-pm.png)

9. 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.  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-08/scaled-1680-/image-1659628294089-50-07-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-08/image-1659628294089-50-07-pm.png)

10. Back on EMS, click `Check again`. Note that sometimes it might take a while for your new DNS record to propagate.
You can continue, but functionality will be limited. Check back with the Hosts tab on
<a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a>
and click `Rebuild Host` once the DNS record is in place.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702383120826-56-18-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702383120826-56-18-am.png)

    <details>
        <summary>You can also verify the CNAME DNS record using the command line</summary>

    1. On Mac or Linux, using the `terminal`  

        ```bash
        $ dig chat.element.io CNAME

        ; <<>> DiG 9.10.6 <<>> chat.element.io 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.element.io.   IN CNAME

        ;; ANSWER SECTION:
        chat.element.io. 299 IN CNAME element.element.io.

        ;; Query time: 32 msec
        ;; SERVER: 1.1.1.1#53(1.1.1.1)
        ;; WHEN: Fri Jul 31 10:21:56 BST 2020
        ;; MSG SIZE  rcvd: 91
        ```

    2. On Windows, using `PowerShell`  

        ```powershell
        PS C:\Users\twilight> Resolve-DnsName -Name chat.element.io -Type CNAME

        Name                           Type   TTL   Section    NameHost
        ----                           ----   ---   -------    --------
        chat.element.io                 CNAME  299   Answer     element.element.io
        ```

    </details>

11. Continue from step 11 on [Get Your Own EMS Server](get-your-own-ems-server)

## Provider-specific instructions

### GitHub Pages

If you are hosting your website with GitHub Pages, add this to the Jekyll config file `_config.yml`

```yaml
include:
  - .well-known
```

### Microsoft Azure

If you are using Microsoft 365 / Azure to manage your domain or the rest of your infrastructure, please use the following instructions to host the `.well-known/matrix` URI (RFC 8615).

In this section, we will configure Azure to serve `https://yourdomain.com/.well-known/matrix/client` and `https://yourdomain.com/.well-known/matrix/client`.

The summary of steps is as follows:
- prepare json files
- create a Storage account then enable a Static website
- upload the json files to .well-known/matrix/ in the `$web` container
- create a CDN and an endpoint for this container
- create a `CNAME` DNS entry for your custom domain, pointing to your CDN endpoint
- associate your custom domain to your CDN endpoint

#### Prepare client and server .well-known files locally
On your computer, prepare two plain text files called `client` and `server` (again, notice the lack of file extension such as ".txt") which contain the following:
##### client
```json
{
    "m.homeserver": {
        "base_url": "https://your-tenant.ems.host"
    },
    "m.identity_server": {
        "base_url": "https://vector.im"
    },
    "org.matrix.msc4143.rtc_foci": [
        {
            "type": "livekit",
            "livekit_service_url": "https://jwt.call.your-tenant.io"
        }
    ]
}
```

Remember to replace `your-tenant` by the name of your EMS tenant.

##### server
```json
{
    "m.homeserver": {
        "base_url": "https://your-tenant.ems.host:443"
    }
}
```

Remember to replace `your-tenant` by the name of your EMS tenant.

You will be uploading these shortly.

#### Create a Storage account and Static website
##### Storage account
In the Azure Portal, [create a Storage account](https://portal.azure.com/#create/Microsoft.StorageAccount-ARM).

[![Screenshot 2023-11-10 at 14-20-46 Microsoft Azure.png](https://ems-docs.element.io/uploads/images/gallery/2023-11/scaled-1680-/screenshot-2023-11-10-at-14-20-46-microsoft-azure.png)](https://ems-docs.element.io/uploads/images/gallery/2023-11/screenshot-2023-11-10-at-14-20-46-microsoft-azure.png)

The name needs to be unique to Azure. `yourdomainwellknown` is an option that should work well in most scenarios.

Performarce can be left to Standard.  
Redundancy should be set to Geo-redundant storage (GRS) as the .well-known URI will be a core part of your EMS deployment.  
You can leave all other options to their default or change them to fit your specific deployment scenario.

Finally, click create.

##### Static website
Once the Storage account is created, you will need to create a Static website in this Storage account.  
In the Storage account overview, choose "Static website", in the Data management section.

[![Screenshot 2023-11-10 at 15-15-32 Microsoft Azure.png](https://ems-docs.element.io/uploads/images/gallery/2023-11/scaled-1680-/H3rscreenshot-2023-11-10-at-15-15-32-microsoft-azure.png)](https://ems-docs.element.io/uploads/images/gallery/2023-11/H3rscreenshot-2023-11-10-at-15-15-32-microsoft-azure.png)

You do not need to provide a specific Index document name or Error document path.

Enabling the Static website in your Storage account will automatically create a `$web` storage container to which you can upload the json text files which will be served at the .well-known URI.

Go to "Containers", in the "Data storage" section, to upload the `client` and `server` files you prepered earlier.

Click on the `$web` container, then chose "Upload", which will open a panel on the right.

When uploading the `client` and `server` files, make sure to open the "advanced" part of the upload panel and choose to upload to a specific folder: `.well-known/matrix/`

[![Azure: Storage account: upload .well-known/matrix/](https://ems-docs.element.io/uploads/images/gallery/2023-11/scaled-1680-/screenshot-2023-11-10-at-15-47-44-microsoft-azure.png)](https://ems-docs.element.io/uploads/images/gallery/2023-11/screenshot-2023-11-10-at-15-47-44-microsoft-azure.png)

#### Create a CDN, `CNAME` DNS entry for your custom domain and Custom domain name for the CDN endpoint
Creating a CDN is needed because Azure does not allow serving HTTPS over a custom domain using only a Storage account Static website. To do so, a CDN is necessary.

##### Create a CDN endpoint
Go back to your Storage account's main view and choose "Front Door and CDN" in the Security + Networking section, to create a CDN endpoint.

[![Azure: Storage account: CDN: endpoint](https://ems-docs.element.io/uploads/images/gallery/2023-11/scaled-1680-/screenshot-2023-11-10-at-15-57-51-microsoft-azure.png)](https://ems-docs.element.io/uploads/images/gallery/2023-11/screenshot-2023-11-10-at-15-57-51-microsoft-azure.png)

Service type: Azure CDN is sufficient, the more advanced features of Azure Front Door are not necessary here.

If you need to create a new profile, you may call the Profile name and Endpoint name as you wish.  
For consistency, it is suggested to call them `yourdomainwellknown` as previously.

For Origin host name, pick your Static website.

For Query string caching behaviour, pick Ignore Query String, although this setting is not important in our context.

Once your endpoint is deployed, go to the resource, then go to your endpoint's further settings  by clicking on it. Make note of its hostname (`rfc8615demo.azureedge.net` in our example) as you will need it shortly.

[![Azure: CDN: overview](https://ems-docs.element.io/uploads/images/gallery/2023-11/scaled-1680-/screenshot-2023-11-10-at-16-09-22-microsoft-azure.png)](https://ems-docs.element.io/uploads/images/gallery/2023-11/screenshot-2023-11-10-at-16-09-22-microsoft-azure.png)

##### Create `CNAME` DNS entry for your custom domain
You will now create a DNS entry for your custom domain, a `CNAME` pointing to your Azure CDN endpoint's hostname. How to do so exactly will depend on who hosts your DNS servers. The specifics of this are beyond this documentation, but the following general information should be sufficient.

In your DNS provider's admin panel, add a DNS entry with the following details:
- Type: `CNAME`
- Domain: your custom domain, such as `yourdomain.com`
- Target: your Azure CDN Endpoint's hostname, such as `rfc8615demo.azureedge.net` in our example

Once created, this DNS entry may take some time to propagate, but in most cases will be picked up quickly by Azure, as needed in the next step.

##### Associate your custom domain with your CDN Endpoint
In the endpoint's settings, choose "+ custom domain" to start adding your custom domain. A panel will open on the right.

Enter your custom domain: `yourdomain.com` and finally, click add.

If the `CNAME` entry can be seen by Azure, after a few minutes your custom domain should be associated with your CDN Endpoint.

#### Final result
`https://yourdomain.com/.well-known/matrix/client` and `https://yourdomain.com/.well-known/matrix/server` are now served over HTTPS by Azure.

You should now have the following resources in your Azure account:
- Storage account
- Front Door and CDN Profile
- Endpoint


#### Resources
- https://learn.microsoft.com/en-us/azure/cdn/cdn-create-a-storage-account-with-cdn
- https://learn.microsoft.com/en-us/azure/cdn/cdn-storage-custom-domain-https

# How to Get an EMS Server

1. Go to <a href="https://ems.element.io/user/hosting#/hosts" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting#/hosts</a> and click the “Register” link below the sign-in button.
[![step2-click-register-link.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step2-click-register-link.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step2-click-register-link.jpg)

1. Fill in your details and click the Register button. <i>Note: Your password must be at least 12 characters long.</i>
[![step3-fill-in-your-details-updated.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step3-fill-in-your-details-updated.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step3-fill-in-your-details-updated.jpg)

1. Look in your inbox for your verification email. (If it doesn’t appear after a couple of minutes - check your spam!) Click the link in the email to verify your email address.
[![step4-verification-email.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step4-verification-email.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step4-verification-email.jpg)

1. You will be automatically redirected to the EMS Hosting site. Before proceeding any further, agree to our terms and conditions.
[![step5-agree-to-terms.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step5-agree-to-terms.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step5-agree-to-terms.jpg)

1. Click “Set up a host now” to start setting up your first EMS server
[![step6-set-up-a-host.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step6-set-up-a-host.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step6-set-up-a-host.jpg)

1. Choose your host size and click Continue.
[![step7-choose-host-size.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step7-choose-host-size.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step7-choose-host-size.jpg)

1. Choose a hostname and click “Check” to check availability.
[![step8-choose-host-name-updated.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step8-choose-host-name-updated.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step8-choose-host-name-updated.jpg)

1. Configure your new host.
[![step9-setup-host-updated.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step9-setup-host-updated.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step9-setup-host-updated.jpg)

1. Set up your payment card.
[![step10-setup-payment.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step10-setup-payment.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step10-setup-payment.jpg)

1. Check your payment information and click Purchase to build the host.
[![step11-purchase.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step11-purchase.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step11-purchase.jpg)

1. Sit tight for a few minutes while your server is being built
[![step12-building2.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step12-building2.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step12-building2.jpg)

1. Once your host is ready, click Manage hosts to configure additional settings and add users.
[![step13-upandrunning-updated.jpg](https://ems-docs.element.io/uploads/images/gallery/2025-06/scaled-1680-/step13-upandrunning-updated.jpg)](https://ems-docs.element.io/uploads/images/gallery/2025-06/step13-upandrunning-updated.jpg)

# Migrate From EMS to Self-Hosted

For support on Synapse or matrix-media-repo, ask in the Matrix rooms <a href="https://matrix.to/#/#synapse:matrix.org" target="_blank" rel="noopener noreferrer">#synapse:matrix.org</a> and <a href="https://matrix.to/#/#mediarepo:t2bot.io" target="_blank" rel="noopener noreferrer">#mediarepo:t2bot.io</a>. For support on bridges, see the [bridge documentation](#bkmrk-bridges) for each bridge's support channel.

See also [this](https://matrix.org/blog/2024/01/migrating-from-ems-to-selfhosted-matrix/) excellent blog post by Robin Riley at The Matrix.org Foundation.

## Important

- It is impossible to change the domain of any Matrix server. Therefore if your EMS server is not using Custom DNS (i.e. your Matrix IDs are `@someone:hostname.ems.host`), unfortunately it is not possible to import your export to your own or another environment.
	- You can run an export with this domain in a local environment if you set up your own DNS and self-signed certificates. But you will not be able to federate with the public Matrix federation.
- Do not cancel your EMS server until you have downloaded your export and verified its content. Canceling your server will erase your data.
- You will experience some downtime as your server will be stopped while the export is running. The EMS export tool will estimate the actual downtime when initiated.
- Ensure all your users have key backup configured and working before starting the export and migration. All clients need to log out and in again after the migration. See the [Cross Signing](https://ems-docs.element.io/books/element-support/chapter/cross-signing) section for more information about key backup.
- It is impossible to read encrypted messages or media from the export. Encrypted data in Matrix can only be decrypted by the user in their client when they have the required decryption keys.

## Export data

1. Go to <https://ems.element.io/user/hosting#/exports>
1. Select the server you want to export from in the drop-down box, then click `Create export`
1. Wait for the export of your config, database, and media to complete
1. Once all exports have completed, download all files provided

## Import process

For all components, you must install the same version as your EMS server is running. Version information is provided in the `hostname-config.md` file. If a newer version is available, once the import is completed and verified, follow the official upgrade documentation for each component to upgrade.

All required configuration values are provided in the `hostname-config.md` file.

1. Following official documentation, install and configure
    1. <a href="https://www.postgresql.org/" target="_blank" rel="noopener noreferrer">PostgreSQL</a>. Refer to the <a href="https://element-hq.github.io/synapse/latest/postgres.html" target="_blank" rel="noopener noreferrer">Synapse PostgreSQL documentation</a> for database setup
    1. <a href="https://element-hq.github.io/synapse/latest/" target="_blank" rel="noopener noreferrer">Synapse</a>
    1. Optional (see media step below): <a href="https://docs.t2bot.io/matrix-media-repo" target="_blank" rel="noopener noreferrer">matrix-media-repo</a>
1. When generating your Synapse configuration file, you MUST use the same domain as your EMS server
1. Do not start Synapse yet
1. In the Synapse config file (usually `homeserver.yaml`), set:
    1. <a href="https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#password_config" target="_blank" rel="noopener noreferrer">pepper</a>. If you do not do this, you have to reset all passwords
    1. Signing key. This is stored in a file. See <a href="https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#signing_key_path" target="_blank" rel="noopener noreferrer">this</a> config file option for path. Alternatively, add the public key for your EMS hosted server to `old_signing_keys`. If your EMS server is still running, you can find your public signing key at <https://yourHostname.ems.host/_matrix/key/v2/server>
    1. <a href="https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#macaroon_secret_key" target="_blank" rel="noopener noreferrer">macaroon_secret_key</a>
1. Import the Synapse database
    1. Create a new database per the <a href="https://element-hq.github.io/synapse/latest/postgres.html#set-up-database" target="_blank" rel="noopener noreferrer">Synapse PostgreSQL documentation</a>
    1. Or, if your Synapse database is not empty, empty it  
        **WARNING - THIS WILL IMMEDIATELY AND IRRECOVERABLY DELETE DATA, PLEASE TAKE CARE. WE ACCEPT NO RESPONSIBILITY IF YOU DELETE THE WRONG DATABASE OR DATA**  
        Connect to the database with `psql`, then run the following queries:
        ```sql
        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;
        DROP sequence account_data_sequence;
        DROP sequence application_services_txn_id_seq;
        DROP sequence device_inbox_sequence;
        DROP sequence device_lists_sequence;
        DROP sequence e2e_cross_signing_keys_sequence;
        DROP sequence event_auth_chain_id;
        DROP sequence events_backfill_stream_seq;
        DROP sequence events_stream_seq;
        DROP sequence presence_stream_sequence;
        DROP sequence push_rules_stream_sequence;
        DROP sequence pushers_sequence;
        DROP sequence receipts_sequence;
        DROP sequence un_partial_stated_event_stream_sequence;
        DROP sequence un_partial_stated_room_stream_sequence;
        ```
        Enter the command `\d` and make sure no tables or sequences remain.  
        Disconnect from the database
    1. Extract the database dump
        ```
        unzip emsHostname-synapse-database.zip
        ```
    1. Import the database dump
        ```bash
        pg_restore \
            --username USERNAME \
            --host HOSTNAME \
            --dbname DATABASE_NAME \
            --no-owner \
            /path/to/id-emsHostname-synapse-database.dir/
        ```
    1. Verify that sequence was set correctly. Connect to the database and run the query
        ```sql
        SELECT * FROM state_group_id_seq;
        ```
        `last_value` should be greater than 1
1. Import media into matrix-media-repo according to documentation <a href="https://github.com/turt2live/matrix-media-repo/blob/master/docs/admin.md#exportingimporting-data" target="_blank" rel="noopener noreferrer">here</a> or import media into Synapses built-in media repository using the `import_to_synapse` executable available from the latest [matrix-media-repo release](https://github.com/t2bot/matrix-media-repo/releases)
1. Start Synapse and ensure everything is working as expected
1. Optionally, install <a href="https://web-docs.element.dev/Element%20Web/index.html" target="_blank" rel="noopener noreferrer">Element Web</a> or use another <a href="https://matrix.org/ecosystem/clients/" target="_blank" rel="noopener noreferrer">Matrix client</a>
1. <span id="bkmrk-bridges"></span> If you have any bridges, please see the documentation for each bridge  
<a href="https://github.com/matrix-org/matrix-appservice-discord" target="_blank" rel="noopener noreferrer">Discord</a> |
<a href="https://matrix-org.github.io/matrix-hookshot/latest/index.html" target="_blank" rel="noopener noreferrer">Hookshot</a> |
<a href="https://matrix-org.github.io/matrix-appservice-irc/latest/index.html" target="_blank" rel="noopener noreferrer">IRC</a> |
<a href="https://docs.mau.fi/bridges/python/signal/index.html" target="_blank" rel="noopener noreferrer">Signal</a> |
<a href="https://matrix-appservice-slack.readthedocs.io/en/latest/getting_started/" target="_blank" rel="noopener noreferrer">Slack</a> |
<a href="https://docs.mau.fi/bridges/python/telegram/index.html" target="_blank" rel="noopener noreferrer">Telegram</a> |
<a href="https://docs.mau.fi/bridges/go/whatsapp/index.html" target="_blank" rel="noopener noreferrer">Whatsapp</a>
	- The process for importing the bridge databases is the same as with Synapse
1. Cancel your EMS server. See [this](https://ems-docs.element.io/link/6#bkmrk-please-discontinue-m) FAQ document for instructions. **Note, this cannot be undone and all your data will be lost. Ensure your imported server is working as expected before doing this**

# Migrate From Self-Hosted to EMS

## Notes

Before starting with this guide, please contact EMS support from <a href="https://ems.element.io/support" target="_blank" rel="noopener noreferrer">https://ems.element.io/support</a> or by emailing [ems-support@element.io](mailto:ems-support@element.io)

- Except where specified, you should be able to just copy-paste each command in succession.
- Please do not change any file names anywhere.

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

- At the latest 48 hours before your migration is scheduled, set the TTL on any DNS records that need to be updated to the lowest allowed value.
- Upgrade your Synapse to the same version as EMS is running. Generally this will be the latest stable release. <a href="https://element.ems.host/_matrix/federation/v1/version" target="_blank" rel="noopener noreferrer">https://element.ems.host/_matrix/federation/v1/version</a> is a good indicator, but confirm version with your EMS contact.
  - This is not required, but if your Synapse version is not the same as the EMS version, your migration will take longer.
- Check the size of your database and report to your EMS contact:
  - PostgreSQL: Connect to your database and issue the command `\l+`
  - SQLite: `ls -lah /path/to/homeserver.db`
- Check the size of your media repository and report to your EMS contact.
  - Synapse Media Store: `du -hs /path/to/synapse/media_store/`
  - Matrix Media Repo: <a href="https://github.com/turt2live/matrix-media-repo/blob/master/docs/admin.md#per-server-usage" target="_blank" rel="noopener noreferrer">https://github.com/turt2live/matrix-media-repo/blob/master/docs/admin.md#per-server-usage</a>
- If you are using SQLite instead of PostgreSQL, you should port your database to PostgreSQL by following [this](https://element-hq.github.io/synapse/latest/postgres.html) guide before dumping your database and sending to your EMS contact.
  - This step is not required, but will speed up your migration.

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

```bash
pwgen -s 64 1
```

Alternatively, you can use our GPG key.
<a href="https://ems-cust-content.s3.eu-central-1.amazonaws.com/ems-docs/element-support-public.pgp" target="_blank" rel="noopener noreferrer">element-support-public.pgp</a>

## GPG

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

## Create a folder to store everything

```bash
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):

```bash
chmod 000 /tmp/synapse_export
```

## Copy Synapse config

Copy the following files and send to EMS Support:

- Your Synapse configuration file (usually `homeserver.yaml`)
- Your message signing key.
  - This is stored in a separate file. See the Synapse config file for the path. The variable is `signing_key_path` <a href="https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#signing_key_path" target="_blank" rel="noopener noreferrer">https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html#signing_key_path</a>

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

- `<dbhost>` (ip or fqdn for your database server)
- `<dbusername>` (username for your synapse database)
- `<dbname>` (the name of the database for synapse)

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

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

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

```bash
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](#bkmrk-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 <a href="https://github.com/turt2live/matrix-media-repo/releases" target="_blank" rel="noopener noreferrer">https://github.com/turt2live/matrix-media-repo/releases</a>

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

- `<dbhost>` (ip or fqdn for your database server)
- `<dbname>` (the name of the database for synapse)
- `<dbusername>` (username for your synapse database)
- `/path/to/synapse/media_store` (the path to where synapse stores your media)
- `<yourdomain.tld>` (the domain for your server. this is the part that is in your usernames)

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

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

```bash
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)

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

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

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

```nginx
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;
}
```

# Reset User Password

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

- all sessions are connected to key backup,
- all sessions have backed up all their keys. See [Check Status](check-status), and
- the correct key backup passphrase is available.

<br />

1. Click `Your Account` and `Manage Servers` or click this link <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a>.

1. Click `Server Admin`, select your host, then `Users`

1. Click the user you want to manage  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702383680400-45-40-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702383680400-45-40-pm.png)

1. Click `Reset password`, enter a new password and click `Go`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702383700656-47-25-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702383700656-47-25-pm.png)

# Token based registration

Create a new registration token using the [Synapse Admin API](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/registration_tokens.html). Give this to your users.

The registration flow looks like this:

1. Enter username, password and email as normal. Click `Register`  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-07/scaled-1680-/image-1658392358640-26-06-am.png)](https://ems-docs.element.io/uploads/images/gallery/2022-07/image-1658392358640-26-06-am.png)

1. Enter the registration token and click `Continue`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-05/scaled-1680-/image-1683207542151-37-01-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-05/image-1683207542151-37-01-pm.png)

1. Continue registration like normal  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-07/scaled-1680-/image-1658392458002-26-52-am.png)](https://ems-docs.element.io/uploads/images/gallery/2022-07/image-1658392458002-26-52-am.png)

# Adding a Trust & Safety Contact

1. Click `Your Account` and `Manage Servers` or click this link <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a>.
1. Click the Hosts tab.
1. Add an email address to the `Trust and Safety contact` field and click `Save` at the bottom. 

This contact should be a user with access to respond to content takedown notices and other trust & safety concerns (such as deactivating users).

# Authentication



# Migrating from SAML to OpenID Connect

To migrate an EMS cloud host with SAML to OpenID Connect, follow the following steps.

1. Follow the [OpenID Connect setup guide](https://ems-docs.element.io/books/element-cloud-documentation/page/openid-connect#bkmrk-google) to create an OAuth2 client ID. **Important**, only do the Google console part, do NOT configure OpenID Connect on your EMS host. Do NOT remove your SAML configuration from the Google console or the EMS configuration.
2. Once you have your Google OAuth2 client ID and secret, contact EMS support (via the [portal](https://ems.element.io/support) or `ems-support@element.io`) to agree on how to securely deliver the credentials. For the ticket, request "SAML to OpenID Connect" migration, indicating the hostname in question. DO NOT put the Oauth2 client id or secret in the support ticket. Please also indicate a preferred time during week days for the migration to happen.

Support will agree on a secure delivery method for the client ID and secret, and notify of an actual migration time.

During the migration time you do not need to take any action. There will be downtime on the service for a few minutes while the changes are applied. While the migration happens the old SAML subscription will be cancelled and a new one for OpenID Connect made. This may mean a charge on your credit card. The subscription cost of OpenID Connect and SAML will be the same.

One the migration is complete, you can safely remove the SAML configuration from the Google console. Existing user sessions will work as before.

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

See also <a href="https://element.io/enterprise/enterprise-functionality/delegated-authentication" target="_blank" rel="noopener noreferrer">Delegated Authentication for single sign-on (SSO) integration</a>.

## Setup

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

- Configure secure LDAP in your domain.
- Create a user and optionally an UO to use for LDAP authentication.

## Configure Your EMS Server

- Set up an Element Cloud Enterprise server.
- Click the Integrations tab.
- Select LDAP from the list of available Advanced Authentication methods.
- Set the following configuration parameters:

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

- For Display Name, you have a few options based on your preference. For example:
  - displayName
  - GivenName
  - Name
  - sn
- For a full list, open PowerShell on your domain controller and enter

```powershell
Import-Module ActiveDirectory
Get-ADUser test_user -Properties *
```

- Save your LDAP settings and wait for your EMS server to reprovision.
- Authentication in Element should now be working. If not, please look in the logs for your firewall or domain controllers
or contact EMS support from <a href="https://ems.element.io/support" target="_blank" rel="noopener noreferrer">our support form</a>

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

- [Authentik](#bkmrk-authentik)
- [Gitea](#bkmrk-gitea)
- [GitHub](#bkmrk-github)
- [GitLab](#bkmrk-gitlab)
- [Google](#bkmrk-google)
- [Okta](#bkmrk-okta)

See also
<a
  href="https://element.io/enterprise/enterprise-functionality/delegated-authentication"
  target="_blank"
  rel="noopener noreferrer">
Delegated Authentication for single sign-on (SSO) integration
</a>.

## Authentik

- Create a new `OAuth2/OpenID Provider` provider
- Name: can be anything
- Authentication flow: `default-authentication-flow`
- Authorization flow: `default-provider-authentication-explicit-consent`
- Client type: Confidential
- Take note of the Client ID and Client Secret
- Redirect URIs/Origins (RegEx): `https://my-host.ems.host/_synapse/client/oidc/callback`. Adapt the URL to match your homeserver's address. You must use your `.ems.host` domain, even if your server uses Custom DNS.
- Signing Key: `authentik Self-signed Certificate`
- Create an application using the provider you just created. Take note of the Slug

### In the Element Matrix Services configuration form

- Preset: `Custom`
- Issuer: `https://your-authentik-instance.com/application/o/the-slug-from-above/` (you can also find this URL on the provider as `OpenID Configuration Issuer`)
- Client ID and Secret: Values from above
- Discover endpoints: Enable
- Scopes: `openid,profile,email`
- Subject claim: `sub`
- Username attribute: `preferred_username`
- Display name attribute: `name`

## Gitea

- Create a new `OAuth2 Application` on <https://your-gitea-instance.com/user/settings/applications>
- Choose a name for you and your users to recognize
- Set `Redirect URIs` to `https://my-host.ems.host/_synapse/client/oidc/callback`. Adapt the URL to match your
  homeserver's address. You must use your `.ems.host` domain, even if your server uses Custom DNS.
- Confidential Client: enable

### In the Element Matrix Services configuration form

- Preset: `Custom`
- Issuer: `https://your-gitea-instance.com/`
- Client ID and Secret: Values given by Gitea OAuth2 settings
- Discover endpoints: Enable
- Scopes: `openid,profile`
- Subject claim: leave empty
- Username attribute: `name`
- Display name attribute: `name`'

## GitHub

For detailed information, read
<a href="https://docs.github.com/en/developers/apps/authorizing-oauth-apps" target="_blank" rel="noopener noreferrer">
  GitHub's guide on OpenID
</a>.

1. Create a<a href="https://github.com/settings/applications/new" target="_blank" rel="noopener noreferrer">
    new application on GitHub.com
  </a>.
1. Choose a name for you and your users to recognize.
1. 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.
1. The Authorization callback URL needs to be `https://my-host.ems.host`. Adapt the URL to match your homeserver's
  address.
You must use your `.ems.host` domain, even if your server uses Custom DNS.
1. 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:

- Issuer must be `https://github.com/`
- Use the client id and secret from above.
- Discover must be turned off.
- Authorization URI must be `https://github.com/login/oauth/authorize`.
- Token URI must be `https://github.com/login/oauth/authorize`.
- User Info URI must be `https://api.github.com/user`.
- JWKS URI is not required, because the scope `profile` will be requested.
- The scopes should be `openid,profile,read:user`.
- Subject Claim must be `id`.
- Username attribute should be `login`.
- The display name can be `name` (GitHub's display name) or `login` (GitHub's user handle).

## GitLab

For detailed information, read
<a href="https://docs.gitlab.com/ee/integration/openid_connect_provider.html" target="_blank" rel="noopener noreferrer">
  GitLab's guide on OpenID
</a>.

1. Create a <a href="https://gitlab.com/-/user_settings/applications" target="_blank" rel="noopener noreferrer">new application
  on GitLab.com</a>.
1. Choose a name for you and your users to recognize.
1. 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.
1. The Redirect URL needs to be `https://my-host.ems.host/_synapse/client/oidc/callback`. Adapt the URL to match your
  homeserver's address.
You must use your `.ems.host` domain, even if your server uses Custom DNS.
1. Check the scopes `read_user`, `openid` and `profile`.
1. 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

- Issuer must be `https://gitlab.com/` or the URL of your GitLab instance.
- Use the client id and secret from above.
- Discover must be turned on.
- The scopes should be `openid,profile,read_user`.
- Leave Subject Claim empty.
- Username attribute should be `nickname`.
- Display name attribute can be `name` (GitLab's display name) or `nickname` (GitLab's user handle).

## Google

For detailed information, read
<a
  href="https://developers.google.com/identity/protocols/oauth2/openid-connect"
  target="_blank"
  rel="noopener noreferrer">
Google's guide on OpenID
</a>.

1. Create a <a href="https://console.developers.google.com/apis/credentials" target="_blank" rel="noopener noreferrer">
  new application on Google
</a>.
1. Click `Create credentials` and `OAuth client ID`.
1. Select the application type `Web application`.
1. Choose a name for you and your users to recognize.
1. Add an authorized redirect URI with your homeserver URL, like
  `https://my-host.ems.host/_synapse/client/oidc/callback`.
  You must use your `.ems.host` domain, even if your server uses Custom DNS.
1. Save and note the client ID and client secret. Those are needed when adding the OpenID Connect integration in our
  interface.
<!--[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702389800129.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702389800129.png)-->
<video width="600" controls
  poster="https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702389800129.png"
  src="https://ems-cust-content.s3.eu-central-1.amazonaws.com/ems-docs/create-google-oauth.webm">
</video>

### In the Element Matrix Services configuration form

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

- Issuer must be `https://accounts.google.com/`.
- Use the client id and secret from above.
- Discover must be turned on.
- The scopes should be `openid,profile,email`.
- Leave Subject Claim empty.
- Username attribute can be `email`. This means your Matrix addresses will include the server domain of the user's
  e-mail address.
- Display name attribute can be `name`.

## Okta

For detailed information, read
<a href="https://developer.okta.com/docs/reference/api/oidc/" target="_blank" rel="noopener noreferrer">
  Okta's guide onOpenID
</a>.

1. Create a new App. Sign-in method `OIDC - OpenID Connect` and Application type `Web Application`.
1. Choose a name for you and your users to recognize.
1. Sign-in redirect URIs: `https://my-host.ems.host/_synapse/client/oidc/callback`. Adapt the URL to match your
homeserver's address. You must use your `.ems.host` domain, even if your server uses Custom DNS.
1. Sign-out redirect URIs: `https://my-host.ems.host/_synapse/client/oidc/backchannel_logout`. Adapt the URL to match
your homeserver's address. You must use your `.ems.host` domain, even if your server uses Custom DNS.

### In the Element Matrix Services configuration form

- Choose Preset Custom.
- Issuer: `https://your-domain.okta.com`.
- Client ID: Your client ID from the Okta admin panel.
- Client secret: Your client secret from the Okta admin panel.
- Scopes: `openid,profile`.
- Leave Subject Claim empty.
- Username attribute: See below
- Display name attribute: for example, `given_name family_name`

#### Username attributes

This refers to the user's localpart in their Matrix ID (`@localpart:example.com`). The data provided in a minimally
configured Okta user is not ideal for integration with EMS. Below are some possible configuration suggestions. All
examples below use the Matrix server domain `example.com`.

Available values for username and display name are `email` (you must include `email` in Scopes), `phone_number` (you
must include `phone` in Scopes), `address`, `name`, `family_name`, `given_name`, `middle_name`, `nickname`,
`preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`,`locale`, and `updated_at`.
(List updated June 8, 2023. See [this](https://developer.okta.com/docs/reference/api/oidc/#scopes) document for updated
information. Available options are listed in the table under "Scopes" and after the "profile" bullet under "Scope
values").

Make sure all users that will be using your EMS server have the selected attributes set.

Option 1: Username attribute `email`. This will use the user's entire email address as their localpart. Including the
domain. It will also be encoded to be compatible with Matrix. For example, email `jane@example.com` will become
`jane=40example.com:example.com`. To use the email, you must also include `email` in Scopes.

Option 1b: We can add some logic to your OIDC config to exclude the email domain. Contact support for further details.

Option 2: Username attributes: `name`. This will use the user's full name from Okta. Note that spaces (and other
special characters) are not supported in Matrix localparts. For example, spaces will be encoded as `=20`. (I.e., `Jane
Doe` becomes `@jane=20doe:example.com`.

Option 2b: We can add some logic to replace spaces with for example underscore. Contact us for details.

Option 3: By default, usernames in Okta must be an email. But, if you have changed this behavior, you can set Username
attributes to `preferred_username` to use the username.

Note, the attribute you choose for localparts does not have to be unique. But if you, for example, set Username
attributes to `given_name`, the first Jane who sign in to your EMS server will become `@jane:example.com` and the
second Jane becomes `@jane1:example.com`.

Please contact EMS Support at <https://ems.element.io/support> to discuss your options.

# 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 <a href="https://element-hq.github.io/synapse/latest/usage/administration/admin_api/" target="_blank" rel="noopener noreferrer">Synapse Admin API</a>.

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

- All active administrators in a room depromoted themselves. Use Admin Bot to regain control of this room.
- Someone reported a Code of Conduct violation in a room without active moderators. Use Admin Bot to redact the messages and kick or ban the offender.

## Good to know

- Admin Bot joins all rooms and spaces created by your users.
- Admin Bot also joins Direct Message rooms created by your users.
- The use of Admin Bot is visible to your users. The service account cannot be hidden. In Direct Message rooms it will not appear in the room title but is visible in the room member list.
- Admin Bot does not join rooms created by users on others servers. You can still manually invite Admin Bot and promote them to be a room admin.
- The user account `adminbot` will be used. The full Matrix ID will be something like `@adminbot:element.io`.
- Admin Bot is able to read encrypted messages to allow you to moderate messages.
- Admin Bot does not work retroactively, rooms where all admins have left prior to setup of the bot will require manual intervention.

## See also

<a href="https://element.io/enterprise/enterprise-functionality/adminbot" target="_blank" rel="noopener noreferrer">AdminBot for global room administration</a>.

## Setup

1. Go to the <a href="https://ems.element.io/user/hosting#/integrations" target="_blank" rel="noopener noreferrer">Integrations tab on the EMS homeserver page</a>.
1. If you have more than one homesever, select the homeserver to add Admin Bot to.
1. In the section Extensions, click on `Admin Bot`. If this is not visible, check that the homeserver is using the Element Enterprise Cloud plan.
1. Click on `Set Up Integration` and confirm the pricing in a modal.

[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384111522.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384111522.png)

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

[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384061318.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384061318.png)

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

1. Go to the <a href="https://ems.element.io/user/hosting#/integrations" target="_blank" rel="noopener noreferrer">Integrations tab on the EMS homeserver page</a>.
1. If you have more than one homeserver, select the one you want to administrate.
1. In the section Extensions, click on `Admin Bot`. If this is not visible, check that the homeserver is using the Element Enterprise Cloud plan.
1. 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.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384167698.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384167698.png)

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

# 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

- A law or organisational guideline requires you to store all written correspondence.
- A legal investigation requires you to verify or deny if a certain message has been sent.

## Good to know

- Audit Bot joins all rooms and spaces created by your users.
- Audit Bot also joins Direct Message rooms created by your users.
- The use of Audit Bot is visible to your users. The service account cannot be hidden. In Direct Message rooms it will not appear in the room title but is visible in the room member list.
- Audit Bot does not join rooms created by users on others servers. You can still manually invite Audit Bot.
- The user account `auditbot` will be used. The full Matrix ID will be something like `@auditbot:element.io`.
- Audit Bot is able to read encrypted messages to allow you to read or store all messages.

## See also

<a href="https://element.io/enterprise/enterprise-functionality/auditbot" target="_blank" rel="noopener noreferrer">AuditBot for regulation and compliance</a>.

## Setup

1. Go to the <a href="https://ems.element.io/user/hosting#/integrations" target="_blank" rel="noopener noreferrer">Integrations tab on the EMS homeserver page</a>.
1. If you have more than one homesever, select the homeserver to add Audit Bot to.
1. In the section Extensions, click on `Audit Bot`. If this is not visible, check that the homeserver is using the Element Enterprise Cloud plan.
1. 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 <a href="https://ems.element.io/user/hosting#/integrations" target="_blank" rel="noopener noreferrer">Integrations tab on the EMS homeserver page</a>.
1. If you have more than one homeserver, select the one you want to administrate.
1. In the section Extensions, click on `Audit Bot`. If this is not visible, check that the homeserver is using the Element Enterprise Cloud plan.
1. 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.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384268009.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384268009.png)

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

# Create a Conference Call in a Room

## Setting up

1. Create a room  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384338234-26-14-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384338234-26-14-pm.png)

1. Click `Room Info`, then `Add apps, bridges & bots`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384354807-26-00-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384354807-26-00-pm.png)

1. Read and accept the Terms of Service for the Integration Manager  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384372820-25-37-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384372820-25-37-pm.png)

1. Select Jitsi from the list of available widgets  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384435099-28-29-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384435099-28-29-pm.png)

1. Save the URL if you wish, this is also easily available later. Then click `Save`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384454298-29-46-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384454298-29-46-pm.png)

1. Click the `X` to close the integration manager  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384473925-31-11-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384473925-31-11-pm.png)

1. To join the room conference, expand the Jitsi section at the top. Then click `Join Conference`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384492112-32-26-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384492112-32-26-pm.png)

1. Allow camera and microphone access. Note this might be different depending on your browser and operating system  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384510342-36-41-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384510342-36-41-pm.png)

1. You are now in the conference  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384526358-36-05-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384526358-36-05-pm.png)

## Inviting external participants

1. Click the info button in the bottom right corner  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384542301-39-08-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384542301-39-08-pm.png)

1. Click `Copy`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384556705-39-45-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384556705-39-45-pm.png)

1. Send the link to the external participant. They can just copy and paste it to their browser to join  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384575322-56-33-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384575322-56-33-pm.png)

## Screen sharing

1. Click the screen sharing in the bottom left corner  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384590404-58-07-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384590404-58-07-pm.png)

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

1. Select the application or screen you want to share, then click Allow. Note this might be different depending on your browser and operating system  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384612429-02-52-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384612429-02-52-pm.png)

1. Everyone can now see your screen

# Discord Bridge

The Discord bridge is no longer available for purchase. This documentation is for existing customers of the bridge only.

## Setup

First, you need to register a Discord application for your bridge. Discord applications can be registered and managed in the <a href="https://discord.com/developers/applications/" target="_blank" rel="noopener noreferrer">Discord Developer Portal</a>.

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

### Authorize your account

Before authorizing your Discord App, you first need to grant your account the following rights:
1. Manage Webhooks
1. Manage Server

[![Screenshot 2022-10-17 at 07.45.19.png](https://ems-docs.element.io/uploads/images/gallery/2022-10/scaled-1680-/screenshot-2022-10-17-at-07-45-19.png)](https://ems-docs.element.io/uploads/images/gallery/2022-10/screenshot-2022-10-17-at-07-45-19.png)

### 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`.  
    [![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384749669.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384749669.png)
1. In a Matrix room you want to bridge, invite `@discord:example.ems.host` (replace the domain with the one of your homeserver).  
1. Post the message `!discord bridge GUILD_ID CHANNEL_ID` after replacing the two placeholders.  
    [![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384759883.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384759883.png)
1. A privileged Discord user will need to approve the bridge request by responding with `!matrix approve`  
    [![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384768109.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384768109.png)
1. Messages from Discord are now bridged to Matrix and vice versa.  
    [![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384777081.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384777081.png)

### Unbridge

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

### Private Chats

Currently, private chats are not supported by the EMS Discord bridge.

# Hookshot

Dedicated Hookshot instances are available for EMS customers. To request Hookshot added to your server, please
talk to Support or your Account Manager.

This guide only covers EMS-specific settings. You must review the Hookshot documentation available at
<https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html>.

This guide uses my demo server with the EMS hostname and server domain `snowleopard-staging.ems.host`. You must use your
`.ems.host` domain for all fields, even if your server uses Custom DNS. Replace `snowleopard-staging` with your
hostname.

## GitHub

Use the following settings for your GitHub app:

- GitHub App name: This can be anything
- Homepage URL: This can be any valid URL
- Callback URL: `https://snowleopard-staging.ems.host/hookshot/oauth/`
- Setup URL: `https://snowleopard-staging.ems.host/hookshot/oauth/`
- Webhook URL: `https://snowleopard-staging.ems.host/hookshot/`
- Webhook secret: Generate a random secure string
- SSL verification: Enabled
- Permissions: Configure per <https://matrix-org.github.io/matrix-hookshot/latest/setup/github.html#permissions>
- Subscribe to events: Configure per <https://matrix-org.github.io/matrix-hookshot/latest/setup/github.html#permissions>
- Where can this GitHub App be installed? Only on this account
- Example config screenshot. Changes are highlighted with arrows.  
Click the image to open it in a new tab to zoom in  
<a href="https://element.ems.host/_matrix/media/r0/download/element.io/ca419b5c17e095201e9b429d66e3472574ac3fcc" target="_blank"><img src="https://element.ems.host/_matrix/media/r0/download/element.io/847836b7bccc0ef53352a8c1c7b476a75dfa3bf4" /></a>

Send the following information to your Element contact:

- App ID
- Client ID
- Client Secret
- Private Key
- Webhook Secret

# Migrate to the new GitHub and Feeds bots

New versions of the GitHub and RSS bots provided by Element are now available!

The previous bots are now considered deprecated and can no longer be configured. These bots have user IDs like `@_neb_rssbot_...:matrix.org` or `@_neb_github_...:matrix.org` and will be decommissioned on **April 30, 2023**.

#### Who is this for?
These instructions are for anybody who previously set up a GitHub or RSS bot using the integration manager provided by Element.

### How to migrate

You may migrate your bots using Element Web or Desktop.

1. Open the **Room info** side panel and press **Add/Edit widgets, bridges & bots**.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-03/scaled-1680-/image-1679084635130-23-43-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1679084635130-23-43-pm.png) [![](https://ems-docs.element.io/uploads/images/gallery/2023-03/scaled-1680-/image-1679084617809-23-21-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1679084617809-23-21-pm.png)
2. Select the bot you are migrating (**Feeds** or **GitHub**).  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-03/scaled-1680-/image-1679498646147-23-11-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1679498646147-23-11-am.png)
3. Press **Add** to add the new bot to the room.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-03/scaled-1680-/image-1679500438175-53-45-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1679500438175-53-45-am.png)
4. Set up the new bot. Any configurations added previously will be shown under **Migrate connections**.
    - When migrating GitHub, it may be necesssary to log in again.
    
    [![](https://ems-docs.element.io/uploads/images/gallery/2023-03/scaled-1680-/image-1679084842029-27-07-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-03/image-1679084842029-27-07-pm.png)
5. Kick the deprecated bot.

#### If you don't want to migrate

If you don't want to migrate your bots, you can just kick the GitHub or RSS Bot user from the room.

#### If you don't do anything

If you don't take any action, the deprecated bots will remain functional for the time being, but can no longer be configured. These bots will stop functioning fully after the date mentioned above.

#### If you have issues
Issues can be reported to [element-hq/element-integration-manager](https://github.com/element-hq/element-integration-manager/issues).

#### Some bots won't be available anymore

The following bots will also be deprecated, but unfortunately do not have a new version available:
* Travis CI
* Giphy
* Google Image Search
* Wikipedia Search
* Imgur Image Search

# 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 <a href="https://matrix-org.github.io/matrix-appservice-irc/latest/bridged_networks.html" target="_blank" rel="noopener noreferrer">offical documentation</a>.

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

# Public Slack Bridge

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

- You can bridge to an unlimited number of channels, but only public channels.
- You must bridge to a public room.
- Matrix users cannot puppet themselves, or Direct Message other users.

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.

- An EMS server is not required.
- It requires your homeserver to be able to federate with Matrix.org.

## Setup

1. Create a new room in Matrix, with encryption off  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384900366-12-35-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384900366-12-35-am.png)  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384920661-12-48-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384920661-12-48-am.png)

1. Click `Room Info` in the top right corner of the room  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384936633-13-57-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384936633-13-57-am.png)

1. Click `Add widgets, bridges & bots`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384952623-14-55-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384952623-14-55-am.png)

1. Choose `Slack` from the list of available bridges and integrations  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384969393-15-37-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384969393-15-37-am.png)

1. Click `Add Bridge`  
**NOTE if you have purchased your Slack bridge from EMS:** Ensure it says `Slack integration on <your ems domain>` here.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702384989016-16-21-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702384989016-16-21-am.png)

1. Click `Add to Slack`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385016689-17-07-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385016689-17-07-am.png)

1. Enter your Slack workspace URL, and click `Continue`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385033982-18-22-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385033982-18-22-am.png)

1. Enter your Slack email address and password, then click `Sign in`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385050436-19-10-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385050436-19-10-am.png)

1. Click `Allow`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385069574-21-07-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385069574-21-07-am.png)

1. Close the Slack tab and return to Element  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385089379-21-48-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385089379-21-48-am.png)

1. Click `List channels`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385106822-23-00-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385106822-23-00-am.png)

1. Click the Slack channel you want to bridge to the Matrix room  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385130078-23-42-am.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385130078-23-42-am.png)

1. Slack is now added to the Matrix room  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385148815-51-41-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385148815-51-41-pm.png)

1. Go to the channel you selected on Slack, click the ` ` below the message box, enter `invite`, and select `Add apps to this channel`  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-05/scaled-1680-/image-1651758294410-44-25-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-05/image-1651758294410-44-25-pm.png)

1. Add the Element Bridge  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-05/scaled-1680-/image-1651758344201-45-28-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-05/image-1651758344201-45-28-pm.png)  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-05/scaled-1680-/image-1651758417541-45-58-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2022-05/image-1651758417541-45-58-pm.png)

1. The Matrix room and Slack channel are now bridged  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385176956-57-34-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385176956-57-34-pm.png)  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385195525-57-48-pm.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385195525-57-48-pm.png)

# 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: <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a>  
Click the `Integrations` tab  and if you have more than one server, select the server you wish to add the Signal integration to.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385354497.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385354497.png)

1. Click on `Signal Bridge` in the list of available Bridges.
[![](https://ems-docs.element.io/uploads/images/gallery/2024-02/scaled-1680-/ems-bridges.png)](https://ems-docs.element.io/uploads/images/gallery/2024-02/ems-bridges.png)

1. 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.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385394246.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385394246.png)  
If you enter `5` or greater in `Maximum Signal users`, you will not see a warning.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385418148.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385418148.png)  
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).

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 Signal Integration.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385439013.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385439013.png)

1. 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`.
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385481529.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385481529.png)

1. Create a Direct Message conversation by typing `@signalbot:example.ems.host` (replace the domain with the one of your homeserver). Then click `Go`.  
[![element-dm.png](https://ems-docs.element.io/uploads/images/gallery/2024-02/scaled-1680-/element-dm.png)](https://ems-docs.element.io/uploads/images/gallery/2024-02/element-dm.png)

1. The bridge account will join your room and tell you how to use it.
[![](https://ems-docs.element.io/uploads/images/gallery/2024-02/scaled-1680-/element-hello.png)](https://ems-docs.element.io/uploads/images/gallery/2024-02/element-hello.png)

1. Open Signal on your mobile device (iOS or Android) and tap on your avatar to go to `Settings` and then `Linked Devices` and then `+` 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.  
[![](https://ems-docs.element.io/uploads/images/gallery/2024-02/scaled-1680-/signal-link-device.jpg)](https://ems-docs.element.io/uploads/images/gallery/2024-02/signal-link-device.jpg)

1. From your Element client, send a `login` message to the bot to connect to your Signal account.  
[![](https://ems-docs.element.io/uploads/images/gallery/2024-02/scaled-1680-/element-login.png)](https://ems-docs.element.io/uploads/images/gallery/2024-02/element-login.png)

1. 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 `login` message again to generate another QR code.  

1. On your Element client, you will see `Successfully logged in as <your_phone_number> (UUID: <your_signal_id>)`. Once a new message arrives in one of your Signal chats, you will see an invitation for it 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). **This currently works only for Signal users that the bridge has seen activity from.**

1. On your Element client, open your DM with the Signal bridge bot.
1. Say `pm` followed by the phone number for your contact.
1. 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.
1. The user has not added you as a contact on their phone.
1. 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

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

# Slack Bridge

The Slack bridge is no longer available for purchase. This documentation is for existing customers of the bridge only.

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

- Allows you to bridge to private rooms and private channels.
- Allows you to puppet your Slack identity from Matrix, appearing to send messages as if you were using Slack.
- Direct Message other Slack users

## Purchase the Slack integration

1. Open the EMS control panel at: <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a>

1. Click the `Integrations` tab  and if you have more than one server, select the server you wish to add the Slack integration to  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385354497.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385354497.png)

1. Click on `Slack Bridge` in the list of available Bridges
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385374123.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385374123.png)

1. 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  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385773797.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385773797.png)

1. 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](public-slack-bridge)

## Initiate a DM with a Slack user from Matrix

- Message the Slack bot user on Matrix.
- Say `login`
- An OAuth2 URL will be displayed. Follow it to get puppeted to the right Slack instance.
- Click a Slack user in Matrix and DM as normal

# Teams Bridge

The Teams bridge is no longer available for purchase. This documentation is for existing customers of the bridge only.

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

### Teams Link

1. In the [Teams app](https://teams.microsoft.com/), not the admin page. Click the three dots next to your Teams, then `Get link to team`  
[![](https://ems-docs.element.io/uploads/images/gallery/2022-08/scaled-1680-/image-1660645173384-19-25-am.png)](https://ems-docs.element.io/uploads/images/gallery/2022-08/image-1660645173384-19-25-am.png)
1. Click `Copy`
1. Paste this link into the `Teams Link` field on the Teams Bridge setup form on <https://ems.element.io/user/hosting#/integrations>
1. Click `Link Teams to Element`
1. Follow the Microsoft flow and allow access

### 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 <a href="https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview" target="_blank" rel="noopener noreferrer">Azure Active Directory page</a>.
1. Click users.
1. Click New user.
1. 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.
1. 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).
1. After logging in you should be prompted to set a new password.
1. 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 a room **bridged to a Teams channel** (for instance, public rooms in the room directory). 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.**

### Bot Commands

[![](https://ems-docs.element.io/uploads/images/gallery/2022-09/scaled-1680-/image-1663166685626.png)](https://ems-docs.element.io/uploads/images/gallery/2022-09/image-1663166685626.png)

In a chat with the "Teams Bridge" bot, users can manually connect their Teams account with their EMS account by sending the `login` command to the bridge bot. The bot will reply with a link that users can use to login

`You must authenticate with MS Teams to continue: <login.microsoftonline.com link>`

After succesfully login in you should get a message like:

`You are now authenticated as **Teams User**`

To add a bridged Microsoft Teams team as a space in Element, this can be accomplished by sending the `joinspace` command.
This should add a new space to the sidebar of you Element client with the same name as the teams that you had previously setup with the Bridge, with individual channels showing up as rooms within the new space.

[![](https://ems-docs.element.io/uploads/images/gallery/2022-09/scaled-1680-/image-1663167329530.png)](https://ems-docs.element.io/uploads/images/gallery/2022-09/image-1663167329530.png)


Other commands and option are availble via sending `help` to the bot. The current help text is show below:

* `help` - This help text
* `login` - Authenticate with MS Teams to enable puppeting
* `logout` - Remove your MS Teams authentication
* `startupnotice enable` - Send a notification to this room when the bridge is restarted
* `startupnotice disable` - Disable startup notifiations
* `joinspace` - Join the space(s) for your team(s)


### Known limitations

* Private channels are not supported

# 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: <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a>

1. Click the `Integrations` tab  and if you have more than one server, select the server you wish to add the Telegram integration to.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385354497.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385354497.png) 

1. Click on `Telegram Bridge` in the list of available Bridges.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385374123.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385374123.png)

1. 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.**

1. If you wish to allow Matrix users who aren't logged in to Telegram to participate in bridged Telegram chats, follow the steps in [this section](#bkmrk-bridging-matrix-user). 

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.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385919528.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385919528.png)

1. 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`.  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385972923.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385972923.png)

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

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

1. Open Telegram on your mobile device (iOS or Android) and tap on ≡, go to `Settings`, and then `Devices`, and then `Link Desktop Device` 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.

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

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

1. On your Element client, you will see `Successfully logged in as <username>`, and you will see invitations for each of your Telegram channels, groups, and DMs in your Element client. Each Telegram 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 Telegram on mobile.

## Sending a message to a 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.

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

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

## Bridging Matrix users without a Telegram account

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.  (Note: relaying is supported for Telegram groups, but is not yet supported for Telegram channels.)

Follow these steps to register a bot account with Telegram.

1. With your Telegram account, message <a href="https://www.t.me/BotFather" target="_blank" rel="noopener noreferrer">`@BotFather`</a>.  If talking to BotFather via the bridge using Element, note that all "slash" command messages (eg. `/start`) sent to BotFather must begin with two slashes instead of one (eg. `//start`).

1. Create a new bot by sending the message `/newbot` to BotFather.  The created bot will be the Telegram relay bot used by your bridge.  Follow the subsequent prompts to give your bot a display name and a username.

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

1. Send the message `/setprivacy` to BotFather and follow the prompts to set your new bot's privacy settings to "Disabled". This allows your relay bot to bridge all messages sent in a Telegram group, not just messages that mention the bot by name.

1. Open the EMS control panel for your Telegram bridge and enter the token you received from BotFather in the "Bot token" field, then wait for the page to notify you when your bridge is ready.
![EMStelegramBotToken.png](https://ems-docs.element.io/uploads/images/gallery/2022-11/scaled-1680-/emstelegrambottoken.png)

1. In your Element client, view your DM with the Telegram bridge bot and send the `ping-bot` command. The bot should respond with the ID of your relay bot in Matrix, which indicates that the relay bot has been set up correctly.

1. In your Element client, invite the Matrix relay bot to any room that bridges a Telegram group that should relay Matrix users' messages to Telegram.  A convenient way to do so is to send a message of `!tg ping-bot` in such a room (which will be intercepted by the bridge bot & won't appear in Telegram), wait for the bridge bot to respond with a "pill" of the relay bot's Matrix ID, click on the pill, and then click "Invite" on the sidebar that appears.

1. In Telegram, confirm that your Telegram relay bot has joined the group.  If it hasn't, you may manually invite your bot to the group (as long as you have permissions to do so) by viewing the group's details, selecting "Add Members", and entering the username of your relay bot that you chose in step 2.

### Using the Telegram bridge 

See our documentation [here](https://ems-docs.element.io/books/element-support/page/using-the-telegram-bridge).

# 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: <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a>

1. Click the `Integrations` tab  and if you have more than one server, select the server you wish to add the WhatsApp integration to  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385354497.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385354497.png)

1. Click on `WhatsApp Bridge` in the list of available Bridges
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702385374123.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702385374123.png)

1. 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  
    [![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702386058444.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702386058444.png)
    - If you enter `5` or greater in `Maximum WhatsApp users`, you will not see a warning  
    [![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702386067468.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702386067468.png)
    - 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).

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 WhatsApp Integration  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702386075800.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702386075800.png)

1. 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`
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702386086452.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702386086452.png)

1. Create a Direct Message conversation by typing `@whatsappbot:example.ems.host` (replace the domain with the one of your homeserver). Then click`Go`  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702386100921.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702386100921.png)

1. The bridge account will join your room and tell you how to use it
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702386108708.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702386108708.png)

1. 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  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702386116486.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702386116486.png)

1. From your Element client, send a `login` message to the bot to connect to your WhatsApp account  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702386126046.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702386126046.png)

1. 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  
[![](https://ems-docs.element.io/uploads/images/gallery/2023-12/scaled-1680-/image-1702386134936.png)](https://ems-docs.element.io/uploads/images/gallery/2023-12/image-1702386134936.png)

1. On your Element client, you will see `Successfully logged in as <phone-number> (device #<number>)`.

1. From your Element client, send a message of `sync groups --create-portals` to the bot to bridge your existing WhatsApp chats to Matrix. You will then 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.
1. Say `pm` followed by the **international** formatted phone number for your contact.
1. 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 <a href="https://faq.whatsapp.com/general/download-and-installation/about-linked-devices" target="_blank" rel="noopener noreferrer">documentation</a>:

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

## My contacts show as @whatsapp_[phone number]:homeserverdomain.com

Try sending the `sync contacts` command in your DM with the WhatsApp bridge bot.

## Relay Mode is not supported

EMS does not support the WhatsApp Bridge's Relay Mode for Element Cloud, Element Enterprise Cloud or Element One.

### Using the WhatsApp bridge

Please see our documentation [here](https://ems-docs.element.io/books/element-support/page/using-the-whatsapp-bridge).

# EMS Account Management

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

# Creating an EMS Account

<!---
Actions needed:
- [ ] 

# Creating an EMS Account
--->

<!---<p class="callout info">Remember to check our <a href="https://ems-docs.element.io/books/kieranml-test-book/page/have-you-tried-httpselementiohelp">Looking for help?</a> page for answers to Frequently Asked Questions and our User Guide!</p>--->

Your EMS Account is used to manage and use your subscriptions with Element, whether for your own managed homeserver in the cloud, accessing your On-Premise subscription download portal or your Element One bridges.

Depending on which subscription you want, you wil setup an EMS Account as part of that setup flow. You can however also manually create an account first, then sign-up for your desired subcription.

### Manually Registering for an EMS Account

To manually register, from the <a href="https://element.io/" target="_blank" rel="noopener noreferrer">Element</a> homepage, click `Sign In` then `Admin Dashboard` to be taken to the EMS Control Panel. As you don't yet have a login, you will be presented with the login page.

[![element_io_sign_in](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691053542763.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053542763.png)

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

[![element_io_sign_up](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691053685641.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053685641.png)

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

[![element_io_email_verification](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691053824964.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053824964.png)

After you recieve the email, click the link to verify, then on the page `Click here to proceed` to confirm creation of your EMS Account.

[![element_io_email_confirm](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691053972849.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053972849.png)

[![element_io_email_verified](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691053984968.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053984968.png)

With your email verified and account created, repeat the steps to open the [EMS Control Panel](https://ems.element.io/user/hosting#/hosts), or click the link. Login with your details, then accept the Terms and Conditions.

[![element_io_terms_and_conditions](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691054183691.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054183691.png)

You are now in the EMS Control Panel where you can manage your account and subscriptions.

### Your EMS Account when signing up through Element One

If your interested in <a href="https://ems.element.io/element-one" target="_blank" rel="noopener noreferrer">Element One</a>, you'll be prompted to create your EMS Account whilst running through the Element One setup flow.

[![element_one_sign_up](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691054322843.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054322843.png)

Agree to the Terms and Conditions, then you'll be taken to the account creation form. Follow the steps from the `Manually Registering for an EMS Account` section above for step-by-step instructions on this process.

If you already manually created an account, but still see the `Sign Up` screen, it's possible you are no longer signed in. Open the <a href="https://ems.element.io/user/hosting#/hosts" target="_blank" rel="noopener noreferrer">EMS Control Panel</a>, log in with your details, then repeat the <a href="https://ems.element.io/element-one" target="_blank" rel="noopener noreferrer">Element One</a> sign-up flow.

Once signed up, or logged in, you should be taken to complete the Element One sign-up flow, seen below.

[![element_one_account_setup](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691054557538.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054557538.png)

### Your EMS Account when signing up for an On-Premise trial

If you're looking at trying our self hosted On-Premise offering, you will be prompted to register for an account. Click `Register` then accept the Terms and Conditions. Provide your email address then click `Continue`, you will be taken to the registration page. Follow the steps from the `Manually Registering for an EMS Account` section above for step-by-step instructions on this process.

If you already manually created an account, but still see the `Sign Up` screen, it's possible you are no longer signed in. Open the <a href="https://ems.element.io/user/hosting#/hosts" target="_blank" rel="noopener noreferrer">EMS Control Panel</a>, log in with your details, then repeat the <a href="https://ems.element.io/element-one" target="_blank" rel="noopener noreferrer">Element One</a> sign-up flow.

[![onpremise_trial_register](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691054742377.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054742377.png)

[![onpremise_trial_terms](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691054761175.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054761175.png)

[![onpremise_trial_email](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691054781236.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691054781236.png)

### Your EMS Account when signing up for a fully managed homeserver

If you're looking to buy a fully managed homeserver you'll be presented with the creation flow, the first stage being registering for an EMS Account. Click `Register`, then agree to the Terms and Conditions. Follow the steps from the `Manually Registering for an EMS Account` section above for step-by-step instructions on this process.

If you already manually created an account, but still see the `Sign Up` screen, it's possible you are no longer signed in. Open the <a href="https://ems.element.io/user/hosting#/hosts" target="_blank" rel="noopener noreferrer">EMS Control Panel</a>, log in with your details, then repeat the sign-up flow.

[![ems_account_register](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055187227.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055187227.png)

[![ems_account_terms](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055274956.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055274956.png)

# Securing an EMS Account

<!---
Actions needed:
- [ ] 

# Securing an EMS Account
--->

<!---<p class="callout info">Remember to check our <a href="https://ems-docs.element.io/books/kieranml-test-book/page/have-you-tried-httpselementiohelp">Looking for help?</a> page for answers to Frequently Asked Questions and our User Guide!</p>--->

### Two-Factor Authentication

From the <a href="https://element.io/" target="_blank" rel="noopener noreferrer">Element</a> homepage, click `Sign In` then `Admin Dashboard` to be taken to the EMS Control Panel. If you aren't logged in already, you will be presented with the login screen - sign in using your details to be taken to the EMS Control Panel.

[![element_io_navigation_sign_in](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691053542763.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053542763.png)

[![ems_sign_in](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055581048.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055581048.png)

Click `Your Account`, found in the top right, then select `Account`, or goes directly there from this link, <a href="https://ems.element.io/user/account" target="_blank" rel="noopener noreferrer">Account Page</a>.

[![your_account](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055644130.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055644130.png)

This page contains details about your account, to secure your account, you will need to click `Authentication Settings` found at the bottom of the `Edit your profile` section.

[![your_account_settings](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055793853.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055793853.png)

This will take you to your Account Console, where you can manage your account security settings. Click `Signing In` under `Account Security`, then from the `Two-factor authentication` section click `Setup an authenticator application`.

[![element_account_management](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055925565.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055925565.png)

[![two_factor_authentication_settings](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055946973.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055946973.png)

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

[![identity_confirmation](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055997291.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055997291.png)

[![mobile_authenticator_setup](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691056046959.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056046959.png)

If you're planning on using a password manager, you may not be able to scan the QR code. Simply click `Unable to scan`, copy the code and paste it into your password manager. Configuration values are provided below the code, should your application require this information. To complete this process, provide a generated code from your device / password manager, give it a recognisable device name then click `Submit`.

[![two_factor_authentication_settings_post_setup](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691056199966.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056199966.png)

You can confirm this was successful, as you will see the device listed under the `Two-factor authentication` section.

### Changing your EMS Account Email

From the <a href="https://element.io/" target="_blank" rel="noopener noreferrer">Element</a> homepage, click `Sign In` then `Admin Dashboard` to be taken to the EMS Control Panel. If you aren't logged in already, you will be presented with the login screen - sign in using your details to be taken to the EMS Control Panel.

[![element_io_navigation_sign_in](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691053542763.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053542763.png)

[![ems_sign_in](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055581048.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055581048.png)

Click `Your Account`, found in the top right, then select `Account`, or goes directly there from this link, <a href="https://ems.element.io/user/account" target="_blank" rel="noopener noreferrer">Account Page</a>.

[![your_account](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055644130.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055644130.png)

This page contains details about your account, to change your email, simply edit the existing email present and then click `Save`, a banner will appear asking you to verify this new email address.

[![your_account_settings](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055793853.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055793853.png)

[![verify_email_prompt](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691056404870.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056404870.png)

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

[![verification_email](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691056498132.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056498132.png)

# Changing an EMS Account Password

<!---
Actions needed:
- [ ] 

# Changing an EMS Account Password
--->

<!---<p class="callout info">Remember to check our <a href="https://ems-docs.element.io/books/kieranml-test-book/page/have-you-tried-httpselementiohelp">Looking for help?</a> page for answers to Frequently Asked Questions and our User Guide!</p>--->

### Changing your EMS Account Password

From the <a href="https://element.io/" target="_blank" rel="noopener noreferrer">Element</a> homepage, click `Sign In` then `Admin Dashboard` to be taken to the EMS Control Panel. If you aren't logged in already, you will be presented with the login screen - sign in using your details to be taken to the EMS Control Panel.

[![element_io_navigation_sign_in](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691053542763.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053542763.png)

[![ems_sign_in](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055581048.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055581048.png)

Click `Your Account`, found in the top right, then select `Account`, or goes directly there from this link, <a href="https://ems.element.io/user/account" target="_blank" rel="noopener noreferrer">Account Page</a>.

[![your_account](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055644130.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055644130.png)

This page contains details about your account, to change your password, you will need to click `Authentication Settings` found at the bottom of the `Edit your profile` section.

[![your_account_settings](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055793853.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055793853.png)

This will take you to your Account Console, where you can manage your account security settings. Click `Signing In` under `Account Security`, then from the `Basic authentication` section click the `Update` button.

[![element_account_management](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055925565.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055925565.png)

[![basic_authentication_settings](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691056709130.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056709130.png)

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

[![identity_confirmation](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055997291.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055997291.png)

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

[![password_update](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691056774523.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691056774523.png)

# Deleting an EMS Account

<!---
Actions needed:
- [ ] 

# Deleting an EMS Account
--->

<!---<p class="callout info">Remember to check our <a href="https://ems-docs.element.io/books/kieranml-test-book/page/have-you-tried-httpselementiohelp">Looking for help?</a> page for answers to Frequently Asked Questions and our User Guide!</p>--->

### Deleting an EMS Account

From the <a href="https://element.io/" target="_blank" rel="noopener noreferrer">Element</a> homepage, click `Sign In` then `Admin Dashboard` to be taken to the EMS Control Panel. If you aren't logged in already, you will be presented with the login screen - sign in using your details to be taken to the EMS Control Panel.

[![element_io_navigation_sign_in](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691053542763.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691053542763.png)

[![ems_sign_in](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055581048.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055581048.png)

Click `Your Account`, found in the top right, then select `Account`, or goes directly there from this link, <a href="https://ems.element.io/user/account" target="_blank" rel="noopener noreferrer">Account Page</a>.

[![your_account](https://ems-docs.element.io/uploads/images/gallery/2023-08/scaled-1680-/image-1691055644130.png)](https://ems-docs.element.io/uploads/images/gallery/2023-08/image-1691055644130.png)

This page contains details about your account, to dleete your account, you will need to click the `Delete Account` button found at the bottom of the page.

[![](https://ems-docs.element.io/uploads/images/gallery/2023-09/scaled-1680-/image-1694420234229.png)](https://ems-docs.element.io/uploads/images/gallery/2023-09/image-1694420234229.png)

Confirm the account deletion in the following prompt to irreveribily delete all hosts and integrations you have and cancel any subscriptions. Your account will then be deleted.

[![](https://ems-docs.element.io/uploads/images/gallery/2023-09/scaled-1680-/image-1694420311450.png)](https://ems-docs.element.io/uploads/images/gallery/2023-09/image-1694420311450.png)

# 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.
1. Folgen Sie der Anleitung im Abschnitt “Einrichtung auf Ihrem Webspace”.
1. Überprüfen Sie auf <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a>, 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: <a href="https://element-hq.github.io/synapse/latest/delegate.html" target="_blank" rel="noopener noreferrer">https://element-hq.github.io/synapse/latest/delegate.html</a>

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.

- `https://unternehmen.de/.well-known/matrix/client`
- `https://unternehmen.de/.well-known/matrix/server`

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 <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a> 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`

```json
{
    "m.homeserver": {
        "base_url": "https://unternehmen.ems.host"
    },
    "m.identity_server": {
        "base_url": "https://vector.im"
    },
    "org.matrix.msc4143.rtc_foci": [
        {
            "type": "livekit",
            "livekit_service_url": "https://jwt.call.unternehmen.io"
        }
    ]
}
```

`GET /.well-known/matrix/server`

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

<a href="https://federationtester.matrix.org/" target="_blank" rel="noopener noreferrer">https://federationtester.matrix.org/</a> (Nur in englischer Sprache)

Eine grüne Fläche mit dem Wort “SUCCESS” signalisiert eine erfolgreiche Einrichtung. Auch in EMS sollten Sie nun unter <a href="https://ems.element.io/user/hosting" target="_blank" rel="noopener noreferrer">https://ems.element.io/user/hosting</a> 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.