Command
Copy-Chats
Description
The command to copy chats from one Microsoft 365 tenant to another.
Note: Chats cannot be copied to the same tenant. You can only copy chats to another tenant.
Index
Prerequisites
- You have global admin permissions.
- The Azure ShareGate migration tool application is consented on your tenant.
- To use Copy-Chat the migration tool requires additional delegated and application permissions. To consent to these permissions, see Consent for Microsoft Teams private chat migrations.
- You have a working Teams license for the source and destination.
- You have logged into Teams at least once (in a browser or the Teams app) to access the hosted content.
Note: The prerequisites apply to your source and destination.
Behavior
- For each chat, a maximum of 50 messages posted in the last 30 days are copied. For example, only one message would get copied if it was the only one posted in the last 30 days.
- All other messages are copied into an HTML history file.
- The migration tool creates a single site collection to store all the HTML history files.
- The site is named ShareGatePrivateChatsHistory.
- Libraries with custom permissions are created to store the HTML history files and ensure only the chat participants can access them.
- Hosted content and code snippets posted in the chat are stored in the site collection.
- Chat participants can find their chat history in a corresponding Chat history tab the migration tool creates in their destination teams.
- Chat attachments are not copied. However, attachments are stored in your users' OneDrives that you can migrate from with Copy content only or through a PowerShell script.
- Chats with only 1 user are not migrated.
Caution: Avoid adding admins or modifying permissions in the site collection created along your chats to protect the privacy of your users. For more information, see What are the security implications of Copy Chats?
User mappings
Only the chats of users you explicitly map gets copied. You can export user mappings for your source and destination tenant with the Export-TenantUserMappings command. The export command generates an Excel document you can review and edit, then import it within your chat migration script.
Incremental copy
Each time you use the Copy Chats command with a new pair of tenants, the source tenant's chat history is copied to the destination tenant. Subsequent uses of the command with the established tenant pairing result in an incremental copy (i.e., a copy of only the objects that changed since your last copy).
Examples
Copy all source tenant chats
$sourcetenant = Connect-Tenant -Domain sourcetenant
$destinationtenant = Connect-Tenant -Domain destinationTenant
$mappingsSettings = Import-TenantUserMappings -Path C:\MyMappings\MyUserMappingsFileName.xlsx
Copy-Chats -SourceTenant $sourcetenant -DestinationTenant $destinationtenant -MappingSettings $mappingsSettings -Beta
Copy specific user chats
$sourcetenant = Connect-Tenant -Domain sourcetenant
$destinationtenant = Connect-Tenant -Domain destinationTenant
$mappingSettings = Set-UserAndGroupMapping -Source "User source 1" -Destination "User destination 1"
Set-UserAndGroupMapping -MappingSettings $mappingSettings -Source "User source 2" -Destination "User destination 2"
Copy-Chats -SourceTenant $sourcetenant -DestinationTenant $destinationtenant -MappingSettings $mappingSettings -Beta
Copy specific user chats from an SGUM file
$sourcetenant = Connect-Tenant -Domain sourcetenant
$destinationtenant = Connect-Tenant -Domain destinationTenant
$mappingSettings = Import-UserAndGroupMapping -Path C:\MyMappings\MyUserAndGroupMappingsFileName.sgum
Copy-Chats -SourceTenant $sourcetenant -DestinationTenant $destinationtenant -MappingSettings $mappingSettings -Beta
Syntax
Copy-Chats -SourceTenant <Tenant>
-DestinationTenant <Tenant> -MappingSettings <MappingSettings>
[-AcceptChatsCopyPrivacyRisks <SwitchParameter>] [-NormalMode <SwitchParameter>]
[-TaskName <String>]
[-Beta <SwitchParameter>]
Parameters
-AcceptChatsCopyPrivacyRisks <SwitchParameter>
Accepts the privacy risk of chat copy commands. Use this command when setting up automation to skip the privacy risk prompt.
| Required? | False |
| Default value | None |
| Accept pipeline input? | False |
| Accept wildcard characters? | False |
| Parameter set name | (All) |
| Aliases | None |
-DestinationTenant <Tenant>
Specifies the destination tenant.
| Required? | True |
| Default value | None |
| Accept pipeline input? | False |
| Accept wildcard characters? | False |
| Parameter set name | (All) |
| Aliases | None |
-MappingSettings <MappingSettings>
Specifies the mapping settings. Note that only the chats of mapped users are copied.
| Required? | True |
| Default value | None |
| Accept pipeline input? | False |
| Accept wildcard characters? | False |
| Parameter set name | (All) |
| Aliases | None |
-NormalMode <SwitchParameter>
Specifies that Normal mode will be used for the copy.
| Required? | False |
| Default value | None |
| Accept pipeline input? | False |
| Accept wildcard characters? | False |
| Parameter set name | (All) |
| Aliases | None |
-SourceTenant <Tenant>
Specifies the source tenant.
| Required? | True |
| Default value | None |
| Accept pipeline input? | False |
| Accept wildcard characters? | False |
| Parameter set name | (All) |
| Aliases | None |
-TaskName <String>
Specifies a name for the task.
| Required? | False |
| Default value | None |
| Accept pipeline input? | False |
| Accept wildcard characters? | False |
| Parameter set name | (All) |
| Aliases | None |
-Beta <SwitchParameter>
Acknowledges that the Copy Chats feature is in the beta phase and may be modified in the future.
| Required? | True |
| Default value | None |
| Accept pipeline input? | False |
| Accept wildcard characters? | False |
| Parameter set name | (All) |
| Aliases | None |
Training video: For more info, watch Copy chats.