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.

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.

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.

  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.

  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

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

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

  4. Select Jitsi from the list of available widgets

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

  6. Click the X to close the integration manager

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

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

  9. You are now in the conference

Inviting external participants

  1. Click the info button in the bottom right corner

  2. Click Copy

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

Screen sharing

  1. Click the screen sharing in the bottom left corner

  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

  4. 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 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 Webhooks
  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.
  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.
  4. A privileged Discord user will need to approve the bridge request by responding with !matrix approve
  5. Messages from Discord are now bridged to Matrix and vice versa.

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

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 added previously will be shown under Migrate connections.

    • 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 element-hq/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:

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.

Setup

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