Integrations

Admin Bot

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

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

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

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

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

Use case examples

Good to know

See also

AdminBot for global room administration.

Setup

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

The Admin Bot integration page ends with a "Set Up Integration" button.

Usage

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

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

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

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

Removal

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

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

Audit Bot

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

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

Use case examples

Good to know

See also

AuditBot for regulation and compliance.

Setup

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

Optional export

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

Usage

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

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

Removal

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

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

Create a Conference Call in a Room

Setting up

  1. Create a room
    temp

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

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

  4. Select Jitsi from the list of available widgets
    temp

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

  6. Click the X to close the integration manager
    temp

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

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

  9. You are now in the conference
    temp

Inviting external participants

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

  2. Click Copy
    temp

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

Screen sharing

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

  2. Give permissions when asked

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

  4. Everyone can now see your screen
    temp

Discord Bridge

Setup

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

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

Authorize your account

Before authorizing your Discord App, you first need to grant your account the following rights:

  1. Manage Weebhooks
  2. Manage Server

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.
    Discord showing Channel ID in URL bar
  2. In a Matrix room you want to bridge, invite @discord:example.ems.host (replace the domain with the one of your homeserver).
  3. Post the message !discord bridge GUILD_ID CHANNEL_ID after replacing the two placeholders.
    Element showing the Discord bridge command
  4. A privileged Discord user will need to approve the bridge request by responding with !matrix approve
    Discord message showing the approve command
  5. Messages from Discord are now bridged to Matrix and vice versa.
    Element showing a message bridges from Discord

Unbridge

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

Private Chats

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

Google SAML

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

See also Delegated Authentication for single sign-on (SSO) integration.

Setup

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

Update metadata

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

Upload metadata to EMS

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

DRAFT Okta SAML

These instructions are a draft and might not be accurate

Hookshot

Dedicated Hookshot instances are available for EMS Enterprise customers. To request Hookshot added to your server, please talk to 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:

Send the following information to your Element contact:

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 Delegated Authentication for single sign-on (SSO) integration.

Setup

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

Configure Your EMS Server

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

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.

See also Delegated Authentication for single sign-on (SSO) integration.

Google

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

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

In the Element Matrix Services configuration form

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

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

GitHub

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

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

In the Element Matrix Services configuration form

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

GitLab

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

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

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

In the Element Matrix Services configuration form

Public IRC Bridges

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

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

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

Public Slack Bridge

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

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

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

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

An EMS server is not required.

Setup

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

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

  3. Click Add widgets, bridges & bots
    temp

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

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

  6. Click Add to Slack
    temp

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

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

  9. Click Allow
    temp

  10. Close the Slack tab and return to Element
    temp

  11. Click List channels
    temp

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

  13. Slack is now added to the Matrix room
    temp

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

  15. Add the Element Bridge

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

Signal Bridge

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

It requires your EMS server to have federation on.

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

Purchase the Signal integration

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

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

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

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

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

Bridge Signal to your Element account

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

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

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

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

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

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

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

Sending a message to a Signal User

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

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

Why do Signal user names show up as phone numbers?

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

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

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

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

Slack Bridge

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

Purchase the Slack integration

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

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

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

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

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

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

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

Setup

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

Initiate a DM with a Slack user from Matrix

Teams Bridge

Introduction

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

Setup

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

  1. In the Teams app, not the admin page. Click the three dots next to your Teams, then Get link to team
  2. Click Copy
  3. Paste this link into the Teams Link field on the Teams Bridge setup form on https://ems.element.io/user/hosting#/integrations
  4. Click Link Teams to Element
  5. 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 Azure Active Directory page.
  2. Click users.
  3. Click New user.
  4. Ensure Create user is selected.
    • Enter a User name ex. matrixbridge.
    • Enter a Name ex. Matrix Bridge.
    • Enter an Initial password.
    • Create the user.
    • Optionally, set more profile details like an avatar.
  5. You will now need to log in as this new bot user to set a permanent password (Teams requires you to reset the password on login).
  6. After logging in you should be prompted to set a new password.
  7. Enter the bot username and password into the integration form.

Welcome room

Users can be automatically prompted to link their Teams account to their Element account when they join 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

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.

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

Known limitations

Telegram Bridge

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

It requires your EMS server to have federation on.

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

Purchase the Telegram integration

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

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

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

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

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

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

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

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

Bridge Telegram to your Element account

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

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

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

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

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

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

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

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

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

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

Bridging Matrix users without a Telegram acccount

By default, a Matrix user will have to connect their Telegram account for their messages to be bridged to Telegram. If you provide a bot token, we will use this bot to relay the messages of any Matrix users to Telegram. (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 @BotFather. 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).

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

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

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

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

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

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

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

WhatsApp Bridge

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

It requires your EMS server to have federation on.

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

Purchase the WhatsApp integration

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

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

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

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

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

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

Bridge WhatsApp to your Element account

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

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

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

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

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

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

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

Sending a message to an WhatsApp User

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

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

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

From WhatsApp's documentation:

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

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

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.

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.

  2. Select the bot you are migrating (Feeds or GitHub).

  3. Press Add to add the new bot to the room.

  4. Set up the new bot. Any configurations you added previously will be shown under Migrate connections.

    • Migrate connections will only appear for the user who originally added the old bot.
    • When migrating GitHub, it may be necesssary to log in again.

  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 vector-im/element-integration-manager.

Some bots won't be available anymore

The following bots will also be deprecated, but unfortunately do not have a new version available: