Zoom Team Chat Migration App Field Guide

Introduction

The Zoom Team Chat Migration App Field Guide is a comprehensive resource for IT administrators, providing step-by-step instructions for transferring Slack Workspaces to Zoom Team Chat. It covers essential processes for migrating public channels, private channels, and direct messages while maintaining data integrity and user communication history.

The Zoom Team Chat Migration App implements a dual-engine architecture for transferring Slack Workspace data to Zoom Team Chat environments. System administrators have access to several migration pathways.

Migration overview

There are multiple ways to migrate your Slack data using the Zoom Team Chat Migration App, depending on your organization's size, Slack plan, and security requirements.

Additionally, you must meet certain Slack and Zoom prerequisites, make a migration plan, and consolidate your Slack Workspaces. This section provides an overview of these prerequisites and considerations.

Migration options

The following table details the most-common migration approaches:

Migration Method

Description

Best For

Requirements

Benefit

API Migration (App-Based)

Uses a migration app to directly connect to Slack APIs and transfer data. Supports public channels, private channels, and DMs.

Smaller organizations or where obtaining user authorization is feasible

Users must authorize access to their data for private chats and DMs

Fully automated and seamless transfer of data directly from Slack

Import Tool Migration (File-Based)

Uses Slack export files to migrate data via Zoom’s Import Tool

Organizations with Slack Plus or Enterprise Grid plans

Admins must export Slack data from the Slack admin dashboard

No user authorization needed; ideal for bulk migration, especially private chats

Hybrid Approach (API + Import)

Combines API and Import methods: public channels via API; private channels and DMs via Import Tool

Mid-to-large organizations that want to avoid user authorization complexity

Admin access for both Slack export and app-based API migration setup

Avoids user authorization friction for private chats while maintaining automation for public channel migration

System constraints

The migration process is subject to specific constraints:

Maximum single job capacity: 12 months of historical data
Total migration window: 60 months (5 years)
Job concurrency: Only one job must be running at a time

This technical architecture enables systematic migration of enterprise communication data while maintaining security protocols and data integrity.

Slack-to-Zoom data mapping

The following table of mapping details can help you understand the connection between Slack and Zoom Team Chat prior to migration:

Slack Feature

Zoom Team Chat Equivalent

Notes

Public Channels

Migrated automatically

Private Channels

Requires user approval

Direct Messages (DMs)

1:1 Chats

Requires user approval

Group DMs

Group Chats

Requires user approval

Threads

Inline Replies

Not fully threaded like Slack, but keeps reply order

@ Mentions

Same behavior

Reactions

Emoji Reactions

Same behavior

Files

Shared Files

Requires cloud storage enabled

Pinned Messages

Starred Messages

Pinned messages become starred

Slack Bots/App Messages

Text Only (No Cards)

Rich app cards will not migrate

Account and permission prerequisites

You must check both your Slack and Zoom account levels and admin permissions before proceeding.

A Pro, Business, Enterprise, or Education Zoom account is required.
Slack and Zoom admin permissions are needed to authorize migration.

The admin installing the Zoom Marketplace app must access role management on the web portal. They must ensure they are assigned the correct chat management permissions - the Edit checkbox must be selected for Chat Channels and Chat Messages roles. Otherwise, they will not be able to authorize the Zoom Slack Migration app due to insufficient permissions.

Cloud storage must be enabled for message/file retention.

Slack APIs: Scopes, permissions, and rate limits

Slack APIs are used to fetch your Slack user, channel, and message data. These data types have rate limits, allowing only a certain number of requests per minute for a Slack Workspace. This is an important consideration when planning your migration timeline.

Slack Migration Job Performance Benchmarks

The following tables provide estimates for Slack migrations.

Migration Method

Data Range

Processing Time per Channel

Estimated Migration Time*

Import Migration

~2 weeks

5-10 seconds

45 seconds - 1 minute 15 seconds per channel

API-Based Migration

~2 weeks

20-30 seconds

