Microsoft Teams chat migration explained

Given the widespread adoption of Microsoft Teams in the past few years, Microsoft Teams Chat has become a key component of Microsoft 365 tenant-to-tenant migrations. As a Microsoft 365 technical consultant who performs hands-on-keyboard work and speaks with business stakeholders, I’ve found that most clients are not prepared for the nuances of chat migrations and assume that they can be migrated like any other workload in Microsoft 365; this is not the case.

Whether you’re a technically minded stakeholder who is seeking clarity on the impact that a Teams Chat migration will have on your business, or a technical specialist like me who is responsible for the migration work, this post will tell you what you need to know about Microsoft Teams Chat migrations.

What is considered a Microsoft Teams chat?

I’ve worked with plenty of stakeholders on tenant-to-tenant migration projects who have asked for clarity on what qualifies as a Teams chat, as they are easy to confuse with Teams channel messages.

Microsoft Teams chats are the conversations that appear when you have opened the Chat panel from the side rail in Teams (that’s the menu bar on the left side of Microsoft Teams). Chats are associated with users, not with teams.

Microsoft Teams Chat app











The Teams Chat app in Microsoft Teams.

A chat in Microsoft Teams









A chat in Microsoft Teams.

When you click on the Teams option in the side rail in Teams and open a channel, the conversations you see are channel messages. These are not considered to be chats and would be migrated along with your Microsoft Teams teams. I have worked with most of the major Microsoft 365 tenant-to-tenant migration tools that are currently on the market, and this is true for all of them.

Chats can be one-on-one, with a group of people, or with yourself. If your external access settings allow it, you can even chat with people outside your organization.

Finally, you may have noticed that my capitalization of “chat” has been inconsistent in this article. To clarify the proper language, grammar and capitalization per Microsoft: Teams Chat (proper noun, capitalized) refers to the core app within Teams, while a chat (common noun, not capitalized) is a conversation within Teams Chat. Just like Microsoft Teams (proper noun, capitalized) has teams (common noun, not capitalized) and we migrate Teams teams. Not confusing at all, right?

Can Microsoft Teams chats be migrated without a third-party migration tool?

At the time of writing this post, Microsoft Teams chats can only be migrated with Microsoft’s APIs – requiring advanced development skills and experience, or a third-party migration tool that leverages those APIs. Even with in-house development expertise, it is more cost effective to license a third-party migration tool than to build your own migration scripts.

What are the limitations of a Microsoft Teams Chat migration?

It is important to set expectations during a tenant-to-tenant migration that Teams Chat migration capabilities are limited compared to other products in the Microsoft 365 suite. To understand these limitations, it’s important to know what an API is.

Understanding APIs

For those who are unfamiliar with APIs, put simply, these allow developers to write code that communicates with a program. APIs are not always available to everyone, but Microsoft has made some of theirs public to allow third parties to build apps that extend or interact with Microsoft 365 products.

Apps like Microsoft Outlook and Exchange have existed for a long time and have remained more or less the same for many years. Over those years, migration software companies have had time to refine their tools and processes. On the other hand, apps like Microsoft Teams have been around for a relatively short time, with functionality that changes rapidly. Microsoft Teams was around for a few years before the APIs for Teams Chat were made publicly available, and there are still parts of Microsoft Teams that are not included in Microsoft’s public APIs.

Different migration tools handle Teams chat migration differently, but the following limitations are generally true for all Microsoft 365 tenant-to-tenant migration software:

  • Chats cannot be migrated for users without Microsoft Teams and OneDrive for Business licenses.
  • Files that are migrated are not migrated with the chat; rather, links to migrated files are added in line with the migrated messages.
  • Chats that are initiated by external users cannot be migrated, as migration software does not have the ability to see inside another organization’s tenant and “read” the chats that are associated with that user.
  • Users cannot be blocked from signing into the source tenant or the target tenant.
  • Users who are not mapped in your migration software will not be migrated.
  • Loop components in chats cannot be migrated.
  • One-to-one chats with Skype users cannot be migrated.
  • Chats cannot be truly migrated; migration tools with the ability to “migrate” chats to Teams work around this by recreating chats in the target tenant.
    • For tools with this capability, 1:1 chats are recreated as group chats.

