Connect Microsoft Teams to Mattermost#

plans-img Available on Enterprise plans

deployment-img Cloud and self-hosted deployments

intro here

Setup#

Setup starts in Mattermost, moves to Microsoft Teams, and ends in Mattermost.

Install the Microsoft Teams integration in Mattermost#

  1. Log in to your Mattermost workspace as a system administrator.

  2. Download the latest version of the plugin binary release, compatible with Mattermost v8.0.1 and later. If you are using an earlier version of Mattermost, follow our documentation to upgrade to Mattermost v8.0.1 or later.

  3. Go to System Console > Plugins > Plugin Management > Upload Plugin, and upload the plugin binary you downloaded in the previous step.

  4. Go to System Console > Plugins > Plugin Management. In the Installed Plugins section, scroll to MS Teams, and select Enable Plugin.

Set up an OAuth application in Azure#

  1. Sign into portal.azure.com using an admin Azure account.

  2. Navigate to App Registrations.

  3. Select New registration at the top of the page.

In Azure, create a new app registration.

  1. Fill out the form with the following values:

  • Name: Mattermost MS Teams

  • Supported account types: Default value (Single tenant)

  • Platform: Web

  • Redirect URI: https://(MM_SITE_URL)/plugins/com.mattermost.msteams/oauth-redirect

Replace (MM_SITE_URL) with your Mattermost server’s Site URL. Select Register to submit the form.

In Azure, register the new Mattermost app.

  1. Navigate to Certificates & secrets in the left pane.

  2. Select New client secret. Enter the description and select Add. After the creation of the client secret, copy the new secret value, not the secret ID. We’ll use this value later in the Mattermost System Console.

In Azure, enter client secret details.

  1. Navigate to API permissions in the left pane.

  2. Select Add a permission, then Microsoft Graph in the right pane.

In Azure, manage API permissions for the Mattermost app.

  1. Select Delegated permissions, and scroll down to select the following permissions:

  • Channel.ReadBasic.All

  • ChannelMessage.Read.All

  • ChannelMessage.ReadWrite

  • ChannelMessage.Send

  • Chat.Create

  • Chat.ReadWrite

  • ChatMessage.Read

  • Directory.Read.All

  • Files.Read.All

  • Files.ReadWrite.All

  • offline_access

  • Team.ReadBasic.All

  • User.Read

  1. Select Add permissions to submit the form.

  2. Next, add application permissions via Add a permission > Microsoft Graph > Application permissions.

  3. Select the following permissions:

  • Channel.ReadBasic.All

  • ChannelMessage.Read.All

  • Chat.Read.All

  • Files.Read.All

  • Group.Read.All

  • Team.ReadBasic.All

  • User.Read.All

  1. Select Add permissions to submit the form.

  2. Select Grant admin consent for… to grant the permissions for the application.

Create a user account to act as a bot#

  1. Create a regular user account. We will connect this account later from the Mattermost side.

  2. This account is needed for creating messages on Microsoft Teams on behalf of users who are present in Mattermost but not on Microsoft Teams.

  3. This account is also needed when users on Mattermost have not connected their accounts and some messages need to be posted on their behalf. See the screenshot below:

    In Microsoft Teams, create a user account to act as a bot.

Note

After you’ve connected the bot user to the account on Microsoft Teams, all the messages that are posted from the account on Microsoft Teams won’t be synchronized back to Mattermost since it’s a “bot”, and messages from bots are ignored.

Ensure you have the metered APIs enabled (and the pay subscription associated to it)#

Follow the steps here: https://learn.microsoft.com/en-us/graph/metered-api-setup

Important

If you don’t configure the metered APIs, you must use the Evaluation model (configurable in Mattermost) that is limited to a low rate of changes per month. We strongly recommend that you avoid using the Evaluation model configuration in live production environments because you can stop receiving messages due the rate limit. See this Microsoft documentation for more details.

You’re all set for configuration inside Azure.

Configure how users connect accounts#

Mattermost admins can configure Mattermost to automatically prompt users to connect their Mattermost user account to their Microsoft Teams user account on login.

  1. Go to System Console > Plugins > MS Teams.

  2. Enable Enforce connected accounts to prompt users to connect if they haven’t done so.

  3. (Optional) Enable Allow to temporarily skip connect user to allow users to skip the connection prompt temporarily. Users are prompted on refresh and login.

Mattermost configuration#

Additional configuration settings are available for this plugin. See the Microsoft Teams plugin configuration settings documentation for details.

Monitor performance#

