How to migrate from Microsoft Teams to Mattermost

Move from Microsoft Teams to Mattermost: rebuild channels, sign in with Entra ID, archive the history, copy files out of SharePoint and move meetings.

Start with one workloadThe steps

Written for
The engineer who will do the work
Or run by Pilae
At a fixed price, then operated

In short

  • Mattermost has no Teams importer: the history stays in Microsoft 365 under retention, is exported as an archive through eDiscovery or the Graph APIs, or is converted by script for chosen channels.
  • Files shared in Teams live in SharePoint and OneDrive, so they are copied out separately: channel files from each team’s SharePoint site, chat files from the sender’s OneDrive.
  • Mattermost signs people in against Entra ID over OpenID Connect or SAML, directly or through Keycloak; with the full message history, single sign-on needs a paid Mattermost plan.
  • Scheduled meetings move to Jitsi Meet and one-to-one calls to Mattermost; webinars, town halls and telephony are not replaced and stay with a separate service.
On this page (15)

Moving from Microsoft Teams to Mattermost is a rebuild and an archive, not an import. Microsoft lets you export Teams messages, through eDiscovery and through the Teams Export APIs in Microsoft Graph, but neither produces anything Mattermost reads, and Mattermost publishes no Teams importer. So the work is to rebuild the structure people use, sign them in with the Entra ID accounts they already have, decide where the old history lives, copy out the files that sit behind Teams in SharePoint and OneDrive, and give meetings a home of their own. This guide covers that order, and the parts of Teams that do not move at all.

Why teams move from Microsoft Teams to Mattermost

Three reasons come up again and again.

  • Chat holds what never reaches a document. Incident threads, decisions, names and figures shared in passing. With Mattermost on your own machines, that history sits in your PostgreSQL database, in the location you choose.
  • Reachable only on your network. Mattermost can answer on a private network only, with the desktop and mobile apps as the way in. The internet never sees a login page.
  • Chat without the rest of the tenant. Mattermost does not depend on Microsoft 365. It serves the teams whose conversations must stay inside the perimeter, and it can run next to Teams for everyone else.

What you give up is the bundle. Teams puts chat, meetings, telephony, webinars and Office co-editing in one client with one sign-in. Nothing self-hosted replaces all of that in one product, and some of it is not replaced at all. Decide early whether everyone moves, or only the teams that need chat inside the perimeter while Teams stays for meetings. Both work.

Step 1: inventory what Teams is used for

Start from Microsoft’s own report. In the Microsoft 365 admin center, open Reports, then Usage, select Microsoft Teams and the Team usage tab. It lists each team with its last activity date, active users, active channels, posts and replies, over periods of up to 180 days, and Export saves it as a CSV file. Team names are hidden in reports by default: a Global Administrator shows them by clearing Conceal user, group, and site names in all reports under Settings, Org Settings, Services, Reports.

For each team you keep, write down:

  1. Channels, by type: standard, private and shared. Shared channels with other organisations have no direct equivalent.
  2. Members, including guests from outside the organisation.
  3. Meetings: recurring meetings and their owners, meetings with outside guests, webinars and town halls, phone numbers and Teams Rooms.
  4. Apps, bots and workflows that post into its channels, with their owners. A Teams workflow belongs to the person who created it, not to the channel, and is left without an owner when that person leaves, unless co-owners were added.
  5. Files: the volume in the team’s SharePoint site, and which channels use their Files tab.

Each line gets a destination: Mattermost, Jitsi Meet, Nextcloud, a service kept for it, or nothing.

In Teams After the move
Team A Mattermost team, or a set of channels in a shared team
Standard and private channels Public and private channels
Shared channel with another organisation Guest accounts on a paid plan, or a federated Element room
One-to-one and group chats Direct and group messages
Calls Mattermost Calls: one-to-one in Team Edition, group calls on paid plans
Scheduled meetings Jitsi Meet rooms
Webinars, town halls, phone system Not replaced
Channel files in SharePoint Nextcloud team folders
Chat files in OneDrive Each person’s Nextcloud files
Workflows and bots Mattermost incoming webhooks, bots or n8n workflows
Entra ID sign-in OpenID Connect or SAML, directly or through Keycloak

