MigrationWiz now migrates Teams private chats, including one-on-one chats, group chats, and meeting chats. Migrated chats will now be visible in Outlook, not in Teams.
Teams private chat migration must be done via a Mailbox migration flow (Microsoft 365 to Microsoft 365 only). Teams private chat migration is independent from the Collaboration project migration type.
The private chats may be migrated with a full mailbox migration, or separately after the mailbox migration has completed. Private Chat migrations (Mailbox project) may also be run concurrently with a Teams migration (Collaboration project).
After migration has completed, all the migrated private chats can be found within a new Migrated Teams Chat folder in Outlook. Chat rehydration at the Teams destination tenant is currently not supported.
Private chat messages are not searchable in the destination mailbox. Chats are migrated as "active content," preventing the mail client from searching for it.
The migrated private chats will be constructed as email items in the following format:
- "Sender" is the user who posted the specific chat message
- Email subject
- Group Chat
- If there is a title, the group chat title will be the email subject
If there’s no title, the email subject will show ‘Conversation with Name1, Name2, etc.’
- If there is a title, the group chat title will be the email subject
- 1:1 Chat
- Email subject will show ‘Conversation with <Name>’
- Meeting Chat
- Email subject will show the ‘Meeting Title'
- Email body content will show the specific chat message
- Group Chat
Prerequisites
- A OneDrive migration (both documents and permissions) must be completed prior to migration for any OneDrive links or attachments within the private chats to function. This ensures OneDrive links or attachments within private chats will be mapped correctly and migrated over to the destination. Otherwise, migration will succeed but the links will not be accessible.
- Wait for the cut-over. This is because any change in UPN will affect the OneDrive document links.
- Use the RecipientMapping Advanced Option to map the source user’s UPN to the destination user’s UPN.
- Mailbox or UMB licenses are required.
What data will be migrated?
Migrated | Not Migrated |
Chat titles |
Reactions |
Chat participants |
Forms |
GIFs | Polly |
Embedded images |
Saved messages |
File Attachments |
Chats from deactivated users |
Chats marked ‘Important’ |
Chats on external tenants (i.e. You are the guest of that tenant) |
Edited messages in a Chat |
Links directly pasted into chats, including documents and images. |
Praise (Icon/image not migrated) |
|
Stickers | |
Deleted Chat messages |
Limitations
- Private chats with image attachments will include both the attachment and the link to OneDrive.
- Chat history prior to the user’s addition into the group chat will not be migrated even if the ‘Include all chat history’ option was selected.
Migration Steps
Migrate OneDrive
Set up a Document migration project to migrate OneDrive. All files or links shared in Teams Private Chats are stored in the sender’s OneDrive folder. Therefore, a OneDrive migration has to be completed prior to migrating private chats to ensure the OneDrive links are mapped correctly and migrated to the destination.
Using the OneDrive for Business to OneDrive for Business migration guide, perform the following steps:
- Set up OneDrive project.
- Start OneDrive migration.
- Migrate both documents and documents permissions.
- Ensure document permissions are mapped and migrated correctly.
- Ensure all user mappings are added.
- Migrate both documents and documents permissions.
- Ensure the OneDrive migration (documents & documents permissions) has been completed successfully before proceeding with the Teams private chat migration.
- Refer to the OneDrive migration guide and how to use MapPermissionEmailByPairsInProject=1 if your users' prefixes are not matching.
Migrate Teams Private Chat
Set up a Mailbox project to migrate Teams Private Chat via the following steps. Use the Microsoft 365 to Microsoft 365 guide to perform the migration. The following steps provide additional guidance and should be used in correlation with the guide.
Create a Mailbox project
Only Microsoft 365 to Microsoft 365 Source and Destination endpoints are support for Teams private chat migration. This includes Microsoft 365 for China, Germany, and the U.S. Government.
- Add the following Advanced Options where applicable. (Optional)
Advanced Options Description MigratedTeamsChatFolder=XX The private chat items will be migrated to the ‘Migrated Teams Chat’ folder by default. This folder can be renamed using the advanced option MigratedTeamsChatFolder=New Folder Name (replace with your desired folder name). The folder name is both case and space sensitive.
Important: Do not use quotations ("") when entering this option. Use of quotations (E.g. "TestMigratedTeamsChatFolder") will result in an error.
Examples:
- MigratedTeamsChatFolder=TestMigratedTeamsChatFolder
- MigratedTeamsChatFolder=Test Migrated Teams Chat Folder
This option should be added at the project level before starting the migration. If folder has to be renamed again after a migration pass, the older folder that was already migrated should be deleted before resetting and rerunning the migration.
HideMigratedTeamsChatFolder=1 The migrated folder "Migrated Teams Chat" will be visible by default. This option can be added to hide the folder by default. E.g.
HideMigratedTeamsChatFolder=1
RecipientMapping / UserMapping RecipientMapping / UserMapping should be done for the OneDrive links to work in the destination. The migration will still go through if this is not done, but the links will not be valid anymore.
E.g. RecipientMapping="@SourceTenant.com->@DestinationTenant.com"
Add Users/Mailboxes
-
- Add mailboxes via Autodiscover or Bulk Add.
- Use a date filter if required, as private chats can be large.
Start Full Migration
- In the Start Migration flyout, select 'Teams Private Chat' checkbox to migrate Teams Private Chats. Teams private chat can be migrated individually or selected along with other mailbox item types.
- Once the 'Teams Private Chat' checkbox is selected, a message alert regarding OneDrive will be prompted. Click OK to proceed if OneDrive migration has been completed prior.
Post Migration
Once the migration has completed successfully, all the migrated chat items can be found in the 'Migrated Teams Chat' folder in Outlook.
The total number and size of chats migrated are reflected under 'Migrated Items' in the Reports section.
Am I missing file extensions?
Some users report issues viewing file extensions for embedded images after migration. This is expected behavior, and will not cause issues with migrated items.
-
Whenever an embedded image is pasted/uploaded into a private chat window, Microsoft generates a file to store the pixel information of that image. The filename is also auto-generated by Microsoft.
-
Post migration, the corresponding file (with an auto-generated filename) is displayed as an attachment and the image will still be viewable under ‘Preview’.
Refer to the Teams FAQ for more information on Private Chat migrations and other questions.