Large tenant-to-tenant migrations often run into problems when it comes to Microsoft Teams private chat migrations. The main challenges are throughput and content fidelity. This post outlines the challenges of migrating Teams private chats so you can prepare your migration project plan accordingly.

Low bandwidth for Microsoft Teams private chat migration

There are many more private chat messages today than there were 3 years ago due to the incredible growth of Teams during the pandemic. Some organizations with tens of thousands of users may have millions of private chat messages when migrating Teams. This migration can take a long time to implement. The problem of migration from tenant to tenant is that there are more private chat messages that need to be migrated than most companies can imagine.

There are the following problems when migrating chats:

Timing for migration of private chats

The problem is determining the best time to reschedule private chat messages. Most organizations want to complete their chat migration at a predetermined switchover point. This ensures that users receive the latest messages in the source tenant and messages are added to the destination tenant in the correct order. But this is difficult to achieve when migrating Teams. And there are implementation options:

  1. Record private chat messages to a folder in Outlook in the target client. However, writing these messages to an Outlook folder will not display the same messages in the Teams client. Therefore, messages are not readable or searchable in the Teams client.
  2. Migrate all private chat messages from the source to the target tenant so they appear in Teams. This ensures the best possible compliance with end-user expectations. If possible, consolidate private chat messages into fewer messages. 
  3. Migrate the most recent messages and leave the rest in the original client. This provides a partial user experience because not all messages are transferred.
  4. Migrate the most recent messages and write the remaining messages to an HTML file. The HTML file is stored in the folder Microsoft Teams chat files in the OneDrive of the user who initiated the original private chat, and direct permissions assigned to other users in the private chat. Users can open the HTML file to search and read messages. The problem for users is that they have to look for messages in two places:
    • In team chat
    • In HTML files containing archived chats
  5. Write all private chat messages to an HTML file. This also provides a partial user interface, but the user cannot access their messages directly in Teams (unless the HTML files are added later to the private chat). Additionally, the user must search for messages in HTML files containing archived chats.


There are two Graph APIs for reading and one for writing. The APIs do not support batch processing. Batch processing will greatly improve performance. That is, batch processing allows multiple messages to be read and written in a single process. This is because Microsoft also enforces message throttling.

Content is not transferred with high fidelity

There are two APIs (Export and Graph) for reading the content of private chat messages from the source client:

SharePoint Migration Export API (asynchronous metadata read)

  • Allows multiple reading of messages depending on the number of chat participants
  • Allows incremental migration
  • Does not support batch processing
  • Roughly the same content accuracy as the Microsoft Graph API
  • Allows you to find private chats (and chat ID) and read chat messages.

Microsoft Graph API

  • Allows incremental migration
  • Does not support batch processing
  • Cannot find private chats (or chat ID); nor find messages in private chats. Information about private chats is not available.

Thus, you can only use the Export API to search for private chats and read messages.

Only the Microsoft Graph API can write the contents of a private chat message to the target client:

  • It is not possible to impersonate the original owner of a chat message when writing messages. This means that users do not consider themselves to be the creators of the migrated private chat thread or the messages in the thread. The owner is the user account used to transfer private chat messages.
  • Write speed matches Microsoft Graph API read speed (which cannot be used for chats and chat messages); but it is much slower than the reading speed of the Export API (which is used for chats and chat messages). 

Other problems

Of course, there are other issues to consider when migrating chat messages:

  • Message notifications. Users can receive a huge number of notifications in Teams. This is a common complaint from users when transferring private chat messages. The easiest way is to ask users to turn off notifications in the Teams client settings in their target tenant. Click User to configure individual notifications and disable all settings during the migration. However, this may not be possible if users cannot yet access the target tenant.
  • Identification of the author or owner of the message. This cannot be done using the Graph API. The import API supports identifying the author or owner of messages, but only for channel messages.
  • Skip selected messages (eg bots). Yes, this will reduce the number of messages in private chats. But bots are not yet widely used in personal chats. 
  • Including external users when migrating private chat messages.

Still have questions?

The migration process can be long and lead to results that are not at all what were originally planned. To prevent this from happening, we advise you to immediately contact a reliable Cloud Solutions Provider in Kazakhstan, such as Fanetech. We are a Microsoft Gold Partner and customize the MS stack to suit the needs of our clients. Just contact us for any questions migration and get advice.

en_GBEnglish (UK)