In Mattermost, each team has its own member list and its own sidebar, and people switch between teams to see them. We usually keep Mattermost teams for real organisational boundaries, and turn a Microsoft team that is really one project into a few channels with a common name prefix.

Step 2: decide where the Teams history lives

Mattermost’s conversion tool, mmetl, reads Slack and Rocket.Chat exports. It has no Teams input, and Microsoft offers no export in Mattermost’s format. So the history takes one of three paths, and they can be combined.

Three places the Teams history can live

Left in Microsoft 365

A Teams retention policy keeps chats and channel messages searchable through eDiscovery, including for people who leave. It works while you keep the tenant, and ends with it.

Exported as an archive

eDiscovery exports conversations as HTML transcripts, and the Graph Export APIs return every message as JSON. The archive is kept read-only, under your own retention rules.

Imported for chosen channels

A script writes the Graph export into Mattermost’s bulk import format. It is custom work, worth it for channels people still search.

Keep it in Microsoft 365

Teams keeps a copy of chat messages in a hidden folder of each participant’s Exchange mailbox, and channel messages in the team’s group mailbox. A retention policy for the Teams chats and Teams channel messages locations keeps them, and eDiscovery finds them. If a person’s account is deleted while such a policy applies, their mailbox becomes an inactive mailbox that keeps the chats. This path suits an organisation that moves chat but keeps Microsoft 365 for mail and documents. It does not survive closing the tenant.

Export an archive through eDiscovery

In the Microsoft Purview portal, open eDiscovery, then Cases. In a case, run a search over the people and teams in scope, select it and choose Export. Turn on Organize conversation into HTML transcript, which threads chat messages into readable transcripts, and choose PST or .msg files for the messages. The account that exports needs a Microsoft 365 E3 or E5 licence, and search exports are deleted 14 days after they are created, so download them straight away. Microsoft documents the options in Export search results in eDiscovery.

Export through the Teams Export APIs

For a complete, machine-readable copy, an application registered in Entra ID calls the Teams Export APIs: getAllMessages for each user’s chats, which covers one-to-one, group and meeting chats, and for each team’s channels. It needs the application permissions Chat.Read.All, ChannelMessage.Read.All and User.Read.All, granted by an administrator. Three details matter:

  • Each message once. The chat export reads every user’s own copy, so exporting all members of a chat returns its messages once per member. Deduplicate by chat and message ID.
  • Links, not files. Attachments come back as metadata and links into SharePoint and OneDrive. The files themselves are copied in step 4.
  • Before the licences go. Microsoft requires an active Teams licence on the users whose data is exported, and reaches a deleted user’s messages for only 30 days. Run the export before anyone’s licence is removed.

Import the channels that justify it

Mattermost documents its bulk import format: a JSONL file of teams, channels, users, and posts with their replies, reactions and attachments, loaded with mmctl import. A script can turn the Graph channel export into that format, matching people by email address so the history lands under the right accounts. It is custom work, worth doing for the handful of channels people still search, not for every chat. We agree the list before quoting.

Step 3: set up Mattermost and Entra ID sign-in

People already have an Entra ID account, and the move goes best when that is the account they use in Mattermost. Single sign-on is part of the paid Mattermost plans. The free Team Edition signs people in with email and password, and Mattermost positions it for teams under 250 activated users. People can add a second factor there, but making one mandatory is a licensed feature.

  • OpenID Connect with Entra ID. Register an application in Entra ID with the redirect URI https://<your-server>/signup/office365/complete and a client secret. In Mattermost, open System Console, Authentication, OpenID Connect, choose Entra ID as the provider and enter the tenant ID, client ID and secret.
  • SAML with Entra ID. An enterprise application in Entra ID signs people in over SAML, and Mattermost creates each account the first time its owner signs in. Set an ID attribute in Mattermost, so that a changed email address does not create a second account.
  • Through Keycloak. Keycloak brokers to Entra ID, so Microsoft stays the directory, and Mattermost, Jitsi Meet and Nextcloud all sign in through one place.

