Teams migration step-by-step

TheMigrator treats Teams migration as two distinct workloads that can be enabled independently. Teams Channels migrates specific team workspaces (channels, message history, channel files, member rosters) using a team picker. Teams Chat migrates private 1:1 and group chat history between individual users and requires an additional Graph API permission.

• Teams Channels: team-level migration — you select which Teams to move. Channel files come from SharePoint, so no extra cost if SharePoint is already running.
• Teams Chat: user-level migration — maps to the same user mapping as Email/OneDrive. Requires Chat.Read.All on the source App Registration.
• You can run both workloads in the same job, or create separate jobs for each.

Teams uses Exchange Online for user identity, calendar, and meeting data. Starting Teams migration before email migration completes will result in missing meeting invites in channel message history and broken @mentions.

If you intend to migrate Teams Chat history, you must add the Chat.Read.All application permission to the source tenant's App Registration and re-grant admin consent before starting the job.

• In Azure → App registrations → [your source app] → API permissions, add Chat.Read.All (Application permission).
• Click 'Grant admin consent' — a Global Admin on the source tenant must approve it.
• Verify the permission shows a green tick with 'Granted for [tenant]' status.
• Teams Channels migration does not require Chat.Read.All — skip this step if you are only migrating channels.

In TheMigrator → New migration, select Teams. Select source and destination tenants.

If Teams Channels is enabled, the mapping step shows a team picker table with all Teams workspaces discovered in the source tenant. Select which teams to migrate and map each to a destination team.

• Auto-matched teams (green): TheMigrator matched by name — verify the destination team is correct.
• Unmatched teams (yellow): select the destination team from the dropdown. If the destination team does not exist yet, create it in the destination tenant first.
• Teams marked as skip will not be migrated.
• Team owners must be mappable to destination users — a team with no owner is inaccessible after migration.
• Guest members from the source are not automatically migrated — they need to be re-invited in the destination.

If Teams Chat is enabled, a user mapping table appears below the team picker. Map source users to destination UPNs. This is the same user list used for Email and OneDrive migrations — if you already mapped users in a previous job, the same mappings apply.

• Only users explicitly mapped here will have their chat history migrated.
• Users marked as skip will not have their chat history migrated but will still appear in Teams (if their email was migrated).

Launch the job. Teams Channels migration runs in three phases: team structure creation, message history import, member assignment. Teams Chat runs in parallel as a separate phase. Monitor each phase in the job detail view.

• Phase 1 (team creation): fast — typically a few minutes per team.
• Phase 2 (message import): the longest phase — message rate is throttled by Microsoft's Teams Migration API.
• Phase 3 (member assignment): fast — happens after migration mode is completed on each team.
• Teams Chat phase: runs concurrently with Channels — duration depends on chat volume per user.

Teams channel files are stored in SharePoint. After migration, confirm the Files tab in each channel shows the correct documents. If the SharePoint migration is still running, channel file tabs may show empty until it completes.

Third-party app tabs (Planner, Trello, GitHub, etc.) are not migrated. They need to be reconfigured manually in the destination team. Document all custom tabs in each channel before migration.