How to migrate Microsoft Teams teams, channels, chats and meetings to another tenant
Teams content is split across several services. Files move with SharePoint and OneDrive, chats and meetings now have Microsoft cross-tenant tooling, and teams and channel conversations still need rebuilding or a third-party tool.
Your migration plan
This moves Microsoft Teams from one Microsoft 365 tenant (your organisation's own Microsoft 365 setup) to another: part of a Microsoft 365 tenant-to-tenant move. Microsoft's tool for this (Microsoft calls it the migration orchestrator) moves each user's 1:1, group and meeting chats and their meetings along with their mailbox and OneDrive. It needs a one-time, per-user add-on licence called Cross Tenant User Data Migration, which you can buy through a reseller or online as well as under an Enterprise Agreement. Teams and channels do not move with it, so you rebuild them in the new tenant, copy their files, and keep the old tenant for older channel history, or use a third-party tool. The time depends on your waves: each batch of up to 100 users copies the mailbox first and moves chats and meetings after the completion date you set.
Moves 1:1, group and meeting chats with each user and reschedules their meetings. One per-user licence (Cross Tenant User Data Migration) covers the mailbox, OneDrive, chats and meetings.
Other options and when to use them
- Third-party Teams migration tool such as ShareGate, MigrationWiz or Cloudiway: Some teams need their channel conversations, Planner plans or tabs copied into the new tenant.
- Rebuild teams and keep the source for history: Recent files matter more than old channel conversations, and the old tenant can stay licensed for search.
- Slack to Teams guide: You are moving from Slack rather than from another Microsoft 365 tenant.
Decide the scope first, then set up both tenants and the people, rebuild the teams people will work in, and only then move each user's chats and meetings. Microsoft's tool moves chats and meetings after the mailbox, so every step before the waves has to be finished or the batch fails its checks.
- Scope: teams, channels, history needs and users on holdDecides whether Microsoft's tool is enough or some teams need a third-party tool, and how many per-user licences to buy.
- Tenant set-up: migration apps, organisation relationship, federation and forwardingMicrosoft's tool checks these first when a batch starts and cancels the batch if any are missing.
- Target users created and mapped, then licensedChats can only add people who are mapped. A Teams, Exchange or OneDrive licence given before mapping creates a mailbox or OneDrive in the target, and the move then fails.
- Teams and channels rebuilt (or copied with a tool), with their filesMicrosoft's tool does not move teams, so they must exist in the new tenant before people switch, or users have nowhere to work on day one.
- Pilot batch of a few users with all four workloadsShows duplicate chats, rescheduled meetings and timing on a small group, while you can still cancel before the completion date.
- Main waves of up to 100 users, each with its completion dateMicrosoft limits a batch to 100 users. Only the mailbox copies until the completion date, so set that date to the day each wave switches tenant.
- Meeting rooms and shared devices signed in to the new tenantThey depend on resource accounts and on meetings already rescheduled in the target.
- Source teams archived, history kept, then the source closedArchiving stops people posting in the old tenant. Channel conversations never moved with Microsoft's tool, so the source stays licensed or exported until nobody needs them.
Built-in and third-party tools treat these differently. Tick each one off once you have decided.
Download this checklist (Excel)How each tool handles it
Built-in methodMicrosoft's tool (Microsoft calls it the migration orchestrator, part of cross-tenant user data migration) needs an add-on licence called Cross Tenant User Data Migration: a one-time fee per user, assigned on either the source or the target account. It covers that user's mailbox, OneDrive, chats and meetings. Microsoft says it is available to Enterprise Agreement customers and through resellers (CSP), online purchase, small business and education plans. Users also need Teams and Exchange Online licences in both tenants during the move.Tip: Ask your reseller to quote the add-on per user, and check the Microsoft 365 message centre (MC1198079) for the tool's current preview or general availability status before you set dates.
Microsoft Learn: Migration orchestrator overviewHow each tool handles it
Built-in methodMicrosoft's tool: Microsoft says chats and meetings are migrated, and its announcement names 1:1, group and meeting chats. How much history, and which message content (images, files, edits) comes across: not stated in Microsoft's documentation: test it in your pilot. Source chats are never deleted, the participant list changes from source to target accounts, and duplicate threads can appear in both tenants.ShareGate MigrateIts Copy teams documentation covers channel posts only, not the Chat section of Teams. Moving 1:1 and group chats: not stated in ShareGate's Copy teams documentation: test it in your pilot.BitTitan MigrationWizPrivate (1:1 and group) chats are not migrated.CloudiwayCloudiway says it migrates 1:1 and group chats.Tip: Tell users before their wave which tenant to use from which day, and that an old chat may appear twice.
Microsoft Learn: Migration orchestrator overviewHow each tool handles it
Built-in methodMicrosoft's tool: teams and channels are shared data and are not migrated. Channel conversations stay in the source tenant.ShareGate MigrateThe 50 most recent conversations become posts (raised to 500 with a PowerShell setting); older ones go to an HTML Message history tab. Several replies to one conversation are merged into one reply.BitTitan MigrationWiz60 messages per team show in the channel; the full history is an HTML file in a Conversation History tab.CloudiwayCloudiway says it migrates messages, replies and threads.Tip: Keep the source licensed for search, or export older history with Microsoft Purview, for teams that do not need history in the target.
Microsoft Learn: Migration orchestrator overviewHow each tool handles it
Built-in methodMicrosoft's tool: not stated in Microsoft's documentation: test it in your pilot.ShareGate MigrateReactions are not migrated. @mentions become highlighted text with no link to the person.BitTitan MigrationWizLikes and reactions are not migrated. @mentions arrive as plain text.CloudiwayCloudiway says reactions are migrated.Tip: Show channel owners a pilot channel so they know what old posts will look like.
How each tool handles it
Built-in methodMicrosoft's tool: no channels move. You create private and shared channels yourself in the rebuilt team.ShareGate MigrateCopies standard and private channels. Shared channels are not supported. Channel members and owners are copied only for private channels.BitTitan MigrationWizMigrates private channels and their files. Shared channels and their conversations are not migrated.CloudiwayCloudiway says it migrates private channels. Shared channels: not stated in Cloudiway's documentation: test it in your pilot.Tip: Set owners for private and shared channels when you create them, because only their members can see them.
How each tool handles it
Built-in methodMicrosoft's tool does not move team sites. Move them with Microsoft's built-in tenant-to-tenant site move (cross-tenant SharePoint migration, which needs a licence sold only under an Enterprise Agreement, a volume licensing contract most small businesses do not have) or a copy tool. See the SharePoint guide for how each handles versions.ShareGate MigrateCopies channel files with the team. Version handling in Copy teams: not stated in ShareGate's Copy teams documentation: test it in your pilot.BitTitan MigrationWizCopies files in public and private channels with versions and metadata (name, created date, modified date, modified by).Tip: Files shared in 1:1 and group chats live in the sender's OneDrive, so they move with that user's OneDrive, not with the team.
Microsoft Learn: Cross-tenant SharePoint migration overviewHow each tool handles it
Built-in methodMicrosoft's tool: every user must be in Cross-Tenant Identity Mapping (Microsoft's list that pairs each source account with its target account) before a batch runs, or chats cannot add the right people. Target users must not have a mailbox or OneDrive yet. Team membership is not moved because teams are not moved.ShareGate MigrateMembers and owners can take up to 24 business hours to show in the target. Org-wide teams become Public teams.BitTitan MigrationWizMigrates team privacy type and member permissions. All memberships arrive as static; dynamic membership is not migrated. Guests are added only if the guest already exists in the target.Tip: Turn off OneDrive creation for target users as soon as you create them, and assign licences only after mapping shows Complete.
Microsoft Learn: Migration orchestrator planning and prerequisitesHow each tool handles it
Built-in methodMicrosoft's tool: none of these move, because teams are not moved.ShareGate MigrateCopies basic Planner plans, buckets and tasks; premium plans are not supported. Only Teams store apps copy; custom apps and webhooks do not. Wiki and Flow tabs are not supported, and Forms, Power BI and Stream tabs need setting up again across tenants.BitTitan MigrationWizMigrates Planner plans, buckets and tasks, and Word, Excel, PowerPoint, Website, Planner and OneNote tabs. Custom tabs, Wiki, Power BI and Stream tabs are not migrated.Tip: Record every tab and app per team in the inventory, with a named owner for each rebuild.
How each tool handles it
Built-in methodMicrosoft's tool: after the completion date, each user's meetings are cancelled in the source and rescheduled in the target. This cannot be undone: if you move a user back, Microsoft says meetings are not recreated. The meetings workload only runs in a batch that also has chats and mailboxes. Meeting recordings are files in the organiser's OneDrive or the channel's site, so they move only if that OneDrive or site moves.ShareGate MigrateMeet Now posts and the team calendar are not migrated.BitTitan MigrationWizTeams meeting invites in conversations, meeting recordings and calendar previews are not migrated.Tip: Warn guests that invitations will come again from new addresses, and make the go or no-go call before the completion date.
Microsoft Learn: Migration orchestrator FAQ and known issuesHow each tool handles it
Built-in methodMicrosoft's tool: mailboxes on any type of hold are not migrated and the move is blocked. Microsoft asks you to contact its engineering team before moving users with holds. Because meetings need the mailbox in the same batch, plan for that user's meetings not moving either.Tip: List held users in the scope step and agree a plan for each with your compliance owner.
Microsoft Learn: Migration orchestrator overviewHow each tool handles it
Built-in methodMicrosoft's tool: voicemails and the greeting migrate, but voicemails received in the source do not show in the target Teams client. Users can hear them by calling voicemail, where they appear as saved messages.Tip: Tell users how to reach old voicemails, and ask them to save anything important first.
Microsoft Learn: Migration orchestrator FAQ and known issuesHow each tool handles it
Built-in methodMicrosoft's tool: a batch holds up to 100 users, and a user listed twice moves once. Until the completion date (CompleteAfterDate) only the mailbox copies; chats and meetings move after the mailbox completes. You can cancel only before that date. Microsoft gives no guaranteed finish time, and does not say whether later chat messages are topped up: test it in your pilot.ShareGate MigrateCopy teams incremental picks up new conversations and changed files in team and private channel sites.CloudiwayCloudiway says later passes transfer only new messages (a delta pass: a top-up copy of only what changed since the last copy).Tip: Set each wave's completion date to the day those users switch, outside business hours.
Microsoft Learn: Migration orchestrator FAQ and known issues
- 1
Agree the scope
Before you startWatch out: Microsoft's tool: teams, channels and channel conversations do not move. They stay in the source tenant.
Ways around it
- Rebuild teams, and keep the source tenant licensed for search or export old history with Microsoft Purview before closing it.
Tools that can do it
- ShareGate MigrateCopies standard and private channel conversations. The 50 most recent are native posts, the rest go to an HTML history tab. Shared channels are not supported.
- BitTitan MigrationWizMigrates public and private channel conversations: 60 messages per team show in the channel, the full history is an HTML file in a tab.
- CloudiwayMigrates channels, messages, replies and threads between tenants.
Show the detailed steps (2) →Watch out: Microsoft's tool: mailboxes on any type of hold are not moved and the move is blocked. Meetings need the mailbox in the same batch, so plan for that user's meetings not moving either.
Ways around it
- Review each held user with compliance. Microsoft asks you to contact its engineering team before moving held users.
- 2
Set up both tenants
Watch out: Microsoft's tool: if a target user already has a mailbox or OneDrive, that user's move fails.
Ways around it
- License target users only after identity mapping completes.
- If one was provisioned early, remove the content or recreate the user as a mail user, then map again.
Show the detailed steps (6) →Watch out: Microsoft's tool: users need Teams and Exchange Online licences in both tenants during the move, on top of the add-on.
Ways around it
- Plan how long source licences stay assigned for the final sync and any history you keep searchable.
- 3
Rebuild teams
Show the detailed steps (3) →Watch out: Microsoft's tool and a rebuild by hand: tabs, apps, bots and Planner plans do not move.
Ways around it
- Rebuild them by hand from the inventory before cutover, so teams that rely on them work on day one.
Tools that can do it
- ShareGate MigrateCopies basic plans, buckets and tasks with assignments. Premium plans are not supported.
- BitTitan MigrationWizMigrates Planner plans and Word, Excel, PowerPoint, Website, Planner and OneNote tabs. Custom tabs and other apps are not migrated.
- 4
Copy channel history
Optional, only for teams that need itWatch out: Third-party tools: Microsoft's import interface, which these tools use to write channel posts, gives no way to fix an import except deleting the team, recreating it and importing again.
Ways around it
- Test on a throwaway team first, and book one production import slot per team.
Show the detailed steps (3) →Watch out: Third-party tools: Microsoft's import interface accepts five requests per second per channel, so long histories take time. Videos and cross-posted messages do not move.
Ways around it
- Move only recent history, and leave older history in the source tenant or a Purview export.
- 5
Prepare users
One week beforeShow the detailed steps (3) →Watch out: Microsoft's tool: source chats remain and participant lists change, so users can see the same chat twice.
Ways around it
- Tell users in advance to use the migrated thread in the target tenant.
- 6
Switch over
On the completion dateWatch out: Microsoft's tool: a batch with the meetings workload will not start unless chats and mailboxes are in the same batch. A batch holds up to 100 users.
Ways around it
- Always select all four workloads in every wave.
Watch out: Microsoft's tool: after the CompleteAfterDate, meetings are cancelled in the source and rescheduled in the target, which cannot be undone.
Ways around it
- Make your go or no-go call before that date. Until then you can change the date or remove users from the job.
Turn this phase into dated tasks with the cutover planner
Show the detailed steps (4) → - 7
Check and close
Show the detailed steps (4) →Watch out: Microsoft's tool: voicemails received in the source move, but do not show in the target Teams client. Users hear them as saved messages by calling voicemail.
Ways around it
- Ask users to deal with important voicemails in the source before it closes.
- Microsoft's tool shows Completed for every user and every workload in each batch.
- Every rebuilt team has its channels, owners and files, and each owner has signed it off.
- Users see their chats and recurring meetings in the target, and rooms and shared devices show the new organisation.
- Every source team is archived, and older history is searchable or exported.
Tools named in this plan are independent third-party products, not endorsed by the platform vendor and not paid placements. Check the tool's own documentation and run a pilot first.
Detailed steps
Open a part when you reach it in the plan. Each step says where to go, what to do and what you should see.
About this migrationWhat it covers, limits at a glance
A Microsoft Team is not one object. The team itself is a Microsoft 365 group, channel files sit in a SharePoint site, files shared in chats sit in the sender's OneDrive, meetings are calendar items in Exchange, and chat and channel messages are stored by the Teams service. Each part has a different migration path.
This guide covers the Teams part of a tenant move. Mailboxes, OneDrive and SharePoint are covered in the Microsoft 365 tenant-to-tenant guide. Moving from Slack is covered in the Slack to Teams guide.
1What you need before step one
| Need | Details | Where to get it |
|---|---|---|
| Global Administrator in both tenants | Microsoft requires it for tenant and user configuration. Target admins can run batches as Global Administrator or Microsoft 365 Migration Administrator. | Microsoft 365 admin center, https://admin.microsoft.com |
| Teams PowerShell | MicrosoftTeams module, on Windows PowerShell 5.1 or PowerShell 7.2 or later. | https://learn.microsoft.com/MicrosoftTeams/teams-powershell-install |
| Microsoft Graph PowerShell (including Microsoft.Graph.Beta) | For batches, identity mapping and context checks. | Install Microsoft Graph PowerShell |
| Exchange Online PowerShell | For the endpoint, organisation relationship and spam filter settings. | Install the module and connect |
| CrossTenantMigration module | Microsoft's NuGet package that sets up the migration apps. | Download link on Microsoft's "Configuring source and target tenants" page |
| Licences | Teams and Exchange Online in both tenants, plus the Cross Tenant User Data Migration add-on for each migrating user. | Your licensing partner; check current pricing with them |
2Work out what moves natively2 steps
| Content | Microsoft native path | Notes |
|---|---|---|
| 1:1, group and meeting chats | Cross-tenant user data migration (Teams chats workload) | Source messages remain; participants are swapped for target users |
| Teams meetings | Cross-tenant user data migration (Teams meetings workload) | Requires the chats and mailbox workloads in the same batch |
| Teams and channels (structure) | None | Recreate with PowerShell or templates, or use a third-party tool |
| Channel conversations | None for tenant-to-tenant | Third-party tools use the Teams import (migration mode) API |
| Channel files | Cross-tenant SharePoint migration | Covered in the tenant-to-tenant guide |
| Files shared in chat | Cross-tenant OneDrive migration | Links in migrated messages may need checking |
| Tabs, apps, Planner, Forms | None | Rebuild; see the Power Platform guide for Planner and Forms |
- 1
Agree what history the business needs
Where: Your scope document, signed off by records and legal ownersMany organisations move chats, rebuild teams with recent files, and keep the source tenant read-only or searchable for older channel history. Agree this with records and legal owners before choosing tools.
You should see: A signed-off decision for each content type in the table above. - 2
Inventory teams and owners
Where: PowerShell on your admin PC, connected with Connect-MicrosoftTeams to the SOURCE tenantInstall the module first if needed (
Install-Module -Name MicrosoftTeams -Force -AllowClobber, from Microsoft's Teams PowerShell install page). Export a list of teams, then owners and channels for each team.Connect-MicrosoftTeams Get-Team | Select-Object DisplayName,GroupId,Visibility,Archived | Export-Csv C:\migration\teams.csv -NoTypeInformation Get-TeamUser -GroupId <GroupId> -Role Owner Get-TeamChannel -GroupId <GroupId> | Select-Object DisplayName,MembershipTypeYou should see: C:\migration\teams.csv lists every team, and you have owners and channel types for each.
3Check the status of Microsoft's cross-tenant chat and meeting migration3 steps
Microsoft announced cross-tenant migration of mailboxes, OneDrive, Teams chats and Teams meetings as a public preview in message center post MC1198079 (December 2025). The Microsoft Learn documentation, called migration orchestrator or Cross-Tenant User Data Migration, now describes a per-user Cross Tenant User Data Migration licence but does not state a preview or general availability status. Microsoft describes it as an opt-in feature that runs through PowerShell. Check the message center and the Learn overview for the current status before you commit to it.
- 1
Understand what it does
Where: Microsoft Learn: Migration orchestrator overview (read before planning)Microsoft says personal chats (1:1), group chats and meeting chats are in scope, and meetings are cancelled and rescheduled automatically for the user. It moves content, not identities: you create and map the target users. It does not move teams, channels or SharePoint sites.
You should see: Your scope document lists chats and meetings as moving with Microsoft's tool and teams and channels as not. - 2
Run all workloads in one batch
Where: Your Migration wave planMicrosoft recommends migrating mailboxes, OneDrive, chats and meetings together. A batch with the meetings workload fails unless chats and mailboxes are also selected. Plan each wave as one batch with the Exchange, ODSP, Teams and Meeting workloads.
You should see: Every wave in the plan includes all four workloads. - 3
Know what users will see
Where: Your User communication packOriginal chats stay in the source, possibly edited. Participant lists change from source to target users, and duplicate threads can appear in both tenants. Put this in the user notice.
You should see: The user notice explains duplicate threads and which tenant to use after cutover.
4Meet the prerequisites for chat and meeting migration6 steps
- 1
Map identities
Where: PowerShell on your admin PC in both tenants, with the CrossTenantIdentityMapping module (mainly run by the TARGET admin)Every migrating user must be mapped in Identity Mapping. Target users must not have a mailbox or OneDrive provisioned before migration; turn off OneDrive creation for them as soon as you create them. Install the module, add the service principal (Global Administrator), copy identities from the source security group, then map and write them in the target. Full steps are on Microsoft's Cross-Tenant Identity Mapping page.
Install-Module CrossTenantIdentityMapping -AllowPrerelease Import-Module CrossTenantIdentityMapping Connect-MgGraph Add-CtimServicePrincipal # Source admin New-CtimCopyRequest -SecurityGroupGuid <GUID> -TargetTenantGuid <GUID> # Target admin Accept-CtimCopyRequest -RequestID <ID> -SourceTenantGUID <GUID> New-CtimMapRequest -SourceTenantGuid <GUID> New-CtimWriteRequest -SourceTenantGuid <GUID> Get-CtimReport -SourceTenantGuid <GUID>You should see: Get-CtimReport shows every source user as Mapped, then Complete, and target users are MailUsers. - 2
Licence users in both tenants
Where: Microsoft 365 admin center of each tenant > Billing > Licenses > select the product > Assign licensesUsers need a Teams licence in both tenants and an Exchange Online licence in both for meeting migration, plus the Cross Tenant User Data Migration licence on the source or target user. Assign target workload licences only after identity mapping has completed. Check Microsoft's current pricing with your licensing partner. See assign licences.
You should see: Each migrating user shows Teams and Exchange Online licences in both tenants. - 3
Set up the organisation relationship and migration endpoint
Where: PowerShell on your admin PC, connected with Connect-ExchangeOnline to the TARGET tenant (and the source for its side)Create the cross-tenant migration endpoint and organisation relationship as shown in create a migration endpoint (cross-tenant steps). Add all source users to the mail-enabled security group named in the source organisation relationship.
You should see: Get-MigrationEndpoint lists the cross-tenant endpoint and Get-OrganizationRelationship shows MailboxMoveEnabled True. - 4
Provision the migration apps
Where: PowerShell on your admin PC in each tenant, after installing Microsoft.Graph.Authentication, Microsoft.Graph.Applications, Microsoft.Graph.Identity.DirectoryManagement, Microsoft.Graph.Beta, ExchangeOnlineManagement and MicrosoftTeamsDownload the CrossTenantMigration NuGet package from the link on Microsoft's Configuring source and target tenants page, then expand and import it. Run the grant commands in the tenants shown. Microsoft says the Meeting Migration app needs the Exchange Administrator directory role in both tenants and Calendars.ReadWrite RBAC in the target, which the last command sets.
Expand-Archive -Path ".\CrossTenantMigration.nupkg" -DestinationPath ".\CTModule" -Force Import-Module -Name ".\CTModule\CrossTenantMigration" -Force # Target tenant only Grant-CTMSAppPermissions # Both tenants Grant-OneDriveAppPermissions Grant-CTTMAppPermissions Grant-MMSAppPermissions -TenantType "source" # in the source Grant-MMSAppPermissions -TenantType "target" # in the target # Target tenant only Set-CalendarRBACRolesYou should see: Each command completes without errors in the tenant it was run in. - 5
Allow federation and automatic forwarding
Where: PowerShell on your admin PC, connected with Connect-MicrosoftTeams, and PowerShell connected with Connect-ExchangeOnline, in BOTH tenantsMicrosoft's tenant configuration page sets Teams federation on in both tenants, and requires AutoforwardingMode set to On in the default outbound spam filter policy in both tenants for meeting migration.
Set-CsTenantFederationConfiguration -AllowFederatedUsers $True Get-CsTenantFederationConfiguration Set-HostedOutboundSpamFilterPolicy -Identity Default -AutoForwardingMode OnYou should see: AllowFederatedUsers shows True and Get-HostedOutboundSpamFilterPolicy Default shows AutoForwardingMode On. - 6
Check your Graph context before each command
Where: Every Graph PowerShell sessionYou will switch between tenants often. Confirm which one you are connected to before each change.
Disconnect-MgGraph Connect-MgGraph Get-MgContextYou should see: TenantId in Get-MgContext matches the tenant you mean to change.
5Rebuild teams and channels in the target3 steps
- 1
Create teams and channels
Where: PowerShell on your admin PC, connected with Connect-MicrosoftTeams to the TARGET tenantUse the inventory to recreate each team and its channels. Private and shared channels need owners set at creation.
Connect-MicrosoftTeams $team = New-Team -DisplayName "Finance" -Visibility Private -Owner owner@contoso.com New-TeamChannel -GroupId $team.GroupId -DisplayName "Month end" Add-TeamUser -GroupId $team.GroupId -User user@contoso.com -Role MemberYou should see: Get-Team -DisplayName "Finance" returns the team and Get-TeamChannel lists its channels. - 2
Move channel files
Where: Your SharePoint migration tool, using the team site URLs from each tenantEach team creates a SharePoint site. Move files from the source team site into the matching channel folders with SharePoint cross-tenant migration or a third-party tool. See the SharePoint cross-tenant migration guide.
You should see: Each channel's Files tab in the target shows the migrated files. - 3
Recreate tabs, apps and connectors
Where: Teams client in the target tenant > each team > channel > + (Add a tab), and AppsTabs, apps, connectors and bots do not move. Record them during inventory and add them back. Planner plans and Forms are covered in the Power Platform and apps guide.
You should see: Each team owner confirms their tabs and apps are back.
6Move channel conversations (optional)3 steps
Third-party tools move channel messages using Microsoft's Teams import API. That API puts a channel or chat into migration mode, imports messages with their original time stamps and authors, then completes migration.
- 1
Know the API limits
Where: Microsoft Learn: Import third-party platform messages to Teams (read before choosing a tool)Microsoft documents imports at five requests per second per channel, inline images as the only supported media, and no import of federated content. Videos and cross-posts are out of scope. Up to 250 reactions per message are supported. Use these numbers to estimate run time with your tool vendor.
You should see: You have an estimated import time for your largest channels. - 2
Pick and test a tool
Where: The third-party tool's console, against a test team in the target tenantRun a pilot on one busy team and one private channel. Check authors, time stamps, replies, mentions and file links before you migrate everything.
You should see: The channel owner signs off the pilot in your Pilot test plan. - 3
Plan re-runs carefully
Where: Your Pilot test plan and Cutover runsheetMicrosoft says that to correct imported results you must delete the team, recreate it and migrate again. Test before production, and import each production channel once.
You should see: The runsheet has a single production import slot per team.
7Cut over and support users4 steps
- 1
Create the batch and set the CompleteAfterDate
Where: PowerShell 7 on your admin PC, connected to the TARGET tenant with Connect-MgGraph -Scopes 'CrossTenantContentMigration.ReadWrite.All'With Microsoft's tool, only the mailbox syncs until the CompleteAfterDate passes. Chats and meetings move after the mailbox has completed. Pick a date that matches your domain and mailbox cutover. Create the job with the source user IDs and all four workloads, validate it, then start it. Validation must have passed within the last seven days.
New-MgBetaCrossTenantMigrationJob -BodyParameter $body # $body lists displayName, completeAfterDateTime, sourceTenantId, exchangeSettings, resources, resourceType Users and workloads Teams, Exchange, ODSP, Meeting Test-MgBetaCrossTenantMigrationJob -CrossTenantMigrationJobId <batch name or job id> Move-MgBetaCrossTenantMigrationJob -CrossTenantMigrationJobId <batch name or job id> Get-MgBetaCrossTenantMigrationJobUser -CrossTenantMigrationJobId <batch name or job id> | ConvertTo-Json -Depth 100You should see: The batch goes from ValidatePassed to InProgress, CuttingOver and Completed. Users show Completed for each workload. - 2
Sign users in to the new tenant
Where: Teams desktop and mobile apps on each user's devices, and shared devices and Teams RoomsUsers must sign out of Teams (select their profile picture, then Sign out) and sign in with their target account. Clear cached accounts on shared devices and Teams Rooms.
You should see: Teams shows the target organisation name and the migrated chats. - 3
Check meetings and voicemail
Where: Outlook and Teams Calendar in the target tenant, for a sample of usersConfirm recurring meetings were rescheduled in the target. Microsoft notes that voicemails received in the source are not available in the target Teams client.
You should see: Recurring meetings appear in the target calendar with working Teams links. - 4
Restrict the source tenant
Where: PowerShell on your admin PC, connected with Connect-MicrosoftTeams to the SOURCE tenantOnce users are in the target, stop new posts in source teams (archive them or set them read-only) so conversations do not split. Repeat for each GroupId in your inventory.
Set-TeamArchivedState -GroupId <GroupId> -Archived:$trueYou should see: Get-Team shows Archived True for each source team.
Expert notes
The detail behind the plan: options compared, and what experienced engineers check first. Tap any item.
Compare all the ways to do this3 options
Microsoft migration orchestrator for chats and meetings
Medium effortBest for: Tenant moves that run mailboxes, OneDrive, chats and meetings together per user
- Moves 1:1, group and meeting chats with the user
- Meetings are cancelled and rescheduled for the user automatically
- Uses the same per-user Cross Tenant User Data Migration licence
- Does not move teams, channels or SharePoint sites
- Check its current preview or general availability status before you commit
- Users can see duplicate threads in both tenants
Third-party Teams migration tool
High effortBest for: Organisations that need channel conversations moved, or teams rebuilt for them
- Moves channel messages through the Teams import API with original authors and time stamps
- Can recreate teams and channels in the target
- Vendor licence; check current pricing
- Import API limits set the pace; videos and cross-posts are out of scope
- Correcting an import means deleting the team and migrating again
Rebuild teams and keep the source for history
Medium effortBest for: Teams where recent files matter more than old channel conversations
- No tool for channel history
- A chance to clean up team and channel structure
- Channel conversations stay behind in the source
- The source must stay licensed for search, or be exported with Purview before closing
Agree with records and legal owners what history each team needs before choosing. A common pattern is to move chats and meetings with Microsoft's orchestrator, rebuild teams with their files, and keep the source searchable for older channel history. Bring in a tool only for teams whose channel conversations must be in the target.
Agree how much channel history you really needCost lever
Microsoft's tool does not move channel conversations. Third-party tools can, but channel imports are throttled per channel and the effort grows with years of history.
Ask each team owner what they actually reopen. A common pattern is to move recent files, rebuild the team, and keep the source tenant licensed or exported with Microsoft Purview for older history. Write the decision in the scope document before choosing tools.
These tools copy standard and private channel conversations into the target team, which Microsoft's cross-tenant tool does not. Most keep only recent posts as native messages and put the older history in an HTML page or tab.
- ShareGate MigrateCopies standard and private channel conversations: the 50 most recent are native posts, the rest go to a Message history tab as HTML. Shared channels are not supported.
- BitTitan MigrationWizMigrates public and private channel conversations: 60 messages per team show in the channel, the full history is an HTML file in a Conversation History tab.
- CloudiwayMigrates channels, messages, replies and threads between tenants.
Do not license target users before identity mapping runsReduces risk
Microsoft says target users must not have a mailbox or OneDrive before migration, or the move fails. Assigning an Exchange or OneDrive licence too early provisions them.
Create target users, run Cross-Tenant Identity Mapping so they become MailUsers with the source Exchange GUID, and only then assign workload licences. Turn off OneDrive creation for new target users until migration finishes.
Check holds before you build batchesCompliance
Microsoft says mailboxes on any type of hold are not migrated and the move is blocked. Because meetings depend on the mailbox, held users also lose chat and meeting migration in that batch.
Run Get-Mailbox -ResultSize Unlimited | Where-Object {$_.LitigationHoldEnabled -or $_.InPlaceHolds} | Format-Table Name,LitigationHoldEnabled,InPlaceHolds in the source and agree a plan for each held user with your compliance team.
Warn users about duplicate chats and rescheduled meetingsUser impact
Microsoft says source chats remain, participant lists change and duplicate threads can appear in both tenants. Meetings are cancelled and rescheduled, so attendees receive a flurry of updates.
Send the user communication a week ahead: which tenant to use from which day, what duplicate threads look like, and that meeting updates are expected. Tell external guests their invitations will come from new addresses.
Test channel imports on a throwaway teamSaves time
Microsoft says the only way to correct an imported channel is to delete the team, recreate it and import again. A mistake found after the bulk import costs the whole run.
Pilot one busy standard channel and one private channel in a test team, check authors, dates, replies, mentions and file links with the owner, then delete the test team before production.
List tabs, apps, bots and Planner plans per teamUser impact
None of these move with Microsoft's tool or with a team rebuild. Teams that run on a Planner board or a line-of-business tab stop working on day one if they are not rebuilt.
For each team record its tabs, installed apps, bots and connected Planner plans in the inventory, and assign an owner to rebuild each one in the target before cutover.
ShareGate and MigrationWiz copy a team's Planner plans and several standard tab types with the team, so fewer boards and tabs need rebuilding by hand. Custom apps, bots and webhooks still have to be rebuilt in the target.
- ShareGate MigrateCopies basic plans, buckets and tasks with assignments; comments arrive as emails in the team mailbox. Premium plans are not supported.
- BitTitan MigrationWizMigrates Planner plans, buckets and tasks, plus Word, Excel, PowerPoint, Website, Planner and OneNote tabs. Custom tabs and other apps are not migrated.
Plan shared devices and Teams Rooms separatelyUser impact
Meeting room systems and shared devices sign in with resource accounts that belong to the source tenant. They keep showing old meetings until they are signed out and reconfigured.
Create resource accounts in the target, move room mailboxes, and schedule a visit or remote session to sign each device in to the target on cutover day.
Budget for the cross-tenant migration add-on and overlap licencesCost lever
Microsoft requires a Cross-Tenant User Data Migration add-on licence per migrating user, plus Teams and Exchange Online licences in both tenants during the move.
Get a quote for the add-on from your licensing partner, and plan how long source licences must stay assigned for the final sync and any history you keep searchable.
Check it worked, or roll back
Full validation checklist8 checks
Run these before you declare the migration complete. Record the results in the data validation report.
| Check | How to check | What good looks like |
|---|---|---|
| The migration batch completed for every user | In PowerShell 7 connected to the target with Connect-MgGraph, check the job status with the orchestrator commands from the cutover step, and run | The batch reached Completed, every user shows Completed for each workload, and every identity is Complete in the identity mapping report. |
| Every team and channel exists in the target | Connected to the target with Connect-MicrosoftTeams, run | Every team marked for rebuild is in the target with the same channels and channel types. |
| Owners and members are right | For each target team run | Each team has the same owners, and member counts match the source after mapping to target accounts. |
| Channel files are in place | Ask each team owner to open every channel's Files tab in the target, including private and shared channels, and compare with your file migration tool's report. | Every channel shows its files and the tool report has no failed items you have not accepted. |
| Chats and meetings arrived | Sample users from each wave sign in to Teams with their target account, open their 1:1, group and meeting chats, and open recurring meetings in the target Outlook or Teams calendar. | Migrated chats show with target participants, and recurring meetings appear in the target with working Teams links. |
| Channel conversations imported correctly (tool route) | In the pilot and each imported team, check authors, time stamps, replies, mentions and file links against the source channel. | The channel owner signs off the import in your Pilot test plan. |
| Tabs, apps and devices work | Each owner checks tabs and apps in their team. Check shared devices and Teams Rooms show the target organisation name. | Owners confirm tabs and apps are back, and every shared device and room is signed in to the target. |
| The source no longer takes posts | Connected to the source with Connect-MicrosoftTeams, run | Every migrated source team shows Archived True. |
Rollback planIf it goes wrong
Roll back if
- The orchestrator batch fails validation or users stop at an error before the CompleteAfterDate
- Users cannot sign in to Teams in the target or cannot see migrated chats
- A channel conversation import produced wrong authors or dates for a team
- Rebuilt teams are missing channels, owners or files and the team cannot work
Point of no return
With Microsoft's tool, only the mailbox syncs until the CompleteAfterDate passes, so the cheap no-go point is before that date. After it, chats and meetings move: meetings are cancelled in the source and rescheduled in the target, which cannot be undone, and the mailbox and OneDrive parts behave as in their own guides. Original chats stay in the source, so users can still read them there. For channel imports, Microsoft says the only way to correct imported results is to delete the team, recreate it and migrate again.
- 1
Stop the batch before the CompleteAfterDate
Where: PowerShell 7 connected to the target with Connect-MgGraph, using the orchestrator commands in Microsoft's "Running the migration" articleIf a trigger is met before the CompleteAfterDate, follow Microsoft's article to change the date or remove the affected users from the job, and confirm their status.
You should see: The job shows the users removed or the later date, and users carry on in the source. - 2
Reopen source teams
Where: PowerShell on your admin PC, connected with Connect-MicrosoftTeams to the SOURCE tenantUnarchive each team users need again with
Set-TeamArchivedState -GroupId <GroupId> -Archived:$false.You should see: Get-Team shows Archived False and members can post in the source. - 3
Sign users back in to the source
Where: Teams desktop and mobile apps on each user's devices, shared devices and Teams RoomsUsers select their profile picture > Sign out, then sign in with their source account. Sign shared devices and rooms back in to the source.
You should see: Teams shows the source organisation name and the original chats. - 4
Redo a bad channel import
Where: PowerShell connected with Connect-MicrosoftTeams to the TARGET tenant, then the third-party tool's consoleDelete the target team with
Remove-Team -GroupId <GroupId>, recreate it and its channels as in the rebuild step, and run the import again in its next slot.You should see: The re-imported team passes the channel owner's check. - 5
Roll back mail and files if they moved
Where: Your Rollback planIf the CompleteAfterDate passed, follow the rollback in cross-tenant mailbox migration and cross-tenant OneDrive migration, and tell organisers to recreate any recurring meetings in the source.
You should see: Users work in the source with their mailbox, files and meetings, and the Rollback plan has a dated entry.
Agree the triggers and who decides before the go / no-go meeting. Use the rollback plan template.
Common problems and fixes6 errors
Migration batch fails to start when Teams meetings is selectedCause: The meetings workload was selected without Teams chats and Exchange mailboxes.
Fix: Include mailboxes, chats and meetings in the same batch.
Migration blocked for users with a mailbox on holdCause: Microsoft does not migrate mailboxes on any type of hold.
Fix: Review the hold with your compliance team; Microsoft asks you to contact its engineering team before moving held users.
Target user already has a mailbox or OneDriveCause: The target user was licensed and provisioned before migration.
Fix: Target users must not have a mailbox or OneDrive before migration. Remove the provisioned content or recreate the target user as a mail user, then re-map.
Meeting migration validation fails on auto-forwardingCause: AutoforwardingMode is not On in the default outbound spam filter policy in one of the tenants.
Fix: Run Set-HostedOutboundSpamFilterPolicy -Identity Default -AutoForwardingMode On in both tenants.
Chats appear twice after migrationCause: Microsoft notes duplicate threads can be created in both tenants.
Fix: Tell users in advance. Use the migrated thread in the target tenant.
Imported channel messages are out of orderCause: The channel is still in migration mode and Teams shows a banner while the import runs.
Fix: Wait for the tool to call completeMigration, then check the channel again.
Frequently asked questions
Can Teams chats be migrated to another tenant?
Yes. Microsoft's cross-tenant user data migration covers 1:1, group and meeting chats. It was announced as a public preview in MC1198079; check its current status and licensing before relying on it.
Does Microsoft migrate Teams channels between tenants?
No. Microsoft's tool does not move teams, channels or SharePoint sites. Rebuild them and move channel messages with a third-party tool if you need them.
Are Teams meetings moved?
Yes, with the meetings workload. Microsoft says meetings are cancelled and rescheduled automatically for the user.
Will chats be deleted from the old tenant?
No. Microsoft says chat messages are not deleted from the source tenant after migration.
What about files shared in chats?
They live in the sender's OneDrive, so they move with the OneDrive migration. Check links after cutover.
How do I migrate from Slack instead?
See the Slack to Teams guide, which covers Slack exports and import tools.
Official sources
10 official pages this guide is based on
Vendors change limits and features, so confirm details on the source before you rely on them. Last checked 4 Nov 2026.