Then create the teams and channels from the inventory, before anyone arrives. With single sign-on, accounts appear as people first sign in, so public channels are joined by their members and private channels are filled by their owners, or by script with mmctl once the accounts exist. Syncing directory groups to teams and channels automatically is a Mattermost Enterprise feature.

Step 4: copy the files that sit behind Teams

Teams stores no files of its own. Before any account closes, find them where Microsoft puts them:

  • Channel files are in the SharePoint site connected to the team. Each standard channel is a folder in the site’s default document library, and each private or shared channel has a SharePoint site of its own. Recordings of channel meetings sit in a Recordings folder there.
  • Files sent in chats are in the sender’s OneDrive, in a folder named Microsoft Teams Chat Files, shared with the people in that chat.
  • Recordings of other meetings are in the organiser’s OneDrive, in its Recordings folder.

Copy each channel folder into a Nextcloud team folder and put the folder’s link in the Mattermost channel header, so the files are one click from the conversation, as they were in Teams. The copy runs from a server with rclone: its OneDrive backend reads SharePoint document libraries and OneDrive for Business, it writes to Nextcloud over WebDAV, and a second pass copies only what changed. Chat files and recordings move with each person’s OneDrive; if you are leaving SharePoint and OneDrive altogether, that is a project of its own, covered in our guide to moving SharePoint to Nextcloud.

Copy before the accounts close. Links in the exported messages point into SharePoint and OneDrive and stop resolving once those sites and accounts are deleted, so the archive is complete only with the files beside it.

Step 5: give meetings and integrations a new home

Calls and meetings

  • Calls inside Mattermost. Mattermost Calls gives one-to-one voice calls with screen sharing in the free Team Edition. Group calls need a paid Mattermost plan, and recording and transcription need Mattermost Enterprise.
  • Scheduled meetings move to Jitsi Meet, which Pilae runs beside Mattermost. Guests join from a link in the browser, and each recurring invite is re-sent by its owner with a standing room address.
  • Webinars, town halls, telephony and Teams Rooms are not replaced. Organisations that rely on them keep a service for those.
  • Teams kept for meetings. If meetings stay in Teams, Mattermost’s Microsoft Teams Meetings plugin starts a Teams meeting from a channel with /mstmeetings start. It needs an app registration in Entra ID with the delegated OnlineMeetings.ReadWrite permission.

Webhooks, workflows and bots

Teams now receives webhooks through Workflows, built on Power Automate, which accept Adaptive Card and MessageCard payloads; the older Office 365 connectors are retired. Mattermost incoming webhooks accept Slack-format payloads instead, so each sender changes its format as well as its URL. Many monitoring and CI tools can post to Mattermost directly or in Slack’s format. For the rest, an n8n workflow receives the old payload and posts it to Mattermost. Power Automate flows and Teams bots are rebuilt as n8n workflows or Mattermost bot accounts, each with a named owner. Keep each Teams workflow running until its replacement has posted once.

Step 6: run in parallel, then switch team by team

The switch, in order

  1. Clients: Desktop and mobile apps are installed before the switch, and sign-in through Entra ID is tested on each.
  2. Pilot: One team moves first, and what it finds changes the channel structure and the user guide before anyone else moves.
  3. Switch: On its agreed day, each team stops posting in Teams. Archiving the team in the Teams admin center stops all activity and keeps it readable, and an archived team can be restored if you need to roll back.
  4. Final export: The history export runs after the last team has switched, so the archive holds the final messages.
  5. Close: Teams licences are removed only once the export and the file copy are checked, because the Export APIs need an active licence.

