Note: PowerShell integration requires a ShareGate Migrate Pro or Enterprise subscription. It is not available on the Essentials plan.
Copying Microsoft Teams private chats with Copy-Chat relies on the Microsoft Graph API, and several limitations apply.
Selected users are the users whose chats you copy with the -Users parameter. Only selected users are added as members of a chat at the destination, so only they can see it there.
Mapped users are the source and destination pairs in your user mappings. ShareGate Migrate posts messages at the destination under the mapped user. Mapped users don't have to be selected users.
For recommendations on getting the best results, see Copy private chats - Best practices.
Users and mappings
Every member of a chat must be mapped, except deleted, external, and guest users. If a member isn't mapped, ShareGate Migrate doesn't copy that chat because it can't match the source user to a destination user.
Mapped users who aren't selected still appear as the author of their messages, but they aren't members of the chat at the destination and can't see it.
Messages from deleted, external, and guest users are posted under Unknown user, with the original name kept.
Copies between the same source and destination tenant pair must run on the same machine. ShareGate Migrate can't detect chats that another machine already copied, so if users who share a chat are split across machines, each user ends up alone in their own copy of that chat.
Chats
All chats are created as group chats, including one-on-one chats and meeting chats. ShareGate Migrate needs to add and remove chat members to adjust their history visibility, which one-on-one chats don't support.
The copy range has a start date only. ShareGate Migrate can only validate chat members as of the current time, so there is no end date.
Messages
File attachments are not copied.
Custom reactions set by your organization are not supported.
Read status is not preserved. All copied messages show as unread at the destination.
Messages from apps and bots are not copied, including Adaptive Cards such as approvals, polls, and meeting recaps.
Deleted messages are not copied.
Copied chats may not appear right away in Microsoft Teams. This is a display delay in Microsoft Teams, and no data is missing. Ask users to sign out of Microsoft Teams and sign back in if they don't see their chats.
Incremental copies
Edited messages and changed reactions are not updated at the destination.
Members removed from a source chat are not removed at the destination. If a mapped member was removed from the source chat since the last copy, ShareGate Migrate skips that chat's incremental copy so the removed member can't see newer messages. The report names the skipped chat.
Changed user mappings between incremental copies prevent chats that include those users from being copied, because ShareGate Migrate can't edit the author of messages it already copied. Deleting the chat at the destination lets ShareGate Migrate copy it again.