Migrate from Microsoft Teams to Matrix and Element

Migrate from Microsoft Teams to Matrix and Element: what the move involves

A move from Microsoft Teams to Matrix and Element is usually triggered by a renewal, a licensing change or a data residency requirement, and it involves four workstreams: exporting history through Microsoft Graph, rebuilding teams and channels as Matrix spaces and rooms, standing up Synapse with Element and Element Call, and running old and new side by side until users have moved. Most organizations hand this to an internal platform or infrastructure team with help from an implementation partner, because the work crosses identity, networking, databases and meeting infrastructure rather than being a single application install. The effort depends mainly on three things: how much chat history must be retained, how deeply the new servers must integrate with the existing identity provider, and how far the meeting scope reaches beyond Element Call into calls with external guests or large audiences.

The export step is the one most often underestimated. The Teams Export APIs in Microsoft Graph require admin-approved application permissions, and they only return content for users who hold an active Teams license, so any user who has left the organization or lost a license may need a separate retention decision before the export starts. Confirm with your Microsoft 365 administrator which users, teams and retention policies apply, and agree in writing which history will be imported, since messages, files and meeting artifacts each follow their own path into Matrix. Mapping is the second decision: teams and channels become spaces and rooms, so naming, room visibility and who can create rooms need a documented model before any data is loaded.

Cutover is where a chat-only move and a chat-plus-meetings move diverge. Synapse, the most widely documented Matrix homeserver, needs PostgreSQL in production and a worker layout with Redis if load grows, and its upgrade notes warn that rolling back after schema changes can be difficult, so test upgrades on a copy before the first production release. Single sign-on through OIDC, SAML2 or CAS must be configured and tested with real accounts, and Element Call needs its own media path that you must size and place. Plan a parallel-running period with clear rules on where new conversations start, and treat the cutover date as a decision for the business owners, not only for the platform team. Ask any partner to put the export, mapping, server build and cutover tasks in a written, fixed scope with named deliverables.

Which Teams capabilities map cleanly to Matrix and Element

This table compares the main Teams capabilities with Matrix spaces and rooms, Element clients, Element Call and Synapse. Read each row as a planning signal: clean means a direct equivalent exists, needs rework means the feature exists but your data or processes must change, and gap means you need a different tool or a custom build. Confirm meeting scale, recording behavior and admin controls against the current vendor documentation before committing.

Capability	Matrix and Element fit	Status	Where to confirm
Channel chat and threads	Rooms inside a space, with threaded replies in Element clients	Clean	Element client help and Matrix spec for threads
Teams and channels structure	Spaces and rooms replace teams and channels, so hierarchy must be redesigned	Needs rework	Map each team to a space and each channel to a room in a pilot
1:1 and group chat	Direct messages and group rooms with encryption available per room	Clean	Element client settings for end-to-end encryption
Chat history from Teams	Graph export gives messages as data, but there is no direct Teams importer for Synapse, so conversion is required	Needs rework	Microsoft Learn Teams Export APIs and your import tooling plan
File sharing	Files attach to messages and are stored by the homeserver media repository, with no SharePoint document library equivalent	Needs rework	Synapse media configuration and storage sizing
Meetings and video calls	Element Call runs over a self-hosted LiveKit server, with scale limits set by your infrastructure	Needs rework	Element Call and LiveKit documentation for participant limits
Meeting recording and transcripts	Recording and transcription in Element Call are not equivalent to Teams Stream recordings	Gap	Element Call release notes and your recording requirement
Single sign-on	Synapse supports OpenID Connect, SAML2 and CAS through its configuration	Clean	Synapse configuration manual for oidc_providers and saml2_config
Admin and retention controls	Server-side admin tools and retention settings exist, but Teams-style compliance eDiscovery is not built in	Gap	Synapse admin API documentation and your compliance team's control list

What data can be exported from Teams and what must be rebuilt

The Teams export path covers message history and meeting artifacts, but it does not carry over the identity, integration and configuration layer around them. Plan the export as a data job and the rebuild as a separate workstream with its own owners and checks.

Message history through Graph

The Microsoft Graph Teams Export APIs return 1:1, group, meeting and channel messages, which is the documented route for pulling chat history out of Teams. Confirm early which conversation types your tenant uses most, because channel and private chat content may need different handling before import into Matrix rooms. Ask your Microsoft 365 administrator to confirm the exact export scope in your tenant before the project starts.

Meeting recordings and transcripts

