Skip to main content

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:

  • 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
Back to top