3-5 minutes per channel

_{*Based on midsize Slack workspace with one year of historical data}

Migration jobs encounter two fundamental bottlenecks that directly affect implementation timelines and resource planning. File transfer processing limitations impact both import and API-based migration methods, creating performance constraints that require adequate bandwidth allocation and transfer optimization strategies during deployment planning. API-based migration jobs face additional performance restrictions due to Slack's native API rate limiting mechanisms. These constraints don't affect import migrations but significantly impact API-based implementations, requiring extended processing windows and careful job scheduling to optimize throughput while maintaining compliance with platform limitations.

While your Slack workspace may contain hundreds or thousands of channels, channel activity distribution follows predictable patterns that directly impact migration performance and resource allocation requirements. High-activity channels with extensive message histories, file attachments, and user interactions will require the full benchmark processing times outlined above. However, the majority of workspace channels typically contain minimal activity—consisting of brief conversations, announcements, or archived discussions that migrate significantly faster than benchmark estimates.

Required Admin Permissions and Scopes

The Zoom App Marketplace requires the following admin permissions and scopes within the Zoom tenant:

Team Chat Management > Chat Channels = Edit
Chat Messages = Edit

The Zoom Migration tool uses internal APIs that require the following Zoom App scopes:

chat_message:write:admin
imchat:bot
chat_channel:write:admin
user:write:admin

Zoom XMPP includes a field containing the Slack Message ID for authenticity and historical tracking.

The Zoom-built Slack app will automatically install in the Slack tenant when an admin connects to a Workspace via the migration tool. The Slack app uses OAuth2 authentication to connect with Zoom, providing the authorization token for data migration. Users must authorize migration of private conversations (DMs, group chats, and private channels).

You must also set the option for Only allow apps from the slack directory to OFF, which allows the Slack app to install once the Workspace connection has been created. The following Slack scopes are also required:

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

Migration considerations

Considering a migration strategy ahead of time will save effort and ensure a smooth transition between platforms. As a high-level example, Zoom offers the following strategy outline:

Decide which Slack Workspaces to migrate (one or more)
Choose what data to migrate:
1. Public channels (automatic migration)
2. Private channels and direct messages (DMs) (requires user authorization)
3. Bot and/or app messages
Decide which migration method best fits your needs
Set a timeframe for migration (up to a maximum of one year per job)
Communicate with users about private message approvals

Slack Workspace consolidation

For organizations using multiple Slack Workspaces, such as Enterprise Grid users, migration to Zoom Team Chat consolidates all Workspaces into a single account.

To differentiate between Workspaces, Zoom appends the original Workspace name to both channel and chat names. For example:

Original Slack Channel:
- #engineering (with a Workspace of "US Team")
Migrated Zoom Channel:
- #engineering: US Team

This consolidation ensures all data migrates to a single Zoom Team Chat account while preserving the original Workspace context. Shared spaces can provide additional structure for specific teams or departments, making it easier to organize and access content.

Chat data consolidation

Workspaces with more than 100 users can have tens of thousands of private group chats and DMs that were never archived or deleted, even after users were removed from the company. This causes private migration jobs to take significantly longer than public jobs.

Administrators should clean old data by either manually archiving these old conversations or updating their Slack retention period to automatically delete them.

Zoom recommends validating which data needs to remain as active data in Zoom Team Chat, and which data can be archived for any future legal, compliance, risk mitigation, human resources, or other purposes.

While you can replicate more Slack data into Zoom Team Chat, Zoom recommends only replicating one (1) year of active data and archiving the rest. Most users rarely need to search beyond a single year to perform their role and communicate. Zoom recommends creating migration jobs in smaller three to six-month batches for successful data migrations.

Also, it is important to consider whether data currently resides in Slack or is integrated with third-party services for DLP, e-Discovery, or archiving.

Chat history retention

Several retention-related considerations exist when migrating from Slack to Zoom, since Slack is entirely cloud-based while Zoom offers more granular retention options:

Zoom offers both local device and cloud storage. Local device storage can range from one (1) day to seven (7) years. Cloud storage can be disabled or set up for a 7-year retention period.
Retention policies can be configured at both the account and group levels for users.
Administrators can set specific retention times for individual channels, as needed.
Administrators can specify one retention policy for DMs or group chats and set another policy for chat channels.
For chat history reporting, Zoom recommends storing edited message revisions and deletions.

See the Zoom Support article Storing Zoom Team Chat message history to learn more about chat history retention.

Best practices

Best practices for pre-migration

Follow these recommendations for an easier pre-migration process:

Ensure that users have created accounts on Zoom and have authenticated at least once.
Administrators have added the Slack Migration app to their Zoom account.
Administrators performing the migration must have permissions for both platforms (Slack and Zoom Team Chat), and their email must match between their Zoom and Slack accounts.
Administrators must use the Zoom Team Chat Migration app to configure migration jobs to run and move data from Slack to Zoom Team Chat. Note: This process requires a minimum of 2 jobs because at least 1 job will move private conversations and 1 job will move public channels.
Administrators should archive or delete any unnecessary Slack data they do not want migrated to Team Chat to help speed up migrations.
If you’re using API Migration jobs for migrating private data, ensure users are aware of when and how they will authorize Slack to move their data to Team Chat.
If planning on using Import Migration jobs, follow Slack’s instructions on exporting your workspace chat data as a .zip file.
- File requirements:
  - The name of the .zip file must not be changed from its original Slack exported format
  - The size of the .zip file must not exceed 1 GB

Best practices for migration

The following process provides a high-level overview of the migration:

Before migration, ensure users are created in Zoom and have authenticated at least once.
Administrators should prepare and add the Slack Migration app to their Zoom account.
The administrator performing the migration must have appropriate permissions for both platforms and matching email addresses between their Zoom and Slack accounts.
Administrators must install the private app in Slack to connect to Zoom and perform OAuth authentication.
Administrators use the Zoom Team Chat Migration app to configure migration jobs for moving data from Slack to Zoom Team Chat. This requires a minimum of 2 jobs - one for private conversations and one for public channels.

When migrating, follow these recommended steps:

Migrate data from one channel by selecting the Select Public Channels Conversation Type and choosing a specific channel. Select a week's worth of data from some of your oldest channels.
Create jobs to transfer all public channels from over a year ago, then verify that all channels were created with users.
After verifying the app works as expected, create and run fewer jobs with larger time ranges rather than more jobs with smaller time ranges. Each job contains the same number of steps to migrate.
(Optional) Repeat these steps for private job migrations.

After data migration, your data will appear as follows:

Public/private channel and group chat names will appear as: #channel-name: workspace-name
Messages sent by Slack users with active Zoom accounts will show normally as if they were sent by those zoom users
Messages sent by Slack users without active Zoom accounts will show as sent by a de-activated Zoom user with the name of the Slack message sender
System messages will migrate (e.g., "@Some User has joined the channel")
All messages will be migrated as read, regardless of their status in Slack
A Migration Completion notice will be sent to each public and private channel upon completion, appearing as "Message is sent from Team Chat Migration App, Day Date Time"

Deleting the migration app

The migration app maintains 1:1 mappings between Slack and Zoom conversations after migration.

Removing this app from your Zoom account will delete these mappings, resulting in duplicate channels and chats if you reinstall and migrate again. Only delete the Team Chat Migration app if you are certain no further migrations will be needed.

Installation

To install the app:

Sign in to the Zoom App Marketplace.
Search for Team Chat Migration and click Add.
Review and approve the necessary permissions.

See the Zoom Support article Using the Team Chat Migration app (Slack Migration tool) for more detailed installation instructions.

Administrators must grant permission to the Slack workspace account or organization to install and authorize the private application, Message Retriever. An admin must approve the use of apps, generally, in a Slack workspace and also grant permissions for all members to use the app.