The same export APIs return links to meeting recordings and transcripts, not the media themselves in a Matrix-ready format. Decide whether these artifacts move into Nextcloud or another file store, or stay in Microsoft 365 as read-only references. Check retention and access rules on each link before you copy any files out.

Admin-approved application permissions

Exporting content requires application permissions that an administrator must approve in Microsoft Entra ID. Document who approves them, which tenant hosts the export app, and how the approval is revoked after the migration. Treat the export credential as privileged access that is logged and rotated.

Active Teams licenses on exported users

Microsoft documents that the export APIs need an active Teams license on each user whose content is exported. Former employees and unlicensed guest accounts may therefore be unreachable, which creates gaps in the history. Build a list of users and licenses before cutover and agree with legal how to handle content that cannot be exported.

Identities and single sign-on

Teams users sign in through Entra ID, and those accounts do not move into Matrix. Plan the identity provider in Matrix, whether OIDC, SAML or CAS in Synapse, and map each Entra ID user to a stable Matrix user ID under your server_name. Confirm group claims and deprovisioning behavior with your identity team.

Bots, connectors and apps to rebuild

Teams apps, bots, Power Automate flows and channel connectors do not transfer into Matrix. List every connector per team, record its purpose and owner, then rebuild each one as a Matrix bot, bridge or webhook where the need still exists. Retire connectors that no longer serve a purpose instead of recreating them by default.

How to sequence the Teams to Matrix migration

This sequence moves Teams chat history and channel structure into a self-hosted Matrix server in an order that protects retained records, tests the path with real users, and keeps a rollback option until the new service is proven.

Inventory teams, channels and retention needs
The IT owner and the compliance lead list every team, standard and private channel, and chat group in scope, along with the owners, member counts and the retention period each record class must meet. Include meeting recordings and transcripts, since the Graph export covers them too. The output is a channel inventory with a retention column and a list of records that must be kept, which is done when the compliance lead signs it off and every item has a named owner.
Confirm Graph permissions and Teams licenses
The Microsoft 365 administrator checks that the Teams Export APIs can be used for the tenant, that the admin-approved application permissions are granted, and that every user whose content will be exported holds an active Teams license. Accounts without a license can cause gaps in the export, so the team should confirm this before any data is pulled. The output is a permissions and license checklist, and the step is done when a test export of one channel returns the expected messages.
Design the channel-to-space map
The platform team maps each Teams team to a Matrix space and each channel to a room, decides which rooms are public, invite-only or encrypted, and records how membership and admin roles will be recreated. Teams and Matrix differ in structure, so the design should state where a Teams feature has no direct equivalent. The output is a channel map and a naming standard for server_name and room aliases, and the step is complete when the owners of each space have approved their entries.
Run a pilot with a small group
A small group of users from one business unit moves to the new Matrix server with Element and Element Call, and the pilot team tests sign-in through the chosen identity provider, notification behavior, file handling and calls on real devices. Exported history for the pilot channels is loaded into a staging homeserver so the team can check how it appears. The output is a pilot report listing defects, workarounds and user feedback, and the step closes when the report is reviewed and each blocking issue has a fix or an accepted risk.
Export through Graph and convert for Matrix
Engineers pull message history with the Microsoft Graph Teams Export APIs, store the raw output in an encrypted location with restricted access, and convert it into a form Matrix tooling can load. Matrix does not provide a Teams importer, so this conversion is custom work, and the team should test it against the pilot data before the full run. The output is a converted dataset and a log of skipped or failed items, which is verified when a sample of messages, attachments and timestamps matches the source.
Operate a parallel run and archive
Teams and Matrix run side by side for a period set by the business, with users told which system is the system of record for each space and where new conversations should happen. The archive team compares message counts and sampled content between the source export and the loaded data, and keeps the verified archive under the retention rules from the first step. The output is a verified archive and a parallel-run log, and the step is complete when discrepancies are resolved or documented.
Cut over with a rollback plan
The team switches users to the Matrix server, updates links and bookmarks, and sets Teams channels to read-only where the retention plan requires it. A written rollback plan states who can reverse the cutover, which backups of the Synapse database and media store are used, and the conditions that trigger a reversal. The output is a signed cutover record and a tested rollback procedure, and the step is done when the owners confirm that sign-in, messaging and calls work for all migrated users.
Decommission Teams content and document the result
After the agreed period passes without a rollback, the team removes Teams access for migrated users, disables the export application, and removes the copies of exported data that retention rules no longer require. The platform team documents the final state, including the channel map, admin roles and retention settings. The output is a decommission record and an operations handover, and the step closes when the compliance lead confirms that the retained archive is accessible and the Teams tenant no longer holds the content.

