Set up a chat migration

If you're transitioning to Google Workspace, you can use chat migration for the new data migration service to move your users' chat messages from Microsoft Teams to Google Chat.

Except where indicated, perform the following steps in the Google Admin console of your Google Workspace account (the account you're migrating to). Make sure a super administrator sets up and runs the migration. Resellers can't migrate data for their customer accounts. 

Migration timeline

Important: Be aware that you must complete the entire migration process, including rolling out the spaces, within 30 days of the start of the migration. The migration process includes the steps below and the steps in Run a migration. If you don’t complete within the timeline, the migration fails.

Step 1: Connect to your Microsoft account

1. Sign in to your Google Admin console.

   Sign in using an account with super administrator privileges (does not end in @gmail.com).

2. In the Admin console, go to Menu  DataData import & exportData migration.
3. For Microsoft Teams, click Migrate.
4. Click Connect to Microsoft account and sign in as a Global Administrator with your Microsoft account.

   If you're successful, you get a Connected message. If you're unsuccessful, make sure you're using a Global Administrator account to sign in to Microsoft.

Step 2: Create a list of teams to migrate

Chat migration transfers the channels that belong to the teams in the list. You can create a comma-separated values (CSV) file, or you can update an existing file to match the needed formatting.

Important: The CSV file must be smaller than 10 MB and have fewer than 150,000 rows of data.

If you want to update an existing file, choose an option:

• Select Example file and click Download sample CSV to get an example file.
• Select Teams' list CSV file and download the file from the Teams admin center. For details about exporting the file, go to Manage teams in the Microsoft Teams admin center.

If you're creating your own file:

1. Open a spreadsheet program.
2. In the first column, add the header Source MicrosoftTeamsID.
3. On separate rows, add the groups ID of the teams that you want to migrate.
4. Save the spreadsheet as a CSV file.

Example:

Source MicrosoftTeamsID

8f445146-9d80-b020-d50d5589ab

bd4685f0-61f2-4789-4c1cda85d93

d0bef58c-9a55-4d8d-976c89n006

Step 3: Upload the file

1. In your Admin console, click Upload migration map CSV.
2. Go to and select your CSV mapping fileclick Open.
3. Click Tasks to confirm that the mapping file is successfully uploaded.

Step 4: Create & upload an identity map (if required)

Next, create a file to map users' email addresses from the source account to the Google Workspace account. An identity map is not always required. You don't need an identity map in the following situations:

• The user's email address on the source account is the same as their address in Google Workspace. For example, the user's email address is [email protected] for their Microsoft and their Google Workspace account.
• All users keep the same username in the target account and are mapped to another domain name. For example, all users have the domain name @example.com and are moving to the domain name @altostrat.com. Users have the same username on the source and target accounts, but the domain name changes.

In these situations, you can use the settings in step 5 (later on this page) to migrate the users' email addresses

If you have some users that don't need to be mapped and some that do, you can add only the users that need to be mapped. For the unchanged users, make sure you also check the Map identities that aren't included in the identity maps box in step 5 (later on this page).

Create the identity map

Tip: Click Download sample CSV to get an example CSV file that you can use.

1. Open a spreadsheet program.
2. In the first column, add the header Source Email and in the second column, add the header Destination Email.
3. Using valid email addresses, add the users’ email addresses for the source account and the destination account (Google Workspace account).

   The CSV file must be smaller than 10 MB and have fewer than 150,000 rows of data.

4. Save the spreadsheet as a CSV file.

Example:

Source Email	Destination Email
[email protected]	[email protected]
[email protected]	[email protected]

Upload the file

1. In your Admin console, click Upload identity map CSV.
2. Go to and select your CSV mapping fileclick Open.
3. Click Tasks to confirm that the mapping file is successfully uploaded.

Step 5: Select the migration settings

1. Click Start date, enter the date that you want chat messages migrated from, and click OK.

   Chat migration migrates messages from the selected date to the date that you start the migration.

2. (Optional) To map all users including those not in the identity map, check the Map identities that aren't included in the identity maps box and then choose an option:
   • If the user's email address on the source account is the same as their address in Google Workspace, select Preserve source domain for identity.
   • If the domain name for all migrated users is changing, select Use target domain for identity, click Domain, and then select the Google Workspace domain name.
3. Click Save.

Next step

Run a migration