To fully understand what is not supported in Teams Chat migration, so that you and your organization are prepared, read through the documentation for your chosen migration software.

What is the migration process for Microsoft Teams chats?

In my experience, there are two main methods of migration: recreating the chats from the source as “live” chats in the target, and migrating chats to an archive location in the target (such as OneDrive or email). Different migration products handle Teams Chat migration differently, so it is important to understand which methods they support.

Regardless of the migration method that you use, when working with third-party tenant-to-tenant migration software, Teams Chat migration is handled in a separate location than Teams team migrations, and efforts should be estimated accordingly.

The files attached to or linked from your Teams chats may also be in a separate area – either  your OneDrive for Business sites, Microsoft Teams teams, SharePoint Online sites or all of the above – and should be migrated along with your conversation history.

Planning the migration effort for Teams Chat migrations

A common misconception is that Microsoft Teams Chat is migrated along with Microsoft Teams teams. Again, Microsoft’s product names can be confusing. As Microsoft Teams is the name of the program that includes Teams Chat, one might imagine that chats would be migrated in the same location. However, because the functionality is separate – with Teams Chat and Teams considered separate core apps within Microsoft Teams – migration software handles chats and teams separately. When you see “Microsoft Teams” in migration software, this includes Teams teams; the functionality for Teams Chat is in a different location.

When you configure a migration project for Teams Chat within Microsoft 365 tenant-to-tenant software, you do this with a list of users, in an area that is specifically for Teams Chat migration; when you configure migration projects for Teams teams, you do this with a list of teams, in an area that is designated for a Teams migration.

How this impacts your migration effort is that the technical staff who are responsible for the migration must create separate migration lists, configure separate migration tasks and policies and review separate migration logs for both Teams Chat and Teams teams. This additional effort should be accounted for in your migration planning.

Recreating Microsoft Teams chats (migrating to live chats)

At the time of writing this post, Teams chats cannot technically be migrated from one tenant to another like for like. Users cannot be impersonated by migration software in the context of Teams chats, so to get around this limitation, conversations must be “read” by a migration application or service account in the source tenant, copied and recreated by a service account in the destination tenant. In migration software, this is referred to as migrating to a “live” chat, or as “recreating” chats in the target.

A benefit to this method of Teams Chat migration is that users may find it more straightforward to find their migrated chats, as they will go to the same place (the Chats app in Teams) to see their conversations. The contents of those conversations can also be searched from the Teams search bar.

The full live chat migration process is as follows for all migration tools that offer it:

  1. In the source tenant, the migration app or service account “reads” a user’s Teams chats: which chats exist, which users are in the chat and the contents of the chat.
    1. Attachments are migrated as links to their new location in the target tenant.
  2. Migration software acts as a broker between the source and destination tenant to move data.
  3. In the target tenant, the service account creates group chats to mimic the conversations in the source tenant. After adding the participants to the chat, it posts messages with the original conversation history.
  4. The service account is removed either automatically or must be removed programmatically (depending on the migration software).

Microsoft Teams chat migration example- showing how this looks in a third-party Teams migration tool










An example of a Microsoft Teams chat that was migrated by a third-party migration tool, using the method where the chat is recreated by a migration service account. Note the migration account posts the conversation history on behalf of the chat participants.

Important user experience considerations for recreating Microsoft Teams chats (migrating to live chats)