How the migration changes by organization size and starting point

A small team with few channels has the lightest migration. History volume is usually modest, identity can often stay local, and the main risk is treating the move as a copy exercise when the team's habits will change. Matrix is built around rooms and spaces rather than Teams-style teams and channels, so a small team benefits from agreeing on a simple space layout before anyone is invited. Federation is rarely needed for a single company, so the server_name can be fixed to the organization's domain and federation disabled.

Export volume: Check how many channels, direct messages and meetings exist before requesting Graph exports. A small tenant may finish quickly, but the export still needs admin-approved application permissions and an active Teams license on each exported user.
Identity: Local accounts may be acceptable for a few users, but confirm whether your Microsoft 365 tenant already provides single sign-on you want to keep.
Federation: Setting federation_domain_whitelist to an empty list disables federation, which fits an internal-only deployment.
Support needs: Decide who runs upgrades. Synapse upgrade notes warn that rolling back can be difficult, so one person needs a tested upgrade routine.
Element Server Suite: Element positions its free Community edition for non-professional use and evaluations, so confirm its terms before using it for daily work.

Before you start, confirm the licensing terms of each Element Server Suite edition with Element.

What usually goes wrong and how to prevent it

Most failed Teams-to-Matrix migrations fail in the same few places: the export, the room design, the network exposure, the database and runtime versions, and the people who never moved. The cards below pair each risk with a check to run before cutover, so the team can confirm the controls rather than assume them.

Incomplete exports from missing permissions

The Teams Export APIs in Microsoft Graph need admin-approved application permissions, and they only return content for users who hold an active Teams license. A user without that license can leave a gap in the history you think you have. Before extraction, build a list of every user and channel in scope, confirm each one is licensed, and compare the export counts against a sample checked by hand. Record the gaps in writing so the business owners accept them.

Poor mapping of teams to spaces

Teams has teams, channels, private channels and chats, while Matrix uses spaces, rooms and direct message rooms. Mapping one team to one space without design often produces dozens of stray rooms, duplicated membership and private content visible to the wrong people. Write the mapping table before migration, decide which rooms are public, invite-only or encrypted, and assign a room owner for each. Test access with a sample of accounts from each group.

Unplanned federation exposure

Synapse federates by default on port 8448, and a misconfigured server_name or open listener can expose rooms to other homeservers. Federation is a policy decision for a regulated organization, not a default to accept. Set federation_domain_whitelist to the domains you intend to trust, or to an empty list if you want no federation, and firewall the federation listener as the Synapse documentation recommends. Verify the result from outside your network before go-live.

Rollback difficulty after a Synapse upgrade

The Synapse upgrade notes warn that rolling back can be difficult because database schema changes between releases are not reversible in practice. A failed upgrade without a tested restore path can leave the homeserver unusable during the parallel run. Take a full PostgreSQL backup and a copy of the configuration before every upgrade, rehearse the restore on a staging copy, and read the release notes for each version between your current and target release. Keep the upgrade window short and documented.

Unsupported PostgreSQL or Python versions

Synapse drops support for Python and PostgreSQL versions once they reach upstream end of life, and recent Synapse releases require PostgreSQL 14 or newer and Python 3.10 or newer. A host built on an older database or interpreter can block an upgrade that otherwise looks routine. Inventory the database and runtime versions before choosing a target Synapse release, plan operating system or database upgrades ahead of the homeserver upgrade, and confirm the minimum requirements in the release notes for your target version.

User adoption gaps in the parallel run

During a parallel run, people keep posting in Teams because it is familiar, so Matrix rooms stay quiet and the cutover date becomes a surprise. Meeting links, mobile notifications and single sign-on are the usual friction points. Set a cutover date in writing, name a champion in each business unit, and publish a short guide covering sign-in, rooms and notifications. Track active users per room weekly, and agree in advance which Teams channels become read-only at cutover.

What drives the cost and duration of this migration

The cost of moving from Teams to Matrix and Element splits into one-time migration work and recurring operations, and the two are priced very differently. One-time work covers mapping Teams and channels to spaces and rooms, extracting history through the Microsoft Graph Teams Export APIs, building and checking the Synapse, PostgreSQL, Redis and media stack, configuring single sign-on, and cutover testing. Most of the internal staff time falls here, and it grows with the number of teams, channels, retained years of history and identity providers involved. Ask any implementation partner to price each of these as a separate line, so you can see which items are fixed and which depend on your data volume.

