Teams Private Chat Migrations

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.’
    • 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


  1. 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.
  2. Wait for the cut-over. This is because any change in UPN will affect the OneDrive document links.
  3. Use the UserMapping Advanced Option to map the source user’s UPN to the destination user’s UPN.
  4. Mailbox or UMB licenses are required.

What data will be migrated?

Migrated Not Migrated

Chat titles
(If there’s no title, participant names will be shown by default)


Chat participants

GIFs Polly

Embedded images

Saved messages

File Attachments
(A completed OneDrive migration with necessary permissions is required for this to be successful)

Chats from deactivated users

Chats marked ‘Important’
(Email item will appear flagged as ‘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)

Deleted Chat messages  



  1. Private chats with image attachments will include both the attachment and the link to OneDrive.
  2. 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: 

  1. Set up OneDrive project.
  2. Start OneDrive migration.
    1. Migrate both documents and documents permissions.
      1. Ensure document permissions are mapped and migrated correctly.
      2. Ensure all user mappings are added.
  3. Ensure the OneDrive migration (documents & documents permissions) has been completed successfully before proceeding with the Teams private chat migration.
  4. 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. 

  1. Add the following Advanced Options where applicable. (Optional) 
    Advanced Options Description 

    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. 


    • 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.


    The migrated folder "Migrated Teams Chat" will be visible by default. This option can be added to hide the folder by default. E.g.



    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. UserMapping=">"

Add Users/Mailboxes 

    1. Add mailboxes via Autodiscover or Bulk Add.
    2. Use a date filter if required, as private chats can be large.

Start Full Migration 

  1. 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. 
  2. 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.

Was this article helpful?
0 out of 0 found this helpful