Administrators must grant permission to install the Team Chat Migration app in their Zoom account along with two Team Chat Management permissions in the admin role.

The option for Only allow apps from the Slack App Directory setting must be disabled.

The administrator using the app must have an account Admin role to migrate conversations. They cannot be a custom admin type. Learn more about identifying account types, roles, and licenses and role management on the Zoom Support site.

Connect your Slack Workspace for API Migration Jobs

If you aren’t using the File Import method, these instructions will help you connect for API migrations.

To connect a Workspace:

Open the Team Chat Migration App in Zoom.
Click Create Connection > Sign in to Slack and authorize.
Confirm the workspace connection in the Zoom dashboard.

Perform 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 on the Zoom side, a new, deactivated user will be created within Zoom for that email address.

If an active Slack user's email address is found under a different Zoom account, such as a personal account, then the user will be mapped to a "dummy user" profile. 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.

Do not delete the TeamChatMigration AppUser user.

Performing migration jobs

The following section will help you start the jobs necessary for migration.

Creating an import migration job

To create a new migration job:

Click Upload Files, select your Slack Export file, then click Upload.
Wait for your file to upload to Zoom.
1. Note: Please do not exit or refresh the page, as this will stall the file upload and the job will be stuck in "Uploading" state. If this happens, you can delete the "Uploading" job and restart this process
Once the initial file upload completes, a Migration details window will pop up while the Migration app prepares the file for migration. At this point, you can close, exit, or refresh the page while you wait until the job is ready to run.
After the tool is finished preparing the file for migration, you will be able to select the conversation types to migrate.
Once you have selected your conversation types, click Run to start the migration job.

Creating an API Migration job

To create a new migration job:

Click New Migration Job and select the Slack workspace.
Choose the data scope:
- Public channels (migrates automatically).
- Private channels & DMs (requires user authorization).
- Specific date range for messages.
Once you have selected your data scope and range and you have obtained the authorization from your users, select Run to start the migration job.

Handling private data authorization requests for private channels and DMs:

Private channels and DMs require user approval before migrating.
Zoom will automatically send email requests for approval once the migration job is created.
Admins can track which users have/haven't approved. For private chat migration, only one user's authorization is required to migrate the entire conversation history.
Authorization request emails are only sent to users who haven't yet provided approval.
For optimal migration success, target obtaining authorization from approximately 60-70% of your users.

Running and monitoring migration jobs

Starting a new migration job

To start a migration job run:

Click Run Migration to begin the process.
Migration times vary (large workspaces may take 12+ hours).
Track progress in the Migration Dashboard.

Troubleshooting migration jobs

Occasionally, a migration job might not return the desired result. The following table provides solutions for possible issues experienced during migration:

Issue

Solution

Private messages/channels missing

Check if the user authorized the migration

Migration job stuck

The migration app will automatically retry

Some users not mapped in Zoom

Ensure they exist in Zoom with the same email and re-run any migrations

Migration postmortem

After completing a migration, Zoom recommends performing a thorough postmortem and verifying your Slack content made it over to Team Chat as expected.

The following table provides recommended tasks to validate your chat migrations:

Step

Action

Verify the Migration

Sign in to Zoom Team Chat and verify that channels, messages, and files appear correctly.
Sign out and sign back in to refresh the chat history.

Fix Any Missing Data

Resend authorization requests to users who have not approved private data access.
Review migration jobs for errors and retry any failed jobs.

(Optional) Decommission Slack

After confirming data migration is complete, you may archive or remove the Slack workspace.

General Troubleshooting

If messages are missing, try signing out and signing back into Zoom.
If users cannot be found, verify that email addresses match between Slack and Zoom.
If migration fails, check logs for error details and retry the process.

Additional troubleshooting checklist

If you discover additional issues post-migration, this checklist can provide additional steps and actions to perform for verification.

Before continuing, you must obtain the Zoom tracking ID from the web call and retrieve both Account IDs and User IDs.