Recurring costs are hosting and people. Hosting covers compute for the Synapse main process and workers, a PostgreSQL database (Synapse recommends PostgreSQL for production and requires version 14 or newer from release 1.143.0), Redis for worker replication, and media and call infrastructure. Element's Server Suite licensing is the other recurring decision: the free AGPL Community edition includes Synapse and Element Call, while the Pro edition adds Synapse Pro and paid support terms. Confirm with Element which features and support levels each edition includes for your use, because Element's pricing page is the authoritative source. Ongoing operations also include upgrades, which Synapse's upgrade notes warn can be hard to roll back because of schema changes, plus monitoring, backups and on-call coverage.

When requesting a written quote, ask for: the scope of history to migrate and the export permissions required, the Element edition and any support tier, sizing assumptions for users, concurrent calls and storage, the assumed number of environments, who holds the Graph application permissions and Teams licenses during extraction, and the upgrade and backup responsibilities after go-live. Ask how the quote treats retained history that the Teams Export APIs cannot return, and what happens if the cutover window slips. A fixed-scope quote with these assumptions written out lets you compare offers and identify where cost will rise.

Questions buyers ask before moving from Teams to Matrix

What drives the cost of moving from Teams to a self-hosted Matrix server?

The cost is mostly people and infrastructure, and it splits into one-time work and recurring running costs. One-time work covers the history extraction, mapping teams and channels to spaces and rooms, single sign-on setup, testing, and cutover. Recurring costs cover the servers, databases, Redis, TURN and Element Call infrastructure, backups, patching, and the staff who operate them. Costs rise with the number of users, the volume of history to extract, the number of SSO integrations, and how many Teams licenses you must keep active during export. Ask any provider for a quote that separates these components and states which party carries each one. Element Server Suite pricing is listed on Element's pricing page, so compare editions against that page.

Can our own team run the Teams to Matrix migration without outside help?

Yes, if you have engineers who already run Linux servers, PostgreSQL, and identity integrations, and who can dedicate time to the project. The Teams Export APIs require an administrator to approve application permissions and an active Teams license on each exported user, so the work depends on your tenant administrators as much as your platform team. Matrix adds its own operational areas: federation settings, reverse proxy and delegation, upgrades, and database maintenance. Upstream upgrade notes warn that rolling back can be difficult because of schema changes, so plan staffing for upgrades as an ongoing task. Many organizations split the work, keeping day-to-day operation in house and bringing in a partner for the initial build, testing, or hardening.

How long should a parallel run of Teams and Matrix last?

The length of a parallel run depends on how many teams depend on Teams-only features, how many users need training, and how quickly you can close integration gaps. Define exit criteria before you start, such as the share of active channels moved, SSO working for every user group, mobile and desktop clients tested on managed devices, and a rollback path that has been rehearsed. Keep Teams licenses and the export window in mind: exports require active licenses, so do not let them lapse before history is captured. Confirm the duration with your own pilot results rather than a generic figure.

What does the migration require from our IT and security staff?

Expect requests across identity, networking, and records management. Identity staff configure OIDC, SAML2, or CAS in Synapse, and must map Entra ID or other directory groups to Matrix access. Network staff set up DNS, TLS certificates, the reverse proxy, and the federation listener on port 8448 or delegation on port 443, and they decide whether federation is enabled at all. Synapse's federation_domain_whitelist setting can restrict federation to listed domains, and the docs recommend also firewalling the federation listener. Security and compliance staff need to agree on retention, backup, and access logging for the new platform and on who may read the exported archive, since that archive contains the history your Teams tenant held.

Can all Microsoft Teams chat history be recovered in Matrix?

Not automatically, and you should verify the scope before promising it internally. The Microsoft Graph Teams Export APIs return 1:1, group, meeting, and channel messages, along with meeting recording and transcript links, but the data is only as complete as the retention and deletion settings in your tenant. Content deleted beyond Microsoft's retention windows is outside what the APIs can return, and the 21 and 30 day windows for deleted content are covered in our export guide. Matrix import tooling and room structures also differ from Teams, so message formatting, reactions, threads, and attachments may need testing with a sample before you commit to a full load. Ask for a sample import and a written list of what does not carry over.

How do we choose between Element Server Suite editions?

Start with licensing and support needs rather than feature names. The Element Server Suite is offered as a free AGPL Community edition that includes Synapse and Element Call, a Pro edition with Synapse Pro, and a Sovereign edition for air-gapped deployments. Element positions the Community edition for non-professional use and evaluations, so a production deployment at a regulated organization should be checked against Element's current terms before rollout. Confirm with Element which features each edition includes, what support is contractually provided, and what the AGPL obligations mean for any modifications you make. Compare those answers against your connectivity requirements and your internal support capacity.

