At Quest, we are aware that our customers and partners experience many Teams chat migration challenges, particularly when it comes to migrating private chats. I explored these challenges in my post on Practical365.com. We evaluated the available options.

Private Teams chat migration options

1. Use the Graph API for reading private chat messages – not possible since we cannot find the chat ID using the Graph API.
2. Use the Export API for reading private chat messages.
3. Write the private chat messages to a folder in Outlook in the target tenant. However, the private chat messages are not displayed in Teams at all. There is a lack of continuity with this solution that the users would have to accept.
4. Migrate all the private chat messages from source to the target so that they appear in Teams. This provides the most complete expected user experience.
5. Migrate the most recent messages and leave the remainder behind in the source tenant. This provides partial user experience because not all the messages are migrated.
6. Migrate the most recent messages and write the remaining messages to an HTML file. This provides a partial user experience; but a better one since all messages are available to the users.
7. Merge messages in a thread together into single messages.
8. Avoid adding external users to target chats.

We reviewed these Teams chat migration proposals and weighed them with benefits and costs. We decided which were best to add to the product. Let’s study the options.

1.    Use the Graph API for reading private chat messages

The Graph API does not support exporting private chats. The main problem is that the Graph API does not have a method to find the chat messages using the chat ID. Thus, we cannot use the Graph API for reading private chat messages.

For more information on the Microsoft Graph API, go here https://docs.microsoft.com/en-us/graph/use-the-api

Note: We do use the Graph API for reading Teams channel messages.

2.    Use the Export API for reading private chat messages

We use the Export API for reading private chat threads and messages because it is the only way to do it. The Export API also provides very fast reading – up to ten times faster than writing with the Graph API.

For more information on the SharePoint Migration Export (Asynchronous Metadata Read) API, go here https://docs.microsoft.com/en-us/sharepoint/dev/apis/export-amr-api.

3.    Write the private chat messages to a folder in Outlook in the target tenant

With this solution, the private chat messages are not displayed in Teams at all. There is a lack of continuity with this solution that the users would have to accept. That is, users cannot continue to use Microsoft Teams to work with the same private chats that they had in the source tenant. Storing the messages in Outlook seems more like an archiving solution.

4.    Migrate all the private chat messages from the source tenant to the target tenant so that they appear in Teams

This provides the most complete expected user experience for a Teams chat migration. However, our solution requires us to use a Teams administration account to write messages to private chats. Thus, we don’t impersonate the message owners while writing the messages. Instead, the Teams administration account appears as the thread owner. This approach also allows us to run incremental migrations on chat messages. There is a huge benefit to running incremental migrations as a project reaches the cutover date. Later, the Teams administration account can be removed from the private chat threads.

However, this does lead to some confusion when users expect to see themselves as owners or members of chat threads and messages.

Note: The account used for performing the Teams chat migration is often referred to as a service account. The service account is not meant to represent a real user and can be disabled or removed when the migration is completed.

5.    Migrate the most recent messages and leave the remainder behind in the source tenant

This option is like #4 – migrating all messages (with the limitations described above). This provides a partial user experience because not all the messages are migrated. Instead, we can limit the total number of messages migrated to improve the overall Teams chat migration throughput performance.

The benefit to the user is that they get their most recent private chat messages migrated to their new tenant in a shorter time.

The cost to the user is that they are missing older private chat messages that remain behind in the source tenant.

6.    Migrate the most recent messages and write/archive the remaining messages to an HTML file

This option is also like #4. However, this option will probably provide the best user experience since all the messages are migrated. The benefit to the user is that only the most recent messages are migrated directly into Teams.

The cost to the user is that older messages are stored in HTML files and linked from within private chats. Thus, these messages are still available in the Teams client, but not in the chat view. The messages are available in the HTML (archive) files, but cannot be searched or read as quickly and easily. However, the messages are available to the user.

This approach to Teams chat migration should run faster than when migrating all messages directly to Teams, but it is still dependent on reading all the messages on the source. Furthermore, it would be best to migrate the fewest messages directly to the Teams client during the cutover period. Then write/archive the remaining messages to the HTML (archive) files after the cutover period. You may also want to limit how far back in time to read messages for the purpose of archiving. This would help to reduce how long you need to maintain access to the source tenant.

We are currently working on a solution to support each of these scenarios and plan to release it very soon.

The image below displays what an HTML (archive) file would look like.

HTML (Archive) File Viewed in a Web Browser

7.    Merge messages in a thread together into single messages

We found that merging messages can result in a faster Teams chat migration. As noted in #2, the Export API provides very fast reading – up to ten times faster than writing with the Graph API. Thus, any performance improvement in writing messages should lead to an increase in throughput. So, the solution here is to merge messages read from the source tenant together into manageable sets and then migrate together as a single message on the target tenant.

The Graph API does not support batching of messages for writing. Thus, we created our own batching solution by “batching” the content of multiple messages in a thread and writing them at one time.

Consider a set of original messages in the source tenant as shown below:

Source Chat Messages

When this message set is migrated without merging, it appears in the target tenant as shown below. Each message is a separate entity. Messages retain their chronological order and the time stamp is converted to GMT.

Chat Messages Migrated Without Merging

When the message set is merged and migrated, they appear in the target tenant as shown below. The migration service determines the merge set. Messages retain their chronological order and the time stamp is converted to GMT.

Chat Messages Migrated With Merging

The merge message feature is enabled by default for migrating messages in our product.

8.    Avoid adding external users to target chats

Migration throughput performance can also be improved by avoiding adding external users to the chats that are migrated to the target tenant. The external users can always be added later to a private chat if required. The external users would still see the old private chats.

Setting for Avoid adding external users to target chats in migration

Conclusion

When it comes to Teams chat migration, quickly moving private chat messages between tenants is difficult. It can be challenging to migrate the messages to the target in a short time and hit the planned target date. However, we have solutions for our customers and partners. We recommend:

• Migrating private chat messages into Microsoft Teams
• Merging messages during migration
• Considering whether or not to include external users
• Migrating minimal messages
• Archiving the minimal amount you need after migration

We continue to look for ways to improve the content fidelity and migration throughput performance of private chat migrations.