You can set up performance monitoring and performance alerting for this plugin using Prometheus and Grafana.

  • Monitoring enables you to proactively review the overall health of the plugin, including database calls, HTTP requests, and API latency.

  • Alerting enables you to detect and take action as issues come up, such as the integration being offline.

Grafana dashboards are available on GitHub for Mattermost Cloud deployments as a useful starting point. These dashboards are designed for use in Mattermost Cloud, and filter to a given namespace.

Example of a Grafana monitoring dashboard for a Mattermost instance connected to Microsoft Teams.

Note

Modifications will be necessary for self-hosted Mattermost deployments. See the Get help section below for details on how to contact us for assistance.

Usage#

Collaborate within Microsoft Teams (Pilot)#

The Mattermost for Microsoft Teams plugin integration enables you to collaborate with Microsoft Teams users without leaving Mattermost.

Mattermost Academy Learn about integrating with Microsoft Teams

Connect your Mattermost account to your Microsoft Teams account#

To use the Microsoft Teams plugin, you must connect your Mattermost user account to your Microsoft Teams account. You only need to complete this step once.

  1. Log into Mattermost using your credentials.

  2. When you log in, you’ll be prompted to enter your Microsoft Teams user information, including your Microsoft Teams email address and your Microsoft Teams password.

Note

  • To change which accounts are linked, in Mattermost, disconnect the current account by running the slash command /msteams disconnect within the Mattermost message text box. Then, re-connect a new Mattermost account to a new Microsoft Teams account by running the Mattermost slash command /msteams connect.

  • If your Microsoft Teams user account is removed from Microsoft Teams, your linked Mattermost user account will also be removed the next time user accounts are synchronized across the two platforms.

Mattermost will confirm when your account is connected, and prompt you to select your primary platform.

Select your preferred platform#

Once you’ve connected your Mattermost account to your Microsoft Teams account, Mattermost prompts you to choose which platform you’ll use more often: Mattermost or Microsoft Teams. Mattermost optimizes your experience based on the platform you prefer to use.

Note

  • If you’re not prompted to connect your accounts, run the Mattermost slash command /msteams connect within the Mattermost message text box to display the prompt in a browser window. Follow the link to connect your accounts.

  • If you select Skip for now, Mattermost is selected as your primary platform. You can change this preference any time by selecting your profile picture and going to Settings > MS Teams Settings.

Mattermost is your preferred platform#

When Mattermost is preferred, you’ll receive Microsoft Teams messages and notifications in Mattermost.

We recommend that you disable notifications in Microsoft Teams. If you don’t, you’ll receive duplicate message notifications in both platforms. See the Microsoft Teams notifications documentation for details.

Microsoft Teams is your preferred platform#

When Microsoft Teams is preferred, you’ll receive messages from Mattermost in Microsoft Teams. Mattermost notifications are automatically muted for you to prevent duplicate notifications.

Setup complete#

Setup is complete! You’re ready to collaborate across your organization. Interact with colleagues in Microsoft Teams without having to leave Mattermost.

Get started#

You can start a direct or group message between Mattermost and Microsoft Teams users unless your Mattermost administrator has disabled the ability to do so in the System Console.

  • Within Mattermost select the Open menus using the plus icon. icon next to Direct Messages in the left pane, then search for the user you want to message. Your direct or group conversation is visible in both Mattermost and Microsoft Teams.

  • Within Microsoft Teams, select Chat > New chat, and select the users you want to chat with. Your conversation is visible in both Mattermost and Microsoft Teams for all users who have connected their Mattermost user account to their Microsoft Teams user account.

An example of a Mattermost direct message (DM) that is synced with a DM on Microsoft Teams.

Collaborate within embedded Microsoft Teams (Demo)#

The Mattermost for Microsoft Teams plugin enables you to collaborate with technical & operations teams seamlessly through the Mattermost app, without leaving Microsoft Teams.

Demonstration: Mattermost embedded in Microsoft Teams#

Check out this YouTube demo, from John Landells, Senior Technical Account Manager at Mattermost, to learn more about using the embedded Mattermost instance within Microsoft Teams:

Frequently asked questions#

Can I connect my Mattermost account to a Microsoft Teams account of a different email address?#

No. Currently, only accounts with the same email addresses are allowed to be connected. Specify the email address that matches your Mattermost account.

If connecting a Mattermost account to a Microsoft Teams account with a different email address is something your workspace requires, there is an open GitHub issue for you to share your feedback.

Get help#

If you face issues while installing this plugin, gather relevant information, including reproduction steps to accelerate troubleshooting. You’re welcome to open a new issue in the Mattermost for Microsoft Teams GitHub repository.