Import from Microsoft Teams

import {Steps, TabItem, Tabs} from "@astrojs/starlight/components";

import FlattenedSteps from "../../components/FlattenedSteps.astro"; import ZulipNote from "../../components/ZulipNote.astro"; import ImportHowUsersWillLogIn from "../include/_ImportHowUsersWillLogIn.mdx"; import ImportIntoASelfHostedServerDescription from "../include/_ImportIntoASelfHostedServerDescription.mdx"; import ImportIntoASelfHostedServerInstructions from "../include/_ImportIntoASelfHostedServerInstructions.mdx"; import ImportIntoAZulipCloudOrganization from "../include/_ImportIntoAZulipCloudOrganization.mdx"; import ImportSelfHostedServerTips from "../include/_ImportSelfHostedServerTips.mdx"; import ImportYourDataIntoZulip from "../include/_ImportYourDataIntoZulip.mdx"; import ImportZulipCloudOrganizationWarning from "../include/_ImportZulipCloudOrganizationWarning.mdx"; import ViewImportedUsers from "../include/_ViewImportedUsers.mdx";

You can import your current workspace into a Zulip organization. It's a great way to preserve your workspace history when you migrate to Zulip, and to make the transition easy for the members of your organization.

The import will include your organization's:

• Name
• Users, including names, emails, roles
• Teams as Zulip channels, including all user subscriptions
• Message history, excluding direct messages and messages in private channels

Import process overview

To import your Microsoft Teams data into Zulip, you will need to take the following steps, which are described in more detail below:

When planning to migrate from Microsoft Teams to Zulip, make sure your Microsoft tenant is active and still has access to Microsoft services for at least a couple of months. The process to gain access to the Teams data export tool can take around a month, and Zulip's import tool for Microsoft Teams requires an active Microsoft Entra ID application. Additionally, since the imported users' email addresses will be their Microsoft tenant emails, they will still need access to those accounts to update their Zulip email addresses.

Import your organization from Microsoft Teams into Zulip

Export your Microsoft Teams data

The Teams data export tool supports the export of data for tenants of up to 500 users. If your organization has more than 500 users, you can try the Teams export APIs.

Export message history using the Teams data export tool

Authorize a Microsoft Graph API token

Some organization data is not exported by the Teams data export tool. The Zulip import tool will call several Microsoft Graph APIs to collect the following data:

• Hosted contents. Teams content hosted in a chat message, such as images or code snippets.

• User roles. The user roles section explains how Microsoft Teams users roles and user types are mapped to Zulip user roles.

To access those APIs, create a Microsoft Entra ID application with the required permissions, and authorize an access token:

 * `ChannelMessage.Read.All`
 * `User.Read.All`
 * `RoleManagement.Read.Directory`

 See the [required token permissions](#required-token-permissions) section for more
 details about these tokens and the endpoints that the import tool calls.

1. Click the Grant admin consent for your organization button in the API permissions menu to grant admin consent to all scopes.
2. Take note of the application's redirect_uri, tenant_id, client_id, and client_secret.
3. To gain administrator permission, make the following HTTP request using the details from your Microsoft Entra ID application:
   bashCopy

   https://login.microsoftonline.com/<tenant_id>/adminconsent?
   client_id=<client_id>
   &redirect_uri=<redirect_uri>
   

4. You will be redirected to the Microsoft sign in page. Log in using a global administrator account and approve all the application permissions that you have requested. If successful, you will be redirected to your application's redirect_uri with the following parameters:
   bashCopy

   GET <redirect_uri>?tenant=<tenant_id>&admin_consent=True
   

5. To get the access token, make the following request:
   bashCopy

   curl --location --request POST 'https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'client_id=<client_id>' \
     --data-urlencode 'scope=https://graph.microsoft.com/.default' \
     --data-urlencode 'client_secret=<client_secret>' \
     --data-urlencode 'grant_type=client_credentials'
   

   A successful response looks like this:
   bashCopy

     {
       "token_type": "Bearer",
       "expires_in": 3599,
       "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
     }
   

6. Take note of the access_token. </Steps>

Required token permissions

The following Microsoft Graph API endpoints are used by the Zulip import tool:

Import your data into Zulip

<ImportZulipCloudOrganizationWarning />

<FlattenedSteps>
  <ImportIntoASelfHostedServerInstructions />

  1. To import into an organization hosted on the root domain
     (`EXTERNAL_HOST`) of the Zulip installation, run the following
     commands, replacing `<token>` with your Microsoft Graph API access token.
     <ImportSelfHostedServerTips />
     ```bash "<token>"
     cd /home/zulip/deployments/current
     ./scripts/stop-server
     ./manage.py convert_microsoft_teams_data /tmp/TeamsData/ --token <token> --output /tmp/converted_microsoft_teams_data
     ./manage.py import '' /tmp/converted_microsoft_teams_data
     ./scripts/start-server
     ```
     Alternatively, to import into a custom subdomain, run:
     ```bash "<token>" "<subdomain>"
     cd /home/zulip/deployments/current
     ./scripts/stop-server
     ./manage.py convert_microsoft_teams_data /tmp/TeamsData/ --token <token> --output /tmp/converted_microsoft_teams_data
     ./manage.py import <subdomain> /tmp/converted_microsoft_teams_data
     ./scripts/start-server
     ```
  1. Follow [step 4](https://zulip.readthedocs.io/en/stable/production/install.html#step-4-configure-and-use)
     of the guide for [installing a new Zulip
     server](https://zulip.readthedocs.io/en/stable/production/install.html).
</FlattenedSteps>

Import details

Because the import tool is currently in beta, the following data is not imported into Zulip. If importing any of this data is important for your organization, contact [email protected] to see if the import tool can be extended to include it.

• Direct messages and messages in private channels
• Meeting chats and recordings
• Message attachments stored in Microsoft SharePoint are not imported.
• Message reactions
• Message edit history, and system messages such as @user_a added @user_b to the chat
• Custom emoji
• User avatars

A couple of additional caveats to keep in mind:

• Mentions in messages are not converted to Zulip mentions.
• Message thread replies will be combined to the main topic.

User roles

Microsoft tenant's user roles are mapped to Zulip's user roles in the following way:

Settings

The Teams export tool does not export organization settings, or full user settings. Configure organization settings as described below, and encourage users to customize their account settings.

Clean up after the Microsoft Teams export

Once your organization has been successfully imported in to Zulip, you should delete the Microsoft Entra ID application that you created in order to export your Microsoft Teams data.

Get your organization started with Zulip

Once the import process is completed, you will need to:

Decide how users will log in

Send password reset emails to all users

Manual password resets

Related articles

• Choosing between Zulip Cloud and self-hosting
• Moving from Microsoft Teams
• Getting started with Zulip
• Change your email address