Teams to Teams (cross-tenant) migration
A reference for moving Microsoft Teams channels between two Microsoft 365 tenants: channels, channel messages and thread replies with original dates, the team's files, and members. This page covers the connections on both sides, how the destination team is built in migration mode, how people are mapped across tenants, and what doesn't come across.
Teams as a source is waiting on Microsoft approval
Reading channel messages with application permissions requires Microsoft's approval for its protected Teams APIs. That approval for the MigrationFox Teams app is still pending, so Teams to Teams may not work yet with the MigrationFox Teams app. If a migration fails with “Microsoft hasn't approved this app to read Teams messages yet (protected Teams APIs)”, the app hasn't been approved. If you connect the source with your own Azure app, your organization can request access through Microsoft's protected API form. Contact support@migrationfox.com before planning a cutover.
Why Teams migration is different
Teams conversation history can't be recreated by copying files. Microsoft's Teams import API is the supported way to write historical messages with their original dates. It only works on a team in migration mode: the team is created in that state, history is written in, and then the team is switched to normal use. MigrationFox runs that sequence for you, which is why every Teams migration creates a new destination team.
Supported scope
| Item | Carried across? | Notes |
|---|---|---|
| Team | Yes, as a new team | A new team is created in the destination tenant, with the source name or a name you choose. Importing into an existing team isn't supported. |
| Standard channels | Yes | Name and description are recreated. You can rename channels in the Windows app. |
| Private channels | Partly | Created as private channels with their messages. Private-channel membership and private-channel files are not copied. See Private channels. |
| Shared channels | Partly | Recreated as standard channels. |
| Channel messages | Yes | Original date kept. Posted as the mapped person when their destination account is found; otherwise the original name and email are shown at the top of the message. |
| Thread replies | Yes | Imported under their parent message (Include thread replies, on by default). |
| Team files | Yes | A companion file job copies the source team's document library into the new team's document library. |
| Members and owners | Yes, via user mapping | Added after the import finishes; owners stay owners. |
| Guests | No | See Guest users. |
| Reactions | No | Not copied. |
| Tabs, apps, Planner, wiki | No | See Tabs and apps. |
| 1:1 and group chats, meeting history | No | Only channels are migrated. Meeting recordings stored in OneDrive can be moved with a OneDrive file migration. |
Prerequisites
A Teams connection on each side
Add one Teams connection for the source tenant and one for the destination tenant. On the project's Connect tab, click Teams and choose:
- Connect with admin consent (recommended): a Global Administrator of that tenant approves the MigrationFox Teams app once. No Azure setup, nothing to copy.
- Bring your own Azure app: your organization's own app registration (client ID, secret and tenant ID).
Application permissions (the MigrationFox Teams app requests these; your own app needs the same, with admin consent granted):
Teamwork.Migrate.All: import messages with their original dates.ChannelMessage.Read.All,Channel.ReadBasic.All: read source channels and messages (this is the protected API that needs Microsoft's approval).Team.ReadBasic.All: read teams.TeamMember.Read.All,TeamMember.ReadWrite.All: read members, and add members and owners to the new team.User.Read.All: match people across tenants.Group.ReadWrite.All: create and manage the destination team.Sites.ReadWrite.All: copy the team's files.
Delegated (signed-in user) tokens are not accepted by Microsoft's import API, so a Teams connection is always app-only and tenant-wide.
Source address → destination address
Across tenants, a person usually has two different addresses: john@source-company.com → john@dest-company.com. The wizard's Users step matches source members to destination accounts automatically where it can, and accepts a CSV with sourceEmail and destEmail columns (leave destEmail empty to skip a person).
With Skip unmatched users off, unmatched people are mapped to the same address, which only works for moves within one domain. Messages from people who can't be resolved at the destination show their original name and email at the top. Members with no mapping are not added to the team, and the migration's log lists them. Fix the mapping up front: messages already imported keep the author they landed with.
How the migration runs
In your project, open the Migrate tab and click Start on Teams & chat (in the Windows app: Teams & chat). Choose Teams → Teams, then go through Source, Teams, Destination, Users and Review. Each selected team runs as its own migration:
- Destination team. A new team is created in the destination tenant in migration mode, which lets messages keep their original dates.
- Channels. Each selected channel is created (the built-in General channel is reused), with its name and description.
- Messages. Messages are read from the source and imported oldest first, then thread replies under their parents. A message that fails is logged and the rest continue.
- Complete migration. Each channel and then the team are switched out of migration mode, so the team becomes a normal team.
- Members. Members and owners are added through the user mapping. Guests are skipped.
- Files. A companion file job copies the source team's document library into the new team's document library.
Links in messages
Messages often contain links to files, SharePoint pages and other Teams resources in the source tenant (for example source-company.sharepoint.com or teams.microsoft.com/l/... deep links). MigrationFox does not rewrite these links. After the migration they still point at the source tenant, so they work only while the source exists and the reader has access to it. File and tab cards embedded in messages are removed from the imported text.
If people rely on those links, plan to keep read access to the source tenant for a while, or update important links by hand after cutover.
Guest users
- Members in your tenant are added to the new team after the import, through the user mapping, keeping their owner or member role.
- Guests are not added. Invite them into the destination tenant as B2B guests and add them to the team in Teams or the Teams admin center.
- Messages written by guests are imported; when the guest can't be resolved to a destination account, the message shows their original name and email at the top.
Check owners after the run
If no source owner can be matched at the destination, the new team has no owner, and the migration's log says so. Add an owner in Teams or the Teams admin center so the team can be managed.
Private channels
Private channels are created as private channels in the new team, and their messages are imported the same way as standard channels. Two things are not copied today:
- Private-channel membership. Members are added to the team, not to individual private channels. Add people to each private channel after the migration.
- Private-channel files. In Teams, a private channel keeps its files on its own SharePoint site, separate from the team's site. The companion file job copies only the team's own document library. Move private-channel files with a separate SharePoint migration.
Tabs and apps
- Tabs (file, website, Planner, wiki and app tabs) are not recreated.
- Planner plans don't move with the team.
- Apps installed in the team, including third-party apps and connectors, are not installed in the new team. Reinstall the ones that matter.
- OneNote notebooks stored in the team's document library are copied as files with the rest of the library.
Known limits
- Teams as a source is pending Microsoft approval for the MigrationFox Teams app (see the note at the top of this page).
- A new team every run. Running the same team again creates another destination team. Delete test teams when you're done.
- Reactions are not copied.
- 1:1 and group chats are not migrated. Only channels are in scope.
- Very old messages. The new team and its channels are created with a start date of January 1, 2020, and Microsoft's import only accepts messages dated after the channel's start date, so older messages can fail to import. Failed messages are recorded in the migration's log.
- Meeting recordings live in OneDrive or SharePoint. Move them with a file migration, not the Teams migration.
- Power Automate flows tied to a team don't migrate. Use the Power Platform inventory to list them.
- Channel email addresses are new in the destination; the source addresses stop working after cutover.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| “Microsoft hasn't approved this app to read Teams messages yet (protected Teams APIs)” | Microsoft's protected-API approval for reading channel messages hasn't been granted to the app used for the source. | With your own Azure app, request access through Microsoft's protected API form. With the MigrationFox Teams app, contact support. |
| “The Teams connection is missing a permission” (Graph 403) | Admin consent wasn't granted, was granted in a different tenant, or your own app is missing one of the Application permissions above. | Have a Global Administrator of that tenant connect again with admin consent, or add the missing permission to your app and grant admin consent. |
Messages show [Name (email)] at the top instead of appearing as the person |
The source address isn't in the user mapping, or the mapped account doesn't exist in the destination tenant. | Fix the mapping and run again into a new team. Messages already imported keep the author they landed with. |
| Links in migrated messages still point at the source tenant | Links are not rewritten. | Keep access to the source for a transition period, or update key links by hand. |
| Guests are missing from the new team | Guests are not added automatically. | Invite them into the destination tenant as B2B guests, then add them to the team. |
| Private-channel files are missing | Private channels keep files on their own SharePoint site, which the companion file job doesn't copy. | Copy those sites with a separate SharePoint migration. |
| Team files are missing | The companion file job hasn't finished or hit errors. | Check the migration's log on the project's Migrate tab for the channel-files step. |
Related
- Slack to Teams migration: the same Teams import API, with Slack as the source
- SharePoint Site Migration: the SharePoint sites that hold team and private-channel files