Chats cannot be archived the way a team can. Announce the date, and ask people to carry live conversations over to Mattermost direct messages from that day.

Running Mattermost in production

A Mattermost server that replaces Teams for a department needs:

  • PostgreSQL for every message, channel and user, backed up daily.
  • S3-compatible object storage for attachments, kept apart from the database so each can be sized and restored on its own.
  • An SMTP relay for invitations and notification emails when someone is offline.
  • Push notifications. Mobile notifications pass through a push proxy run by Mattermost, unless you run your own proxy with your own build of the mobile apps.
  • Compliance features, if you used Purview. Organisations used to Teams retention policies and eDiscovery should know that Mattermost’s counterparts, data retention policies and compliance exports, are Mattermost Enterprise features.

Pilae operates Mattermost this way, with the database and file storage separated from the application from the first day, daily encrypted backups stored at a second site in the same jurisdiction, and on Pilae’s Enterprise plan a restore test every month, recorded in the console. It runs on your premises or on dedicated machines in Pilae Cloud, answering on your private network with one hardened gate for mobile clients. Where messages must be end-to-end encrypted, or rooms shared with partner organisations on their own servers, Element on Matrix is the other answer. For the wider comparison, see our page on Microsoft Teams alternatives.

Let Pilae run the move

Pilae runs Microsoft Teams to Mattermost migrations at a fixed price: the inventory, sign-on through Entra ID or Keycloak, the channel structure, the history export or import you choose, the file copy, Jitsi Meet for meetings, the integration rebuild and a team-by-team switch. Where your requirements need a paid Mattermost plan, the licence is named in the proposal. Then we operate Mattermost for you with backups, monitoring and upgrades under one contract. See migration services for what the fixed price covers, or tell us how your teams work today and we will scope it.

Questions

Can we import our Teams history into Mattermost?

Not directly. Microsoft exports Teams messages through eDiscovery and the Teams Export APIs in Microsoft Graph, and Mattermost has no importer for either: its conversion tool reads Slack and Rocket.Chat exports. History stays in Microsoft 365 under retention, is kept as an exported archive, or is converted by script into Mattermost's bulk import format for the channels that justify it. We agree which before quoting.

What happens to the files shared in Teams?

They were never stored in Teams. Channel files sit in the SharePoint site connected to each team, and files sent in chats sit in the sender's OneDrive. They are copied out separately, usually into Nextcloud, before the Microsoft 365 accounts close.

Does Mattermost replace Teams meetings?

In part. Mattermost Calls gives one-to-one calls with screen sharing in the free Team Edition, and group calls on the paid plans. Scheduled video meetings with outside guests move to Jitsi Meet, which we run beside Mattermost. Webinars, town halls and telephony are not replaced: organisations that rely on them keep a service for those, and we say so in the proposal.

Can people sign in with Microsoft Entra ID?

Yes, through OpenID Connect or SAML, either directly against Entra ID or through Keycloak brokering to it. With the full message history, single sign-on needs a paid Mattermost plan, so we include the Mattermost licence question in the proposal.

Is Mattermost open source?

The source is: the server under AGPL-3.0, and the compiled Team Edition that Mattermost builds under MIT. Mattermost positions Team Edition for teams under 250 activated users and has removed single sign-on from it, and its free Entry edition shows only the most recent 10,000 messages, so most organisations leaving Teams need a paid Mattermost plan, which Mattermost licenses directly. We tell you which one in the proposal.

How long does a Teams to Mattermost migration take?

It depends on what Teams is used for, not on how many messages it holds. Chat alone is a structure rebuild and a sign-on project; meetings, files in SharePoint and integrations each add their own work, and the decision on history changes the scope most. The inventory in step 1 settles it, and Pilae quotes the move at a fixed price once it is done.

Let us run the move for you

An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.

Start with one workload

  • Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
  • CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.