While recreating Microsoft Teams chats (or “migrating to live chats”) may seem like the most straightforward migration method, it is quite disruptive to users, and there are a number of considerations that are imperative to understand before migration:

  • Chat notifications will be a nuisance for everyone post-migration. Every time a chat conversation is recreated by a service account, it appears as a brand-new conversation and creates notifications. Depending on a user’s activity in the source tenant, a Teams chat migration could create hundreds of notifications and chats for a user to click through.
    • Luckily, New Teams added the option to “Mark all as read” for chats.





  • New chats appear not just for the user whose chats you are migrating, but for all the users they are chatting with, whether you are migrating them or not (as long as they are part of the same tenant and are mapped in your migration software).
    • If you are migrating to a target tenant that is actively used and are migrating in waves, I highly recommend you avoid the “live” chats migration method if possible. If it is acceptable to migrate only the attached and linked data and not the conversations themselves, you can achieve this through OneDrive, Teams and SharePoint migration.
  • Due to limitations with migration APIs, 1:1 chats cannot be recreated as true 1:1 chats; instead, they are recreated by a service account, making them group conversations. Post migration, if a Teams user messages someone directly, none of their conversation history will be in that chat. This may be confusing.
  • Naming your service accounts in a way that is friendly to end users is important for all migration workloads that leverage service accounts; with this Teams Chat migration method in particular, you must name your service accounts before migration, as the name and address of the accounts are visible to end users in multiple places, and this cannot be changed post-migration. For example, if you used John Smith’s user account as the service account, all chats would show that John Smith was added to the conversation, and this cannot be changed.
    • If you wish to add an image to a service account, make sure to do it before the migration cutover; although it can be changed after migration, typically Teams caching means that end users do not see the new photo for weeks, unless they log out and back into the Teams client.

Migrating Microsoft Teams chats to archives (OneDrive or email)

Some migration tools can move chat history to email; other tools can move chat history to OneDrive for Business. While these may not be referred to as “archive” migrations, I would still consider them to be archives, as they are moved to a different location than Teams.

Some migration tools opt to create new conversations in the Teams Chat app even if you have opted to only migrate to archives. Double-check whether your chosen migration software creates new chats in Microsoft Teams Chat to contain conversation archives; if it does, please carefully review the advice in the previous section of this post: Important user experience considerations for recreating Microsoft Teams chats (migrating to live chats).

What happens to Teams chat attachments in a tenant-to-tenant migration?

Architecturally speaking, Microsoft Teams stores the attachments that are uploaded from your device to Teams Chat in a folder in your OneDrive for Business documents titled “Microsoft Teams Chat Files.” Therefore, files within Teams chats are migrated with OneDrive for Business data.

You can also attach cloud files to Teams chats. These are files that live in OneDrive or shared libraries across Microsoft Teams and SharePoint Online. When you attach a cloud file to a Teams chat, it looks very similar to a typical attachment, but you’re only sharing a link to the file, which remains in its original location. In my experience, this is typically only used by users and companies with strong cloud collaboration knowledge and processes.

Attaching files in a Microsoft Teams chat

When attaching files to a Teams Chat message, any files you attach via “Upload from this device” are uploaded to the Microsoft Teams Chat Files folder in your OneDrive for Business documents. If you choose “Attach cloud files,” you can attach links to files in locations you have access to within Microsoft Teams and SharePoint Online.

When planning a tenant-to-tenant migration, it is recommended to migrate OneDrive for Business sites before migrating Microsoft Teams chats to ensure that file attachments are available within Teams Chat. Some migration tools offer the option to migrate OneDrive for Business data with your Teams Chat migration; even if this option is available, I recommend migrating your files separately to improve migration task performance and the ability to troubleshoot migration logs.

If your organization or the organization you are working with leverages cloud collaboration at an advanced level (coauthoring in cloud locations, opting for links to cloud locations rather than attaching files), I also recommend that you migrate your SharePoint Online sites and Microsoft Teams teams prior to any of your migrated users signing into the target tenant.


Microsoft Teams Chat migration is a relatively new part of Microsoft 365 tenant-to-tenant migrations, and it is important to understand the experience of migrating Teams chats from both the migration project team and the end user’s perspective. The various migration tools on the market each handle Teams Chat migration differently; if you want to be well equipped for migrating Teams chats, you must not neglect to read through the documentation for your migration software.

Top 10 must-do actions for a successful Teams migration

Learn from Microsoft admins the most common issues to avoid and key actions to take to ensure a successful Teams migration.

Watch On Demand


About the Author

Karin Skapski

Karin Skapski is a Senior Solution Architect for Microsoft. Collaborating with Microsoft partners, she focuses on enhancing their technical expertise and enabling them to deliver impactful solutions for their customers. Previously, Karin worked with Microsoft cloud technologies in a hands-on technical consulting role, focusing on migration, collaboration, and governance. Her experience spans private and public sector organizations of all sizes and in various industries.

Related Articles