Does DeployOpen handle the whole migration, and how is it scoped?

DeployOpen plans, implements, customizes, integrates, hardens, backs up, upgrades, documents, and supports self-hosted open-source platforms inside your own infrastructure, including the Matrix and Element stack. Most engagements are fixed-scope, with scope, deliverables, and timelines agreed in writing before work starts. Ongoing support, upgrades, and continuous testing are available as retainers. DeployOpen does not publish a price list, so a quote follows from the written scope that covers your user count, history volume, identity integrations, and the parallel-run plan. DeployOpen prepares systems, controls, and evidence for compliance assessments, but independent auditors and certification bodies issue any audit report or certification.

When Matrix and Element is the right target for Teams users

Choose Matrix and Element when the organization needs chat and meetings to move together, can run a PostgreSQL-backed Synapse server, and has a clear answer on federation. Matrix is a federated protocol, so the first decision is whether users must talk to people on other homeservers. If they must, plan the server_name value, delegation and port 8448 federation listener before anything else, because the identifiers in @user:example.com form cannot be changed later without re-creating accounts. If they do not, set federation_domain_whitelist to an explicit list of partner domains, or to an empty list to disable federation entirely, and firewall the federation listener as the Synapse configuration manual recommends. Confirm this with your security team before the design is fixed, since it determines the network and DNS work.

Next, check identity. Synapse supports single sign-on through OpenID Connect (oidc_providers), SAML2 (saml2_config) and CAS. If your Entra ID, Okta or on-premises directory already speaks OIDC or SAML, the integration is well understood. If your identity provider only offers a protocol outside that list, plan an intermediary such as the Matrix Authentication Service upstream identity provider documentation describes, and test it before committing. Also confirm who operates the database. Synapse recommends PostgreSQL for production, and recent releases require PostgreSQL 14 or newer and Python 3.10 or newer. Rolling back a Synapse upgrade can be difficult because of schema changes, so a team without database and upgrade discipline should budget for that operating work.

If the answers point elsewhere, the sibling pages cover those cases. Microsoft Teams vs Mattermost is a narrower fit when chat is the priority and meetings can move to a separate tool, and the Mattermost page covers its own identity and licensing tiers. Microsoft Teams vs Nextcloud Talk fits organizations that want chat, calls and files in one self-hosted product. Recommending a different target is a valid outcome of this assessment. Whichever path you choose, ask any implementation partner to put the federation policy, identity design and database operating model in the written scope so that each decision has an owner.

How DeployOpen scopes, runs and supports the Teams to Matrix migration

DeployOpen plans, implements, integrates, hardens, backs up, documents and supports self-hosted open-source platforms inside your own infrastructure. For a Teams to Matrix move, that means a written scope covering the Synapse homeserver, Element clients, Element Call and the history extraction, agreed before work starts.

How we scope

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
The written scope names which Teams teams, channels and chats move, and which stay in Teams during coexistence.
We confirm Microsoft Graph permissions, Teams licenses and the admin approvals needed for export before any extraction.
Scope records how spaces and rooms map to teams and channels, and who approves that mapping.
Scope also states the hosting location, identity provider and whether air-gapped operation is required.

How we build

We deploy Synapse with PostgreSQL and configure server_name, federation settings and reverse proxy routing in your environment.
We wire single sign-on through your existing identity provider using OIDC, SAML or CAS, as Synapse supports.
We set up Element clients and Element Call with the media infrastructure your network can support.
We build the Teams export pipeline and convert extracted history into a format the target can import and verify.
We test imports against a sample of rooms and check that membership, history and access rules match the agreed mapping.

How we hand over

Handover includes configuration documentation, runbooks for upgrades, backups and restores, and the import and mapping records.
We document the cutover plan, rollback steps and the Synapse upgrade notes that apply to your chosen release.
Your staff receive training on administration, room governance and user onboarding in the new platform.
Compliance evidence is prepared for your assessors, though DeployOpen does not issue audit reports or certifications.
Credentials, backup encryption keys and access lists are transferred to your owners under a documented process.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover.
A retainer can cover Synapse and Element version upgrades, watching for end-of-life Python and PostgreSQL changes.
Security testing of the deployed server, clients and integrations can be scheduled as part of the retainer.
Confirm with us during scoping which support hours, response paths and escalation contacts the retainer includes.
Ask for a written quote built from the agreed scope, since DeployOpen does not publish a price list.

Migrate from Microsoft Teams to Matrix and Element