Getting started with the Zoom Team Chat Migration app
The Team Chat Migration app (Slack migration tool) is a self-service tool in the Zoom App Marketplace that provides end-to-end (E2E) migration of Slack chat history and data for users migrating from Slack to Zoom Team Chat. This tool can help users migrate Slack data and consolidate multiple Slack Workspaces into one Zoom account.
This app is designed to migrate:
- Public and private channel messaging along with channel ownership and membership
- Direct messages and group chat messaging
- Chat history messages, reactions, links, files, emojis, and more associated with all of the above conversations up to 1 year at a time.
Note: For more than 1 year of data, the customer must run multiple migration jobs.
Zoom uses a dashboard that allows admins to create migration jobs to replicate Slack data in real-time for public channels and private conversations (direct messages, group chat, and private channels). The Zoom app does not delete any of your data in Slack.
Learn more about using the Team Chat Migration app, Zoom Team Chat Migration app mapping, and troubleshooting the Team Chat Migration app.
How to understand Zoom Team Chat Migration app admin deployment
Zoom offers its own automated, migration service, Team Chat Migration application, to create jobs that migrate data in real-time when admins trigger the migration to run. This solution reduces the risk of data loss while maintaining Zoom’s enterprise-grade security. This dashboard connects to Slack using admins’ preferred OAuth 2.0 standard and real-time APIs.
The Zoom migration self-service app lets you configure migration jobs with variable date ranges to migrate: public channels, direct messages, group chats, private channels, channel manager and member permissions, files, reactions, and more. All threaded messages are preserved with the sender’s name and original time and date stamp.
The admin installing the Zoom Marketplace app must access role management on the web portal. They must ensure that they are assigned the correct chat management permissions—the Edit checkbox is selected for Chat Channels and Chat Messages roles. Otherwise, they will not be able to authorize the Zoom Slack Migration app because they do not have the required permissions.
Understand the Slack Migration app admin requirements and guidelines
Admin permissions
Admins must grant permission to the Slack workspace account or organization to install and authorize the private application, Message Retriever. They must approve the use of apps in a Slack workspace and grant permissions for all members to use the app.
Admins must grant permission to install the Team Chat Migration app in your Zoom account along with two Team Chat Management permissions in the admin role.
The Only allow apps from the Slack App Directory setting must be disabled.
Note: The admin who is using the app must have an account Admin role in order to migrate conversations. They cannot be a custom admin type. Learn more about identifying account types, roles, and licenses, and role management.
User authorization
To migrate private conversations, Slack requires authorization from users for an app to read their messages. Only 1 person in a group chat or private channel needs to authorize the app for the conversation to migrate.
Upon the creation of a private job, admins can generate an email authorization (generated from noreply@zoom.us) from the dashboard to users. Users must be authenticated to Zoom using the same email as their Slack email when they approve the app. If you are running more than 1 migration job for larger amounts of data, this only needs to be completed one time per user per workspace.
How to understand the Zoom Team Chat Migration app
The Team Chat Migration app is designed to:
- Replicate Slack data from 1 Workspace at a time into Zoom Team Chat.
Note: Additionally, Zoom can migrate data from multiple workspaces into 1 Zoom Team Chat account. - Migrate up to 1 year of data at a time in each automated migration job performed.
- Perform replication jobs sequentially if creating more than 1 job at a time.
- Follow Slack’s process to have users authorize an app to read their private conversations (direct messages, group chat, and private channels) for them to migrate. Users only need to authorize the app once per workspace if running multiple migration jobs.
- Migrate all public channels when you run a job.
- Migrate all authorized private conversations when you run a job.
Learn more about using the Team Chat Migration app (Slack Migration tool).
How to understand the supported message data for migration
The supported message types for migration are:
- Text
- Threaded replies
- Files
- Links
- Reactions
- Images
- Audio messages
- Video messages
- Channel manager/owner
- Guest/external user labels
- Original sender time and date stamp
- Deactivated user labels
- Pinned messages
- Mentions
Notes:
- Admins are limited to migrating a maximum of 1 year of chat history in each migration job. Additional migration jobs can be run to migrate more than 1 year of historical chat messaging and files.
- Admins can migrate data up to 5 years of chat history.
Learn more about Zoom Team Chat Migration app features.
How to understand User Sync and Public Channel Sync tasks
Once a workspace connection is created, background tasks to “sync” users and channels are triggered. No further action is needed from you.
Understand the User Sync task
The User Sync task fetches all full, active members in your Slack workspace and creates a 1:1 mapping to their corresponding Zoom account using their email address.
If an active Slack user’s email address is not found in Zoom, a new deactivated user will be created in Zoom for that email address.
If an active Slack user’s email address is found under a different Zoom account (i.e., a personal account), then the user will be mapped to a “dummy user”. In your Zoom account, this user will be named TeamChatMigration AppUser and will be present to ensure all message data is migrated for your workspace.
Note: Do not delete this user.
Understand the Public Channel Sync task
The Public Channel Sync task fetches all public Slack channels but does not migrate them to Zoom. This will enable you to select specific public channels to migrate.
All public channels will be set with the following permissions:
- Channel Type = Public
- New members will see previous message and files = Enabled
- External users can be added = Disabled
- Who can send messages = Everyone
- Who can use @all = Everyone
How to understand scopes, permissions, and Slack API rate limits
Slack APIs are used to fetch your Slack user, channel, and message data. Slack user, channel, and message data all have rate limits, meaning that they only allow a certain number of requests per minute for a workspace. This is an important point to keep in mind when you plan for the time commitment of your migrations.
Note: Ensure that you add approx numbers for migration time.
The Zoom App Marketplace needs the following permissions to be installed by the admin and scopes within their Zoom tenant: Team Chat Management> Chat Channels = Edit; Chat Messages = Edit.
- Zoom is mostly using internal APIs for our application. The only Open API being used is the request to list users within an account. This comes with a medium rate limit rating by Zoom and may have some risk with larger accounts.
- Zoom App scopes: chat_message:write:admin, imchat:bot, chat_channel:write:admin, user:write:admin
- Zoom XMPP will have a new field to contain the Slack Message ID for authenticity and historical purposes.
The Zoom-built Slack app must be installed by the Slack admin as a private app in their Slack tenant and will request the following permissions:
- The app built for Slack is using the Slack process for OAuth2 to connect to Zoom. This is used by Zoom to gain the authorization token to connect and migrate the data from Slack. Users that will migrate private conversations (dm, group chat, and private channels) must provide authorization.
- Scopes that Zoom will access: files:read,channels:history,channels:read,groups:history,groups:read,im:history,im:read,mpim:history,mpim:read,pins:read,stars:read,users:read,users:read.email
How to understand deleting the Team Chat Migration app
Once data is migrated, this app contains the 1:1 mappings between Slack conversations and Zoom conversations. Deleting this app from your Zoom account will also remove these mappings and will lead to duplicate channel and chat creations if you re-install and migrate again. You should only delete the Team Chat Migration app if you are sure you will not migrate again.
How to plan for the Zoom Team Chat Migration app
Strategize data migration
Workspaces with more than 100 users likely have tens of thousands of old private group chats and direct messages (DMs) that were never archived or deleted, even after one or more of their users were removed from the company. This causes private migration jobs to take significantly longer than public jobs. Admins are advised to try and clean their old data by either manually archiving these old conversations or updating their Slack retention period to delete them automatically.
First, evaluate what data needs to live as active data in Zoom Team Chat and what data can be exported for archiving, should it be needed for legal, compliance, risk mitigations, human resources, and more.
While you can replicate more Slack data into Team Chat, Zoom recommends you replicate 1 year of active data and the rest be archived. Most users rarely need to search beyond 1 year to perform in their role and communicate. Zoom recommends creating migration jobs in smaller batches of 3-6 months due to best practices for successful data migrations.
It is important to consider where data lives now, in Slack or integrated with third-party services for DLP, e-Discovery, and archiving.
Consider chat history retention with Zoom
There are a few retention-related considerations with migration from Slack to Zoom since all of Slack is on the cloud and Zoom offers more granular retention options.
- Zoom offers both local device and cloud storage. Local device storage can be set to a minimum of 1 day or as high as 7 years. Cloud storage can be disabled or set to a maximum of 7 years.
- Retention policies can be set at the account and group level for users.
- Admins can set a specific time for individual channels where applicable.
- Admins can specify different retention policies for direct messages/group chats versus channels.
- For Chat History reporting, Zoom recommends you store edited message revisions and deletions.
Learn more about message retention history.
Best practices for the Zoom Team Chat Migration app
Best practices for pre-migration
Follow these notes and recommendations for an easier pre-migration process:
- Ensure that your users have created accounts on Zoom and ideally have authenticated at least once.
- Admins have added the Slack Migration app to their Zoom account.
- Admins, who are performing the migration, must have the permissions for both platforms (Slack and Zoom Team Chat), and their email must match their Zoom account and Slack account.
- Admins must install the private app in Slack to connect to Zoom and perform the authentication using OAuth.
- Admins must use the Zoom Team Chat Migration app to configure migration job(s) to run and move the data from Slack to Zoom Team Chat.
Note: This process will be a minimum of 2 jobs because at least 1 job will move private conversations, and at least 1 job will move public channels. - Admins have archived or deleted any unnecessary Slack data that they do not want to be migrated from Slack to Team Chat. This will help speed up the migrations.
- Ensure that your users are aware of when and how they will authorize Slack to move their data from Slack to Team Chat.
Best practices for migration
The following process is a high-level overview of the migration process:
- Before migration, users are built on Zoom and ideally have authenticated at least once.
- Admins have prepared and added the Slack Migration app to their Zoom account.
- The admin performing the migration must have the right permissions for both platforms and their email must match between their Zoom account and Slack account.
- Admins install the private app in Slack to connect to Zoom and perform the authentication using OAuth.
- Admins use the Zoom Team Chat Migration app to configure migration job(s) to run and move the data from Slack to Zoom Team Chat. This process will be a minimum of 2 jobs since at least 1 will move private conversations and at least 1 will move public channels.
When migrating, it is recommended that you follow the below steps:
- Migrate data from one channel by selecting the Select Public Channels Conversation Type and choosing a specific channel. We recommend that you select a week's worth of data from some of your oldest channels.
- Create jobs to transfer all the public channels from over a year ago, then verify that all channels were created with users.
- After verifying that the app works as expected, create/run fewer jobs with larger time ranges than more jobs with smaller time ranges.
Each job contains the same amount of steps to migrate. - (Optional) Repeat and follow these steps for private job migrations.
After data migration, your data will appear as the following:
- Public channel name format will appear as: #channel-name: workspace-name
- Every message is sent from will appear as: TeamChatMigration App User Month Date, (Year), 12-Hour Time
- The message text will contain the original sender name. For example, it will appear as “Message sent by Michael Hamilton.”
- System messages will migrate. For example, they will appear as “@Some User has joined the channel.”
- All messages are migrated as read. If there were unread messages in Slack, they appear as read in Zoom.
- A Migration Completion notice is sent to each channel as it completes. For example, it will appear as “Message is sent from Team Chat Migration App, Day Date Time.”
Additional resources
Learn more about the Zoom Team Chat Migration app by viewing the following articles:
Due to changes in Slack’s API rate-limiting policies, API-based migration jobs are restricted to migrating only 15 messages per minute. This will significantly slow down the migration process when using an online workspace connection.
To avoid these delays, we recommend using our Import Tool, which lets you upload an exported Slack chat history file and does not rely on Slack APIs. If you must use the API method, consider contacting Slack support to request a rate limit exception for our migration app. Learn more about
Slack’s API rate limits.
