From 707f98b5ab058d0f5d16408f762ccfb4edde1431 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 1 Aug 2025 16:34:30 +0530 Subject: [PATCH 01/72] Created a new draft for migrating external message to Teams --- .../new-draft-external-messages-to-teams.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md new file mode 100644 index 00000000000..736c8786330 --- /dev/null +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -0,0 +1,10 @@ + +## Import third-party platform messages to Teams using Microsoft Graph + +With Microsoft Graph, you can migrate users' existing message history and data from an external system into a Teams channel. By enabling the recreation of a third-party platform messaging hierarchy inside Teams, users can continue their communications in a seamless manner and proceed without interruption. + +> [!NOTE] +> In the future, Microsoft may require you or your customers to pay additional fees based on the amount of data imported. + +## API Migration Workflow +Use the step-by-step migration flow to ensure a seamless transition of historical messages in both existing and newly created channels or chats by enabling migration mode. \ No newline at end of file From 46ee76d742c0c36a040074a5f03959830cd97170 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 1 Aug 2025 19:19:59 +0530 Subject: [PATCH 02/72] updated Note and changed errors for language accuracy --- .../new-draft-external-messages-to-teams.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 736c8786330..4147d57d8c8 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -1,10 +1,18 @@ -## Import third-party platform messages to Teams using Microsoft Graph +# Import third-party platform messages to Teams using Microsoft Graph -With Microsoft Graph, you can migrate users' existing message history and data from an external system into a Teams channel. By enabling the recreation of a third-party platform messaging hierarchy inside Teams, users can continue their communications in a seamless manner and proceed without interruption. +With Microsoft Graph, you can migrate users' existing message history and data from an external system into a Teams channel. Users can continue their communications in a seamless manner and proceed without interruption through the recreation of a third-party platform messaging hierarchy inside Teams. > [!NOTE] -> In the future, Microsoft may require you or your customers to pay additional fees based on the amount of data imported. +> In the future, Microsoft may require you or your customers to pay extra fees based on the amount of data imported. ## API Migration Workflow -Use the step-by-step migration flow to ensure a seamless transition of historical messages in both existing and newly created channels or chats by enabling migration mode. \ No newline at end of file +Use the step-by-step migration flow to ensure a seamless transition of historical messages in both existing and newly created channels or chats by enabling migration mode. + +## Step-by-Step Migration Flow +### Step 1: Create or select a channel/chat +You can either create a new channel or chat in a Team or use an existing channel or chat. + +> [!NOTE] +> All APIs listed in the following sections require the `Teamswork.Migrate.All` permission in the application context. Delegated authentication isn't supported. + From 534e1403995763279eedfa81413851fb626efacf Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 1 Aug 2025 19:59:14 +0530 Subject: [PATCH 03/72] Added Note and Step 2 --- .../new-draft-external-messages-to-teams.md | 30 +++++++++++++++++-- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 4147d57d8c8..4f2adaf5b41 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -1,7 +1,7 @@ -# Import third-party platform messages to Teams using Microsoft Graph +# Use Microsoft Graph to Import Messages from External Platforms to Teams -With Microsoft Graph, you can migrate users' existing message history and data from an external system into a Teams channel. Users can continue their communications in a seamless manner and proceed without interruption through the recreation of a third-party platform messaging hierarchy inside Teams. +You can use Microsoft Graph to migrate users' existing message history and data from an external system into a Teams channel. This enables users to continue conversations without interruption by recreating the messaging hierarchy from a third-party platform directly within Teams. > [!NOTE] > In the future, Microsoft may require you or your customers to pay extra fees based on the amount of data imported. @@ -11,8 +11,32 @@ Use the step-by-step migration flow to ensure a seamless transition of historica ## Step-by-Step Migration Flow ### Step 1: Create or select a channel/chat -You can either create a new channel or chat in a Team or use an existing channel or chat. +You can either create a new channel or chat in a Team or use an existing channel or chat. hyperlink > [!NOTE] > All APIs listed in the following sections require the `Teamswork.Migrate.All` permission in the application context. Delegated authentication isn't supported. +### Step 2: Use startMigration API to start channel migration +* The startMigration API enables migration mode on existing Teams channels, allowing import of historical messages. Previously, import operations were restricted to newly created standard channels in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](#https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/import-messages/import-external-messages-to-teams). + +* You can define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel’s current createdDateTime and will replace it during migration. + +* Supported Channels: Existing Shared, Private and Public + +#### HTTP Request + +```http +POST /teams/{team-id}/channels/{channel-id}/startMigration +{ + INSERT ACTUAL CODE +} +``` +> [!NOTE] +> * You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. +> * If no request body is provided, the API uses the current date and time as the minimum timestamp. +You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. +> * If no request body is provided, the API uses the current date and time as the minimum timestamp. +> - `ConversationCreationDateTime` must be: +> - Greater than the minimum value for `DateTimeOffset`. +> - Less than the current value of the channel's `CreatedDateTime`. + From 71180f276f39094b91044b4ce312badf2ecb47e6 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 1 Aug 2025 20:12:04 +0530 Subject: [PATCH 04/72] made corrections with Acrolinx --- .../new-draft-external-messages-to-teams.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 4f2adaf5b41..b5c99609573 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -1,29 +1,27 @@ # Use Microsoft Graph to Import Messages from External Platforms to Teams -You can use Microsoft Graph to migrate users' existing message history and data from an external system into a Teams channel. This enables users to continue conversations without interruption by recreating the messaging hierarchy from a third-party platform directly within Teams. +You can use Microsoft Graph to migrate users' existing message history and data from an external system into a Teams channel. This feature enables users to continue conversations without interruption by recreating the messaging hierarchy from a third-party platform directly within Teams. > [!NOTE] -> In the future, Microsoft may require you or your customers to pay extra fees based on the amount of data imported. +> In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. ## API Migration Workflow Use the step-by-step migration flow to ensure a seamless transition of historical messages in both existing and newly created channels or chats by enabling migration mode. ## Step-by-Step Migration Flow ### Step 1: Create or select a channel/chat -You can either create a new channel or chat in a Team or use an existing channel or chat. hyperlink +You can either create a new channel or chat in a Team or use an existing channel or chat. Hyperlink > [!NOTE] > All APIs listed in the following sections require the `Teamswork.Migrate.All` permission in the application context. Delegated authentication isn't supported. ### Step 2: Use startMigration API to start channel migration -* The startMigration API enables migration mode on existing Teams channels, allowing import of historical messages. Previously, import operations were restricted to newly created standard channels in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](#https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/import-messages/import-external-messages-to-teams). +The startMigration API enables migration mode on existing Teams channels, allowing import of historical messages. Previously, import operations were restricted to newly created standard channels in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](#https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/import-messages/import-external-messages-to-teams). -* You can define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel’s current createdDateTime and will replace it during migration. +* You can define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel’s current createdDateTime and replaces it during migration. The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. -* Supported Channels: Existing Shared, Private and Public - -#### HTTP Request +#### Request ```http POST /teams/{team-id}/channels/{channel-id}/startMigration @@ -32,7 +30,6 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` > [!NOTE] -> * You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. > * If no request body is provided, the API uses the current date and time as the minimum timestamp. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. > * If no request body is provided, the API uses the current date and time as the minimum timestamp. From 0c9be997eeaeae131ea5a140d211cf97dd891b5d Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 1 Aug 2025 20:23:45 +0530 Subject: [PATCH 05/72] Added Title --- .../new-draft-external-messages-to-teams.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index b5c99609573..3f81d809dcb 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -1,6 +1,15 @@ -# Use Microsoft Graph to Import Messages from External Platforms to Teams +--- +title: Import External Platform Messages Using Microsoft Graph +description: Learn how to use Microsoft Graph APIs to import historical messages and data from an third-party platform to Teams. +ms.localizationpriority: high +author: "akjo" +ms.topic: overview +ms.owner: +ms.date: 01/08/2025 +--- +# Use Microsoft Graph to Import Messages from External Platforms to Teams You can use Microsoft Graph to migrate users' existing message history and data from an external system into a Teams channel. This feature enables users to continue conversations without interruption by recreating the messaging hierarchy from a third-party platform directly within Teams. > [!NOTE] @@ -26,7 +35,7 @@ The startMigration API enables migration mode on existing Teams channels, allowi ```http POST /teams/{team-id}/channels/{channel-id}/startMigration { - INSERT ACTUAL CODE + ACTUAL CODE } ``` > [!NOTE] From e8daf736688afde0edd901994acc3701a4d8d450 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 1 Aug 2025 20:38:06 +0530 Subject: [PATCH 06/72] Made corrections to Title and content --- .../new-draft-external-messages-to-teams.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 3f81d809dcb..89880fe3e49 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -1,16 +1,15 @@ - --- -title: Import External Platform Messages Using Microsoft Graph -description: Learn how to use Microsoft Graph APIs to import historical messages and data from an third-party platform to Teams. +title: Import External Platform Messages Using Microsoft Graphs +description: Learn how to use Microsoft Graph to import historical messages and data from all third-party platforms to Teams. ms.localizationpriority: high -author: "akjo" +author: "nehahedau" ms.topic: overview -ms.owner: +ms.owner: TBD ms.date: 01/08/2025 --- # Use Microsoft Graph to Import Messages from External Platforms to Teams -You can use Microsoft Graph to migrate users' existing message history and data from an external system into a Teams channel. This feature enables users to continue conversations without interruption by recreating the messaging hierarchy from a third-party platform directly within Teams. +You can use Microsoft Graph to migrate users' existing message history and data from an external system into a Teams channel. This feature enables users to continue conversations without interruption, by recreating the messaging hierarchy from a third-party platform directly within Teams. > [!NOTE] > In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. @@ -20,13 +19,13 @@ Use the step-by-step migration flow to ensure a seamless transition of historica ## Step-by-Step Migration Flow ### Step 1: Create or select a channel/chat -You can either create a new channel or chat in a Team or use an existing channel or chat. Hyperlink +You can either create a new channel or chat in a Team or use an existing channel or chat. [Insert Hyperlink or cross-reference to existing steps]() > [!NOTE] > All APIs listed in the following sections require the `Teamswork.Migrate.All` permission in the application context. Delegated authentication isn't supported. ### Step 2: Use startMigration API to start channel migration -The startMigration API enables migration mode on existing Teams channels, allowing import of historical messages. Previously, import operations were restricted to newly created standard channels in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](#https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/import-messages/import-external-messages-to-teams). +* You can use the startMigration API, which enables migration mode on existing Teams channels, allowing import of historical messages. Previously, import operations were restricted to newly created standard channels in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](#https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/import-messages/import-external-messages-to-teams). * You can define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel’s current createdDateTime and replaces it during migration. The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. From 5cd4c6e32927fd8458de7428a3227e181df6b910 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 4 Aug 2025 22:11:30 +0530 Subject: [PATCH 07/72] Fixed errors and resolved issues --- .../new-draft-external-messages-to-teams.md | 23 +++++++++++-------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 89880fe3e49..a511db736bc 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -9,23 +9,28 @@ ms.date: 01/08/2025 --- # Use Microsoft Graph to Import Messages from External Platforms to Teams + You can use Microsoft Graph to migrate users' existing message history and data from an external system into a Teams channel. This feature enables users to continue conversations without interruption, by recreating the messaging hierarchy from a third-party platform directly within Teams. > [!NOTE] > In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. ## API Migration Workflow + Use the step-by-step migration flow to ensure a seamless transition of historical messages in both existing and newly created channels or chats by enabling migration mode. ## Step-by-Step Migration Flow + ### Step 1: Create or select a channel/chat -You can either create a new channel or chat in a Team or use an existing channel or chat. [Insert Hyperlink or cross-reference to existing steps]() + +You can either create a new channel or chat in a Team or use an existing channel or chat. > [!NOTE] > All APIs listed in the following sections require the `Teamswork.Migrate.All` permission in the application context. Delegated authentication isn't supported. -### Step 2: Use startMigration API to start channel migration -* You can use the startMigration API, which enables migration mode on existing Teams channels, allowing import of historical messages. Previously, import operations were restricted to newly created standard channels in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](#https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/import-messages/import-external-messages-to-teams). +### Step 2: Use startMigration API to start channel migration + +* You can use the startMigration API, which enables migration mode on existing Teams channels, allowing import of historical messages. Previously, import operations were restricted to newly created standard channels in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) * You can define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel’s current createdDateTime and replaces it during migration. The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. @@ -37,11 +42,11 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration ACTUAL CODE } ``` + > [!NOTE] +> +> * You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. > * If no request body is provided, the API uses the current date and time as the minimum timestamp. -You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. -> * If no request body is provided, the API uses the current date and time as the minimum timestamp. -> - `ConversationCreationDateTime` must be: -> - Greater than the minimum value for `DateTimeOffset`. -> - Less than the current value of the channel's `CreatedDateTime`. - +> * `ConversationCreationDateTime` must be: +> * Greater than the minimum value for `DateTimeOffset`. +> * Less than the current value of the channel's `CreatedDateTime`. From 9ff77d1d699ccec08bcbdc77c936fa789fbfb562 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 4 Aug 2025 22:30:41 +0530 Subject: [PATCH 08/72] changed author --- .../import-messages/new-draft-external-messages-to-teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index a511db736bc..1d0ff11695a 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -2,7 +2,7 @@ title: Import External Platform Messages Using Microsoft Graphs description: Learn how to use Microsoft Graph to import historical messages and data from all third-party platforms to Teams. ms.localizationpriority: high -author: "nehahedau" +author: "surbhigupta" ms.topic: overview ms.owner: TBD ms.date: 01/08/2025 From 7764410251fb0b604728266e5113ccf715c0215d Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Wed, 6 Aug 2025 23:14:06 +0530 Subject: [PATCH 09/72] Update new-draft-external-messages-to-teams.md --- .../new-draft-external-messages-to-teams.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 1d0ff11695a..8cfbbb66a4d 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -23,12 +23,16 @@ Use the step-by-step migration flow to ensure a seamless transition of historica ### Step 1: Create or select a channel/chat +Namespace: microsoft.graph + You can either create a new channel or chat in a Team or use an existing channel or chat. > [!NOTE] > All APIs listed in the following sections require the `Teamswork.Migrate.All` permission in the application context. Delegated authentication isn't supported. -### Step 2: Use startMigration API to start channel migration +### Step 2: Use startMigration API to start channel and chat migration + +#### Channel Migration * You can use the startMigration API, which enables migration mode on existing Teams channels, allowing import of historical messages. Previously, import operations were restricted to newly created standard channels in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) @@ -40,13 +44,15 @@ You can either create a new channel or chat in a Team or use an existing channel POST /teams/{team-id}/channels/{channel-id}/startMigration { ACTUAL CODE +"conversationCreationDateTime": "2024-01-01T00:00:00Z" } ``` > [!NOTE] > -> * You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. > * If no request body is provided, the API uses the current date and time as the minimum timestamp. -> * `ConversationCreationDateTime` must be: +> * `conversationCreationDateTime` must be: > * Greater than the minimum value for `DateTimeOffset`. > * Less than the current value of the channel's `CreatedDateTime`. + +#### Chat Migration From d951009c96af27a1300e91fe1a5a6120a22bf9cb Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 7 Aug 2025 08:59:13 +0530 Subject: [PATCH 10/72] Updated the content for chat migration Reorganized content to include the startMigration Api for both channels and chats as step1 --- .../new-draft-external-messages-to-teams.md | 33 +++++++++++++++---- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 8cfbbb66a4d..388c026de24 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -32,15 +32,17 @@ You can either create a new channel or chat in a Team or use an existing channel ### Step 2: Use startMigration API to start channel and chat migration -#### Channel Migration +* Use the startMigration API, to enable migration mode on existing Teams channels/chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) + +* Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current createdDateTime and replaces it during migration. -* You can use the startMigration API, which enables migration mode on existing Teams channels, allowing import of historical messages. Previously, import operations were restricted to newly created standard channels in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) +#### Channel Migration -* You can define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel’s current createdDateTime and replaces it during migration. The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. +* The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. -#### Request +#### Channel Request -```http +```https POST /teams/{team-id}/channels/{channel-id}/startMigration { ACTUAL CODE @@ -48,11 +50,28 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` +#### Chat Migration + +* The supported chat types include Group chats and One-on-one (1:1) chats. **Meeting chats are not supported. External members are supported in all applicable chat types.** +* The startMigration API initiates the message migration process by setting the migrationMode property to **inProgress** for a specified chat. + +#### Chat Request + +```https +POST /chats/{chat-id}/startMigration +{ + ACTUAL CODE +"conversationCreationDateTime": "2024-01-01T00:00:00Z" +} +``` + +#### Channel and Chat Response + +For both channels and chats, if the request is successful, the method returns a **204 No Content** status code. The response body is empty. + > [!NOTE] > > * If no request body is provided, the API uses the current date and time as the minimum timestamp. > * `conversationCreationDateTime` must be: > * Greater than the minimum value for `DateTimeOffset`. > * Less than the current value of the channel's `CreatedDateTime`. - -#### Chat Migration From 92871b35b2ef5e875758ab0b65311b4c59222bda Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 7 Aug 2025 15:09:51 +0530 Subject: [PATCH 11/72] Added Example --- .../new-draft-external-messages-to-teams.md | 33 +++++++++++++++---- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 388c026de24..148ef22903c 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -21,7 +21,7 @@ Use the step-by-step migration flow to ensure a seamless transition of historica ## Step-by-Step Migration Flow -### Step 1: Create or select a channel/chat +1. ### Create or select a channel/chat Namespace: microsoft.graph @@ -30,7 +30,7 @@ You can either create a new channel or chat in a Team or use an existing channel > [!NOTE] > All APIs listed in the following sections require the `Teamswork.Migrate.All` permission in the application context. Delegated authentication isn't supported. -### Step 2: Use startMigration API to start channel and chat migration +2. ### Use startMigration API to start channel and chat migration * Use the startMigration API, to enable migration mode on existing Teams channels/chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) @@ -42,10 +42,10 @@ You can either create a new channel or chat in a Team or use an existing channel #### Channel Request -```https +```HTTP POST /teams/{team-id}/channels/{channel-id}/startMigration { - ACTUAL CODE + "conversationCreationDateTime": "2024-01-01T00:00:00Z" } ``` @@ -57,10 +57,10 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration #### Chat Request -```https +```HTTP POST /chats/{chat-id}/startMigration { - ACTUAL CODE + "conversationCreationDateTime": "2024-01-01T00:00:00Z" } ``` @@ -69,9 +69,28 @@ POST /chats/{chat-id}/startMigration For both channels and chats, if the request is successful, the method returns a **204 No Content** status code. The response body is empty. +**Example of a request**: + +```HTTP +POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration + +{ +“conversationCreationDateTime”: “2024-01-01T00:00:00Z” +} +``` + +Response of the request: +**HTTP/1.1 204 No Content** + > [!NOTE] > > * If no request body is provided, the API uses the current date and time as the minimum timestamp. > * `conversationCreationDateTime` must be: > * Greater than the minimum value for `DateTimeOffset`. -> * Less than the current value of the channel's `CreatedDateTime`. +> * Less than the current value of the channel or chat's `CreatedDateTime`. + +3. Call the **GET /channel/chat API** to confirm that the **migrationMode** property is set to **inProgress**, after completing step 2. + +4. ### Import messages using POST API + +Go to [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) and use the POST API, to begin sending back-in-time messages. From 25afb264eadb4b88c6318beb9b62728a70daa1d8 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 7 Aug 2025 22:58:59 +0530 Subject: [PATCH 12/72] Added content for completing chat and channel migration --- .../new-draft-external-messages-to-teams.md | 64 +++++++++++++++++-- 1 file changed, 59 insertions(+), 5 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 148ef22903c..16cafe9fbf2 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -36,11 +36,11 @@ You can either create a new channel or chat in a Team or use an existing channel * Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current createdDateTime and replaces it during migration. -#### Channel Migration +#### Channel migration * The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. -#### Channel Request +#### Channel request ```HTTP POST /teams/{team-id}/channels/{channel-id}/startMigration @@ -50,12 +50,12 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` -#### Chat Migration +#### Chat migration * The supported chat types include Group chats and One-on-one (1:1) chats. **Meeting chats are not supported. External members are supported in all applicable chat types.** * The startMigration API initiates the message migration process by setting the migrationMode property to **inProgress** for a specified chat. -#### Chat Request +#### Chat request ```HTTP POST /chats/{chat-id}/startMigration @@ -65,7 +65,7 @@ POST /chats/{chat-id}/startMigration } ``` -#### Channel and Chat Response +#### Channel and Chat response For both channels and chats, if the request is successful, the method returns a **204 No Content** status code. The response body is empty. @@ -94,3 +94,57 @@ Response of the request: 4. ### Import messages using POST API Go to [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) and use the POST API, to begin sending back-in-time messages. + +5. ### Complete channel and chat migration + +Namespace: microsoft.graph + +Use the **completeMigration** API to finish the migration process for both new and existing channels and chats. Previously, this operation was limited to newly created Standard channels and chats initiated for the initial migration flow. + +#### Complete Channel Migration + +* When a channel is created in migration mode for the initial import flow, calling the **completeMigration** API updates the migrationMode property to completed. **This change is permanent and marks the channel as fully migrated.** +* After calling completeMigration, you can still import extra messages by using the startMigration API. + +#### Request for Completing Channel Migration + +```HTTP +POST /teams/{team-id}/channels/{channel-id}/completeMigration +``` + +#### Complete Chat Migration + +* For existing chats already in migration mode, call the **completeMigration** API to update the migrationMode property to completed. **This marks the chat as fully migrated.** +* After calling completeMigration on a new or existing chat, you can continue importing messages by using the startMigration API. + +#### Request for Completing Chat Migration + +```HTTP +POST /chats/{chat-id}/completeMigration +``` + +> [!IMPORTANT] +> Don't include a request body when calling this method for channels or chats. If the request is successful, the method returns a 204 No Content status code. The response body is empty. +> +> [!NOTE] +> +> In Migration Mode: +> +> * Certain operations such as sending messages and adding members are restricted. +> * Calling the completeMigration API means that channel or chat migration is complete and normal operations can resume. + +#### Supported channel or chat types + +|Entity Type |Sub Type |Migration Mode Support |Notes| +|---------|---------|---------|---------| +|**Channels** | General, Standard, Private, Shared | New and existing | Must be created or already in migration mode | +|**Chats** | Group, One-on-one (1:1) | New and existing | Meeting chats not supported; external members supported | + +6. Call the GET /channel/chat API to verify that the migrationMode property is marked as **completed**. + +## See also + +* [Microsoft Graph and Teams integration](/graph/teams-concept-overview) +* [Export content with the Microsoft Teams Export APIs](/microsoftteams/export-teams-content) +* [Microsoft Teams service limits](/graph/throttling-limits#microsoft-teams-service-limits) +* [Licensing and payment requirements for the Microsoft Teams API](/graph/teams-licenses) From 2775fd252aab7da17b104a07c07668e79c09a2b2 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 29 Aug 2025 07:17:04 +0530 Subject: [PATCH 13/72] incorporated internal review changes --- .../new-draft-external-messages-to-teams.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 16cafe9fbf2..1f3f2b444a9 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -10,7 +10,7 @@ ms.date: 01/08/2025 # Use Microsoft Graph to Import Messages from External Platforms to Teams -You can use Microsoft Graph to migrate users' existing message history and data from an external system into a Teams channel. This feature enables users to continue conversations without interruption, by recreating the messaging hierarchy from a third-party platform directly within Teams. +You can use Microsoft Graph to migrate existing message history and data from an external system into a Teams channel. This feature enables users to continue conversations without interruption, by recreating the messaging hierarchy from a third-party platform directly within Teams. > [!NOTE] > In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. @@ -21,7 +21,7 @@ Use the step-by-step migration flow to ensure a seamless transition of historica ## Step-by-Step Migration Flow -1. ### Create or select a channel/chat +### 1. Create or select a channel/chat Namespace: microsoft.graph @@ -30,7 +30,7 @@ You can either create a new channel or chat in a Team or use an existing channel > [!NOTE] > All APIs listed in the following sections require the `Teamswork.Migrate.All` permission in the application context. Delegated authentication isn't supported. -2. ### Use startMigration API to start channel and chat migration +### 2. Use startMigration API to start channel and chat migration * Use the startMigration API, to enable migration mode on existing Teams channels/chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) @@ -89,13 +89,13 @@ Response of the request: > * Greater than the minimum value for `DateTimeOffset`. > * Less than the current value of the channel or chat's `CreatedDateTime`. -3. Call the **GET /channel/chat API** to confirm that the **migrationMode** property is set to **inProgress**, after completing step 2. +### 3. Call the GET /channel/chat API to confirm that the **migrationMode** property is set to **inProgress**, after completing step 2 -4. ### Import messages using POST API +### 4. Import messages using POST API Go to [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) and use the POST API, to begin sending back-in-time messages. -5. ### Complete channel and chat migration +### 5. Complete channel and chat migration Namespace: microsoft.graph From 616767e33dbf5a529d31ab05686e9e096d502cb0 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 29 Aug 2025 07:38:40 +0530 Subject: [PATCH 14/72] added second-level headings --- .../new-draft-external-messages-to-teams.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index 1f3f2b444a9..b3b72c05d3e 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -36,7 +36,7 @@ You can either create a new channel or chat in a Team or use an existing channel * Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current createdDateTime and replaces it during migration. -#### Channel migration +#### 2.1 Channel migration * The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. @@ -50,7 +50,7 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` -#### Chat migration +#### 2.2 Chat migration * The supported chat types include Group chats and One-on-one (1:1) chats. **Meeting chats are not supported. External members are supported in all applicable chat types.** * The startMigration API initiates the message migration process by setting the migrationMode property to **inProgress** for a specified chat. @@ -101,7 +101,7 @@ Namespace: microsoft.graph Use the **completeMigration** API to finish the migration process for both new and existing channels and chats. Previously, this operation was limited to newly created Standard channels and chats initiated for the initial migration flow. -#### Complete Channel Migration +#### 5.1 Complete Channel Migration * When a channel is created in migration mode for the initial import flow, calling the **completeMigration** API updates the migrationMode property to completed. **This change is permanent and marks the channel as fully migrated.** * After calling completeMigration, you can still import extra messages by using the startMigration API. @@ -112,7 +112,7 @@ Use the **completeMigration** API to finish the migration process for both new a POST /teams/{team-id}/channels/{channel-id}/completeMigration ``` -#### Complete Chat Migration +#### 5.2 Complete Chat Migration * For existing chats already in migration mode, call the **completeMigration** API to update the migrationMode property to completed. **This marks the chat as fully migrated.** * After calling completeMigration on a new or existing chat, you can continue importing messages by using the startMigration API. @@ -140,7 +140,7 @@ POST /chats/{chat-id}/completeMigration |**Channels** | General, Standard, Private, Shared | New and existing | Must be created or already in migration mode | |**Chats** | Group, One-on-one (1:1) | New and existing | Meeting chats not supported; external members supported | -6. Call the GET /channel/chat API to verify that the migrationMode property is marked as **completed**. +### 6. Call the GET /channel/chat API to verify that the migrationMode property is marked as **completed** ## See also From 970f339f44fd3f15f51501e1c7226edfdc3ca3d8 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 29 Aug 2025 07:46:00 +0530 Subject: [PATCH 15/72] saved file --- .../import-messages/import-external-messages-to-teams.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index fafd2dbb3c3..0c4061cf885 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -93,7 +93,6 @@ You can receive the error message in the following scenarios: > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+1%3A+Create+a+team&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-1-create-a-team&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - ## Step 2: Create a channel Creating a channel for the imported messages is similar to the create team scenario: @@ -296,6 +295,7 @@ HTTP/1.1 200 OK "reactions": [] } ``` + > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+3%3A+Import+messages&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-3-import-messages&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) @@ -332,7 +332,6 @@ Action called on a `team` or `channel` that isn't in `migrationMode`. > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+4%3A+Complete+migration+mode&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-4-complete-migration-mode&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - ## Step five: Add team members You can add a member to a team [using the Teams UI](https://support.microsoft.com/office/add-members-to-a-team-in-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9) or Microsoft Graph [add member](/graph/api/group-post-members?view=graph-rest-beta&tabs=http&preserve-view=true) API: @@ -376,7 +375,6 @@ HTTP/1.1 204 No Content > [!NOTE] > Inline images are the only type of media supported by the import message API schema. - ##### Import content scope The following table provides the content scope: @@ -396,7 +394,6 @@ The following table provides the content scope: ||Cross posts between channels| ||Shared channels| - ## See also * [Microsoft Graph and Teams integration](/graph/teams-concept-overview) From eb4476d0fbf88aec35050f43b9fe5e36a8efa397 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 25 Sep 2025 16:25:56 +0530 Subject: [PATCH 16/72] changes in draft --- .../new-draft-external-messages-to-teams.md | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index b3b72c05d3e..d8f11d8502f 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -8,31 +8,34 @@ ms.owner: TBD ms.date: 01/08/2025 --- -# Use Microsoft Graph to Import Messages from External Platforms to Teams +# Import messages from external Platforms to Teams through Microsoft Graph -You can use Microsoft Graph to migrate existing message history and data from an external system into a Teams channel. This feature enables users to continue conversations without interruption, by recreating the messaging hierarchy from a third-party platform directly within Teams. +Use Microsoft Graph to migrate users' existing message history and data from an external system into Teams. Users can continue their conversations seamlessly without interruption, by recreating the messaging hierarchy from a third-party platform directly within Teams. > [!NOTE] -> In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. +> In future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. -## API Migration Workflow +## Understand API migration workflow -Use the step-by-step migration flow to ensure a seamless transition of historical messages in both existing and newly created channels or chats by enabling migration mode. +You can ensure a seamless transition of historical messages, in both existing and newly created channels or chats by enabling the migration mode. All the APIs listed in the following table require **Teamswork.Migrate.All** permission in the application context. Delegated authentication isn't supported for these APIs. -## Step-by-Step Migration Flow +Channel APIs -### 1. Create or select a channel/chat +|APIs |Context | +|---------|---------| +|Row1 | | +|Row2 | | +|Row3 | | + +### 1. Create or select a channel or chat Namespace: microsoft.graph You can either create a new channel or chat in a Team or use an existing channel or chat. -> [!NOTE] -> All APIs listed in the following sections require the `Teamswork.Migrate.All` permission in the application context. Delegated authentication isn't supported. - -### 2. Use startMigration API to start channel and chat migration +### 2. Use startMigration API to bring channel and chat into migration mode -* Use the startMigration API, to enable migration mode on existing Teams channels/chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. Refer [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) +* Use the startMigration API, to enable migration mode on existing Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. See [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) * Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current createdDateTime and replaces it during migration. From c1e3c1effc8468bebc8d456fb1c56cff1974da5a Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 26 Sep 2025 09:07:55 +0530 Subject: [PATCH 17/72] changes in the content --- .../new-draft-external-messages-to-teams.md | 32 ++++++++++++------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md index d8f11d8502f..10217aa6cce 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md @@ -4,8 +4,8 @@ description: Learn how to use Microsoft Graph to import historical messages and ms.localizationpriority: high author: "surbhigupta" ms.topic: overview -ms.owner: TBD -ms.date: 01/08/2025 +ms.owner: mehakagarwal +ms.date: 26/09/2025 --- # Import messages from external Platforms to Teams through Microsoft Graph @@ -17,15 +17,19 @@ Use Microsoft Graph to migrate users' existing message history and data from an ## Understand API migration workflow -You can ensure a seamless transition of historical messages, in both existing and newly created channels or chats by enabling the migration mode. All the APIs listed in the following table require **Teamswork.Migrate.All** permission in the application context. Delegated authentication isn't supported for these APIs. +You can ensure a seamless transition of historical messages, in both existing and newly created channels or chats by performing the following steps: -Channel APIs +1. [1. Create or select a channel or chat](#1-create-or-select-a-channel-or-chat) +1. [2. Use startMigration API to bring channel and chat into migration mode](#2-use-startmigration-api-to-bring-channel-and-chat-into-migration-mode) +1. +1. -|APIs |Context | -|---------|---------| -|Row1 | | -|Row2 | | -|Row3 | | +Delegated authentication isn't supported. Permissions required for both channel and chat APIs are tabulated as follows: + +|APIs |Permission required |Auth Type | +|---------|---------|---------| +|startMigration | Teamswork.Migrate.All | Application | +|completeMigration | Teamswork.Migrate.All | Application | ### 1. Create or select a channel or chat @@ -53,9 +57,13 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` +#### Channel response + +If the request is successful, the method returns a **204 No Content** status code. The response body is empty. + #### 2.2 Chat migration -* The supported chat types include Group chats and One-on-one (1:1) chats. **Meeting chats are not supported. External members are supported in all applicable chat types.** +* The supported chat types include Group chats and One-on-one (1:1) chats. Meeting chats are not supported. External members are supported in all applicable chat types. * The startMigration API initiates the message migration process by setting the migrationMode property to **inProgress** for a specified chat. #### Chat request @@ -68,9 +76,9 @@ POST /chats/{chat-id}/startMigration } ``` -#### Channel and Chat response +#### Chat response -For both channels and chats, if the request is successful, the method returns a **204 No Content** status code. The response body is empty. +If the request is successful, the method returns a **204 No Content** status code. The response body is empty. **Example of a request**: From d1f96dfade558ccbe2621301fd165d58c180c3f0 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 26 Sep 2025 13:41:53 +0530 Subject: [PATCH 18/72] renamed file and seperated chat and channel migration APIs --- ...rt-external-platform-messages-to-teams.md} | 44 +++++++++++-------- 1 file changed, 26 insertions(+), 18 deletions(-) rename msteams-platform/graph-api/import-messages/{new-draft-external-messages-to-teams.md => import-external-platform-messages-to-teams.md} (77%) diff --git a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md similarity index 77% rename from msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md rename to msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 10217aa6cce..8199fe08dde 100644 --- a/msteams-platform/graph-api/import-messages/new-draft-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -5,7 +5,7 @@ ms.localizationpriority: high author: "surbhigupta" ms.topic: overview ms.owner: mehakagarwal -ms.date: 26/09/2025 +ms.date: 09/26/2025 --- # Import messages from external Platforms to Teams through Microsoft Graph @@ -19,17 +19,14 @@ Use Microsoft Graph to migrate users' existing message history and data from an You can ensure a seamless transition of historical messages, in both existing and newly created channels or chats by performing the following steps: -1. [1. Create or select a channel or chat](#1-create-or-select-a-channel-or-chat) -1. [2. Use startMigration API to bring channel and chat into migration mode](#2-use-startmigration-api-to-bring-channel-and-chat-into-migration-mode) -1. -1. +[1. Create or select a channel or chat](#1-create-or-select-a-channel-or-chat) +[2. Use startMigration API](#2-use-startmigration-api) Delegated authentication isn't supported. Permissions required for both channel and chat APIs are tabulated as follows: -|APIs |Permission required |Auth Type | -|---------|---------|---------| -|startMigration | Teamswork.Migrate.All | Application | -|completeMigration | Teamswork.Migrate.All | Application | +|ScopeName|DisplayName| Type|Entities/APIs covered| +|---------|---------|---------|---------| +| `Teamwork.Migrate.All`| Manage migration to Microsoft Teams | Application-only |`POST /teams`| ### 1. Create or select a channel or chat @@ -37,15 +34,15 @@ Namespace: microsoft.graph You can either create a new channel or chat in a Team or use an existing channel or chat. -### 2. Use startMigration API to bring channel and chat into migration mode +### 2. Use startMigration API -* Use the startMigration API, to enable migration mode on existing Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. See [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) +* Use the `startMigration` API, to enable migration mode on existing Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. See [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md). * Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current createdDateTime and replaces it during migration. #### 2.1 Channel migration -* The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. +The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. #### Channel request @@ -59,12 +56,24 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration #### Channel response -If the request is successful, the method returns a **204 No Content** status code. The response body is empty. +If the request is successful, the method returns a '204 No Content' status code. The response body is empty. + +Example of a channel request: + +```HTTP +POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration +{ +“conversationCreationDateTime”: “2024-01-01T00:00:00Z” +} + +``` + +Response of the request: **HTTP/1.1 204 No Content** #### 2.2 Chat migration * The supported chat types include Group chats and One-on-one (1:1) chats. Meeting chats are not supported. External members are supported in all applicable chat types. -* The startMigration API initiates the message migration process by setting the migrationMode property to **inProgress** for a specified chat. +* The startMigration API initiates the message migration process by setting the migrationMode property to 'inProgress' for a specified chat. #### Chat request @@ -78,9 +87,9 @@ POST /chats/{chat-id}/startMigration #### Chat response -If the request is successful, the method returns a **204 No Content** status code. The response body is empty. +If the request is successful, the method returns a *204 No Content* status code. The response body is empty. -**Example of a request**: +Example of a chat request: ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration @@ -90,8 +99,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 } ``` -Response of the request: -**HTTP/1.1 204 No Content** +Response of the request: **HTTP/1.1 204 No Content** > [!NOTE] > From 734f87ed3086a9035974d33e2890211a9106a70f Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 26 Sep 2025 14:58:57 +0530 Subject: [PATCH 19/72] Changed Step 3 --- ...ort-external-platform-messages-to-teams.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 8199fe08dde..fbf235875cf 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -21,6 +21,9 @@ You can ensure a seamless transition of historical messages, in both existing an [1. Create or select a channel or chat](#1-create-or-select-a-channel-or-chat) [2. Use startMigration API](#2-use-startmigration-api) +[3. Call the GET API](#3-call-the-get-api) +[4. Import messages using POST API](#4-import-messages-using-post-api) +[6. Call the GET /channel/chat API (#6-call-the-get-channelchat-api-to-verify-that-the-migrationmode-property-is-marked-as-completed) Delegated authentication isn't supported. Permissions required for both channel and chat APIs are tabulated as follows: @@ -32,11 +35,11 @@ Delegated authentication isn't supported. Permissions required for both channel Namespace: microsoft.graph -You can either create a new channel or chat in a Team or use an existing channel or chat. +You can either create a new channel or chat in a Team or use an existing channel or chat, to migrate users' message history from any external application to Teams. ### 2. Use startMigration API -* Use the `startMigration` API, to enable migration mode on existing Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. See [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md). +* Use the `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. See [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md). * Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current createdDateTime and replaces it during migration. @@ -104,11 +107,17 @@ Response of the request: **HTTP/1.1 204 No Content** > [!NOTE] > > * If no request body is provided, the API uses the current date and time as the minimum timestamp. -> * `conversationCreationDateTime` must be: +> `conversationCreationDateTime` must be: > * Greater than the minimum value for `DateTimeOffset`. > * Less than the current value of the channel or chat's `CreatedDateTime`. -### 3. Call the GET /channel/chat API to confirm that the **migrationMode** property is set to **inProgress**, after completing step 2 +### 3. Call the GET API + +After completing Step 2, call the `GET channel` or `GET chat` API to confirm that the *migrationMode* property is set to *inProgress*. For more information see [GET Channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http) + +```HTTP +GET /teams/{team-id}/channels/{channel-id} +``` ### 4. Import messages using POST API @@ -118,7 +127,7 @@ Go to [Import third-party platform messages to Teams using Microsoft Graph](impo Namespace: microsoft.graph -Use the **completeMigration** API to finish the migration process for both new and existing channels and chats. Previously, this operation was limited to newly created Standard channels and chats initiated for the initial migration flow. +Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. Previously, this operation was limited to newly created Standard channels and chats initiated for the initial migration flow. #### 5.1 Complete Channel Migration From ec8b327f4b3365fca5be603e723c83fb73bd0234 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 29 Sep 2025 06:30:43 +0530 Subject: [PATCH 20/72] Changed the numbering and headings --- ...ort-external-platform-messages-to-teams.md | 51 ++++++++++--------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index fbf235875cf..19ed27ceaf0 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -8,46 +8,47 @@ ms.owner: mehakagarwal ms.date: 09/26/2025 --- -# Import messages from external Platforms to Teams through Microsoft Graph +# Import external platform messages to Teams via Microsoft Graph Use Microsoft Graph to migrate users' existing message history and data from an external system into Teams. Users can continue their conversations seamlessly without interruption, by recreating the messaging hierarchy from a third-party platform directly within Teams. > [!NOTE] -> In future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. +> In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. -## Understand API migration workflow +## Understand the API migration workflow You can ensure a seamless transition of historical messages, in both existing and newly created channels or chats by performing the following steps: -[1. Create or select a channel or chat](#1-create-or-select-a-channel-or-chat) -[2. Use startMigration API](#2-use-startmigration-api) -[3. Call the GET API](#3-call-the-get-api) -[4. Import messages using POST API](#4-import-messages-using-post-api) -[6. Call the GET /channel/chat API (#6-call-the-get-channelchat-api-to-verify-that-the-migrationmode-property-is-marked-as-completed) +1. [Create or select an existing channel or chat](#create-or-select-an-existing-channel-or-chat) +1. [Use startMigration API](#use-startmigration-api) +1. [Call GET API to check migrationMode status](#call-get-api-to-check-migrationmode-status) +1. [Import messages using POST API](#import-messages-using-post-api) +1. [Complete channel and chat migration](#complete-channel-and-chat-migration) +1. [Call GET API to verify migrationMode](#call-get-api-to-verify-migrationmode) -Delegated authentication isn't supported. Permissions required for both channel and chat APIs are tabulated as follows: +## Permissions -|ScopeName|DisplayName| Type|Entities/APIs covered| +Delegated authentication isn't supported. + +|ScopeName|DisplayName| Type|APIs covered| |---------|---------|---------|---------| | `Teamwork.Migrate.All`| Manage migration to Microsoft Teams | Application-only |`POST /teams`| -### 1. Create or select a channel or chat - -Namespace: microsoft.graph +## Create or select an existing channel or chat You can either create a new channel or chat in a Team or use an existing channel or chat, to migrate users' message history from any external application to Teams. -### 2. Use startMigration API +## Use startMigration API * Use the `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. See [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md). * Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current createdDateTime and replaces it during migration. -#### 2.1 Channel migration +### Channel migration The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. -#### Channel request +### Channel request ```HTTP POST /teams/{team-id}/channels/{channel-id}/startMigration @@ -57,7 +58,7 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` -#### Channel response +### Channel response If the request is successful, the method returns a '204 No Content' status code. The response body is empty. @@ -73,7 +74,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 Response of the request: **HTTP/1.1 204 No Content** -#### 2.2 Chat migration +#### Chat migration * The supported chat types include Group chats and One-on-one (1:1) chats. Meeting chats are not supported. External members are supported in all applicable chat types. * The startMigration API initiates the message migration process by setting the migrationMode property to 'inProgress' for a specified chat. @@ -111,7 +112,7 @@ Response of the request: **HTTP/1.1 204 No Content** > * Greater than the minimum value for `DateTimeOffset`. > * Less than the current value of the channel or chat's `CreatedDateTime`. -### 3. Call the GET API +## Call GET API to check migrationMode status After completing Step 2, call the `GET channel` or `GET chat` API to confirm that the *migrationMode* property is set to *inProgress*. For more information see [GET Channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http) @@ -119,17 +120,17 @@ After completing Step 2, call the `GET channel` or `GET chat` API to confirm tha GET /teams/{team-id}/channels/{channel-id} ``` -### 4. Import messages using POST API +## Import messages using POST API Go to [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) and use the POST API, to begin sending back-in-time messages. -### 5. Complete channel and chat migration +## Complete channel and chat migration Namespace: microsoft.graph Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. Previously, this operation was limited to newly created Standard channels and chats initiated for the initial migration flow. -#### 5.1 Complete Channel Migration +### Complete Channel Migration * When a channel is created in migration mode for the initial import flow, calling the **completeMigration** API updates the migrationMode property to completed. **This change is permanent and marks the channel as fully migrated.** * After calling completeMigration, you can still import extra messages by using the startMigration API. @@ -140,7 +141,7 @@ Use the `completeMigration` API to finish the migration process for both new and POST /teams/{team-id}/channels/{channel-id}/completeMigration ``` -#### 5.2 Complete Chat Migration +### Complete Chat Migration * For existing chats already in migration mode, call the **completeMigration** API to update the migrationMode property to completed. **This marks the chat as fully migrated.** * After calling completeMigration on a new or existing chat, you can continue importing messages by using the startMigration API. @@ -168,7 +169,9 @@ POST /chats/{chat-id}/completeMigration |**Channels** | General, Standard, Private, Shared | New and existing | Must be created or already in migration mode | |**Chats** | Group, One-on-one (1:1) | New and existing | Meeting chats not supported; external members supported | -### 6. Call the GET /channel/chat API to verify that the migrationMode property is marked as **completed** +## Call GET API to verify migrationMode + +to verify that the migrationMode property is marked as **completed** ## See also From 7f6dddfc88b3d25bb64725fa32a2a31c75696049 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 29 Sep 2025 07:06:57 +0530 Subject: [PATCH 21/72] added permissions and supported channel types Acrolinx fixed --- ...ort-external-platform-messages-to-teams.md | 42 ++++++++++++------- 1 file changed, 28 insertions(+), 14 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 19ed27ceaf0..9a9122519d9 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -15,18 +15,32 @@ Use Microsoft Graph to migrate users' existing message history and data from an > [!NOTE] > In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. +## Prerequisites + +### Analyze and prepare message data + +* Review the third-party messages to decide what is migrated. +* Extract the selected data from the third-party channel or chat. +* Map the third-party channel or chat structure to the Teams structure. +* Convert imported data into a format that's suitable for migration. + +### Set up your Microsoft 365 tenant + +* Ensure that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). +* Make sure that team members are in Microsoft Entra ID. For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Microsoft Entra ID. + ## Understand the API migration workflow You can ensure a seamless transition of historical messages, in both existing and newly created channels or chats by performing the following steps: 1. [Create or select an existing channel or chat](#create-or-select-an-existing-channel-or-chat) -1. [Use startMigration API](#use-startmigration-api) +1. [Use startMigration API to import messages](#use-startmigration-api-to-import-messages) 1. [Call GET API to check migrationMode status](#call-get-api-to-check-migrationmode-status) 1. [Import messages using POST API](#import-messages-using-post-api) 1. [Complete channel and chat migration](#complete-channel-and-chat-migration) 1. [Call GET API to verify migrationMode](#call-get-api-to-verify-migrationmode) -## Permissions +### Permissions Delegated authentication isn't supported. @@ -34,11 +48,18 @@ Delegated authentication isn't supported. |---------|---------|---------|---------| | `Teamwork.Migrate.All`| Manage migration to Microsoft Teams | Application-only |`POST /teams`| +### Supported channel or chat types + +|Entities |Sub type |Migration mode Support |Notes| +|---------|---------|---------|---------| +|**Channels** | Standard, Private, Shared | New and existing | Must be created or already in migration mode | +|**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | + ## Create or select an existing channel or chat -You can either create a new channel or chat in a Team or use an existing channel or chat, to migrate users' message history from any external application to Teams. +You can create a new channel or chat in a Team, or use an existing one, to migrate users' message history from an external application to Teams. -## Use startMigration API +## Use startMigration API to import messages * Use the `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. See [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md). @@ -76,7 +97,7 @@ Response of the request: **HTTP/1.1 204 No Content** #### Chat migration -* The supported chat types include Group chats and One-on-one (1:1) chats. Meeting chats are not supported. External members are supported in all applicable chat types. +* The supported chat types include Group chats and One-on-one (1:1) chats. Meeting chats aren't supported. External members are supported in all applicable chat types. * The startMigration API initiates the message migration process by setting the migrationMode property to 'inProgress' for a specified chat. #### Chat request @@ -114,7 +135,7 @@ Response of the request: **HTTP/1.1 204 No Content** ## Call GET API to check migrationMode status -After completing Step 2, call the `GET channel` or `GET chat` API to confirm that the *migrationMode* property is set to *inProgress*. For more information see [GET Channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http) +After completing Step 2, call the `GET channel` or `GET chat` API to confirm that the *migrationMode* property is set to *inProgress*. For more information, see [GET Channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http) ```HTTP GET /teams/{team-id}/channels/{channel-id} @@ -162,16 +183,9 @@ POST /chats/{chat-id}/completeMigration > * Certain operations such as sending messages and adding members are restricted. > * Calling the completeMigration API means that channel or chat migration is complete and normal operations can resume. -#### Supported channel or chat types - -|Entity Type |Sub Type |Migration Mode Support |Notes| -|---------|---------|---------|---------| -|**Channels** | General, Standard, Private, Shared | New and existing | Must be created or already in migration mode | -|**Chats** | Group, One-on-one (1:1) | New and existing | Meeting chats not supported; external members supported | - ## Call GET API to verify migrationMode -to verify that the migrationMode property is marked as **completed** +To verify that the migrationMode property is marked as **completed** ## See also From 11bd1db6fa4d72f001f6fb19e3380076f37b8e0c Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 29 Sep 2025 13:10:36 +0530 Subject: [PATCH 22/72] made a tunnel --- ...ort-external-platform-messages-to-teams.md | 25 +++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 9a9122519d9..6b1434d4b2c 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -61,15 +61,14 @@ You can create a new channel or chat in a Team, or use an existing one, to migra ## Use startMigration API to import messages -* Use the `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. See [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md). +* Use `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. +* Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current `createdDateTime` and replaces it during migration. -* Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current createdDateTime and replaces it during migration. +### [Channel migration](#tab/channelmigration) -### Channel migration +All the Shared, Private, and Public channels are supported. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. -The supported channels are all the existing Shared, Private, and Public channels. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. - -### Channel request +#### Channel request ```HTTP POST /teams/{team-id}/channels/{channel-id}/startMigration @@ -79,7 +78,7 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` -### Channel response +#### Channel response If the request is successful, the method returns a '204 No Content' status code. The response body is empty. @@ -91,14 +90,14 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 “conversationCreationDateTime”: “2024-01-01T00:00:00Z” } -``` +Response +HTTP/1.1 204 No Content -Response of the request: **HTTP/1.1 204 No Content** +``` -#### Chat migration +### [Chat migration](#tab/chatmigration) -* The supported chat types include Group chats and One-on-one (1:1) chats. Meeting chats aren't supported. External members are supported in all applicable chat types. -* The startMigration API initiates the message migration process by setting the migrationMode property to 'inProgress' for a specified chat. +* The `startMigration` API initiates the message migration process by setting the migrationMode property to 'inProgress' for a specified chat. #### Chat request @@ -112,7 +111,7 @@ POST /chats/{chat-id}/startMigration #### Chat response -If the request is successful, the method returns a *204 No Content* status code. The response body is empty. +If the request is successful, the method returns a 204 No Content status code. The response body is empty. Example of a chat request: From 37b05a1ab261b3deffd3212bbb2f5b8c14ab6b4e Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 29 Sep 2025 16:30:00 +0530 Subject: [PATCH 23/72] updated sections and content --- ...ort-external-platform-messages-to-teams.md | 268 ++++++++++++++---- 1 file changed, 212 insertions(+), 56 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 6b1434d4b2c..e784df914ce 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -29,16 +29,16 @@ Use Microsoft Graph to migrate users' existing message history and data from an * Ensure that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). * Make sure that team members are in Microsoft Entra ID. For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Microsoft Entra ID. -## Understand the API migration workflow +## Understand the migration workflow You can ensure a seamless transition of historical messages, in both existing and newly created channels or chats by performing the following steps: -1. [Create or select an existing channel or chat](#create-or-select-an-existing-channel-or-chat) -1. [Use startMigration API to import messages](#use-startmigration-api-to-import-messages) -1. [Call GET API to check migrationMode status](#call-get-api-to-check-migrationmode-status) -1. [Import messages using POST API](#import-messages-using-post-api) -1. [Complete channel and chat migration](#complete-channel-and-chat-migration) -1. [Call GET API to verify migrationMode](#call-get-api-to-verify-migrationmode) +* [Step 1: Create or select an existing channel or chat](#step-1-create-or-select-an-existing-channel-or-chat) +* [Step 2: Use startMigration API to import messages](#step-2-use-startmigration-api-to-import-messages) +* [Step 3: Call GET API to check migrationMode status](#step-3-call-get-api-to-check-migrationmode-status) +* [Step 4: Import messages using POST API](#step-4-import-messages-using-post-api) +* [Step 5: Complete channel and chat migration](#step-5-complete-channel-and-chat-migration) +* [Step 6: Call GET API to verify migrationMode](#step-6-call-get-api-to-verify-migrationmode) ### Permissions @@ -48,25 +48,25 @@ Delegated authentication isn't supported. |---------|---------|---------|---------| | `Teamwork.Migrate.All`| Manage migration to Microsoft Teams | Application-only |`POST /teams`| -### Supported channel or chat types +### Supported channel and chat types |Entities |Sub type |Migration mode Support |Notes| |---------|---------|---------|---------| |**Channels** | Standard, Private, Shared | New and existing | Must be created or already in migration mode | |**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | -## Create or select an existing channel or chat +## Step 1: Create or select an existing channel or chat You can create a new channel or chat in a Team, or use an existing one, to migrate users' message history from an external application to Teams. -## Use startMigration API to import messages +## Step 2: Use startMigration API to import messages * Use `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. -* Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current `createdDateTime` and replaces it during migration. +* Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current `creationDateTime` and replaces it during migration. ### [Channel migration](#tab/channelmigration) -All the Shared, Private, and Public channels are supported. You can optionally provide a request body to specify the minimum timestamp for the messages to be migrated. +You can provide a request body to specify the minimum timestamp for the messages to be migrated, optionally. #### Channel request @@ -74,30 +74,33 @@ All the Shared, Private, and Public channels are supported. You can optionally p POST /teams/{team-id}/channels/{channel-id}/startMigration { -"conversationCreationDateTime": "2024-01-01T00:00:00Z" +"conversationcreationDateTime": "2024-01-01T00:00:00Z" } ``` #### Channel response -If the request is successful, the method returns a '204 No Content' status code. The response body is empty. +If the request is successful, the method returns the following status: -Example of a channel request: +```http +HTTP/1.1 204 No Content +``` + +The response body is empty. + +Example: ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration { -“conversationCreationDateTime”: “2024-01-01T00:00:00Z” +“conversationcreationDateTime”: “2024-01-01T00:00:00Z” } -Response -HTTP/1.1 204 No Content - ``` ### [Chat migration](#tab/chatmigration) -* The `startMigration` API initiates the message migration process by setting the migrationMode property to 'inProgress' for a specified chat. +* `startMigration` API initiates the message migration process by setting the migrationMode property to 'inProgress' for a specified chat. #### Chat request @@ -105,66 +108,210 @@ HTTP/1.1 204 No Content POST /chats/{chat-id}/startMigration { -"conversationCreationDateTime": "2024-01-01T00:00:00Z" +"conversationcreationDateTime": "2024-01-01T00:00:00Z" } ``` #### Chat response -If the request is successful, the method returns a 204 No Content status code. The response body is empty. +If the request is successful, the method returns the following status: -Example of a chat request: +```http +HTTP/1.1 204 No Content +``` + +The response body is empty. + +Example: ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration { -“conversationCreationDateTime”: “2024-01-01T00:00:00Z” +“conversationcreationDateTime”: “2024-01-01T00:00:00Z” } -``` -Response of the request: **HTTP/1.1 204 No Content** +``` > [!NOTE] > -> * If no request body is provided, the API uses the current date and time as the minimum timestamp. +> If no request body is provided, the API uses the current date and time as the minimum timestamp. > `conversationCreationDateTime` must be: -> * Greater than the minimum value for `DateTimeOffset`. -> * Less than the current value of the channel or chat's `CreatedDateTime`. +> +> * Greater than the minimum value for `DateTimeOffset`. +> +> * Less than the current value of the channel or chat's `creationDateTime`. -## Call GET API to check migrationMode status +## Step 3: Call GET API to check migrationMode status -After completing Step 2, call the `GET channel` or `GET chat` API to confirm that the *migrationMode* property is set to *inProgress*. For more information, see [GET Channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http) +Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` property is set to `inProgress`. For more information on the APIs, see: -```HTTP -GET /teams/{team-id}/channels/{channel-id} +* [GET channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) +* [GET chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) + +## Step 4: Import messages using POST API + +Use POST API to import back-in-time messages using the `createdDateTime` and `from` keys in the request body. + +> [!NOTE] +> +> * Messages imported with `createdDateTime` earlier than the message thread `createdDateTime` isn't supported. +> * `createdDateTime` must be unique across messages in the same thread. +> * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has the value of `createdDateTime` set as *2020-09-16T05:50:31.0025302Z*, then it would be converted to *2020-09-16T05:50:31.002Z* when the message is ingested. + +### Request (POST message that is text-only) + +```http +POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages + +{ + "createdDateTime":"2019-02-04T19:58:15.511Z", + "from":{ + "user":{ + "id":"id-value", + "displayName":"Joh Doe", + "userIdentityType":"aadUser" + } + }, + "body":{ + "contentType":"html", + "content":"Hello World" + } +} +``` + +#### Response + +```http +HTTP/1.1 200 OK + +{ + "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels('channel-id')/messages/$entity", + "id":"id-value", + "replyToId":null, + "etag":"id-value", + "messageType":"message", + "createdDateTime":"2019-02-04T19:58:15.58Z", + "lastModifiedDateTime":null, + "deleted":false, + "subject":null, + "summary":null, + "importance":"normal", + "locale":"en-us", + "policyViolation":null, + "from":{ + "application":null, + "device":null, + "conversation":null, + "user":{ + "id":"id-value", + "displayName":"Joh Doe", + "userIdentityType":"aadUser" + } + }, + "body":{ + "contentType":"html", + "content":"Hello World" + }, + "attachments":[ + ], + "mentions":[ + ], + "reactions":[ + ] +} +``` + +#### Error message + +```http +400 Bad Request +``` + +#### Request (POST a message with inline image) + +> [!NOTE] +> +> * There are no special permission scopes in this scenario since the request is part of `chatMessage`. +> * The scopes for `chatMessage` apply here. + +```http +POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages + +{ + "body": { + "contentType": "html", + "content": "
\n
\n\n
\n\n\n
\n
" + }, + "hostedContents":[ + { + "@microsoft.graph.temporaryId": "1", + "contentBytes": "iVBORw0KGgoAAAANSUhEUgAAANcAAAExCAYAAADvFzeeAAAXjklEQVR4Ae2d/XNU1RnH+9e0FFrA0RCIyaS8hRA0HV5KbS1gHRgVpjMClY4GHJ3yYm1HCmXaWttaaZUZtIIFKYi8lFAkvOQ9u5vN225IARVBbX9/Os9NbrLZbMjmhCfJPX5+2Lmb3T25y3O+n/M599x7w9f+++UXwoMakIF7n4GvUdR7X1RqSk01A8CFuZm5GGUAuIwKi72wF3ABF+YyygBwGRUWc2Eu4AIuzGWUAeAyKizmwlzABVyYyygDwGVUWMyFuYALuDCXUQaAy6iwmAtzARdwfWXMdeuzT+TGxz3Sfb1LunrapL07IW3pePDQ5/qavqef0c+OdYAELuAac4jGGkLL9rdvfyo9N9ODQAqBGmmrwGlb/R0u3xG4gMspOC5hG882CoRaaCSA8n1ff9doIQMu4PIOrus3u+8ZVNnw6e/Od5AALuDKOyz5hmqiPnfnzi1J9bSbgRWCpvvQfY307wQu4BoxJCOFaDK8rwsQmQsUIQhWW93XSIsewAVckYdLQ24F0Ui/926AARdwRRounZ6Np7GyYdN9DzdFBC7gijRc43GMlQ1U9s/6HXJNjYELuHI<<-----Removed----->>>>", + "contentType": "image/png" + } + ] +} ``` -## Import messages using POST API +#### Response -Go to [Import third-party platform messages to Teams using Microsoft Graph](import-external-messages-to-teams.md) and use the POST API, to begin sending back-in-time messages. +```http +HTTP/1.1 200 OK -## Complete channel and chat migration +{ + "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels('channel-id')/messages/$entity", + "id": "id-value", + "replyToId": null, + "etag": "id-value", + "messageType": "message", + "createdDateTime": "2019-02-04T19:58:15.511Z", + "lastModifiedDateTime": null, + "deleted": false, + "subject": null, + "summary": null, + "importance": "normal", + "locale": "en-us", + "policyViolation": null, + "from": { + "application": null, + "device": null, + "conversation": null, + "user": { + "id": "id-value", + "displayName": "Joh Doe", + "userIdentityType": "aadUser" + } + }, + "body": { + "contentType": "html", + "content": "
\n
\n\n
\n\n\n
\n
" + }, + "attachments": [], + "mentions": [], + "reactions": [] +} +``` -Namespace: microsoft.graph +## Step 5: Complete channel and chat migration -Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. Previously, this operation was limited to newly created Standard channels and chats initiated for the initial migration flow. +Use `completeMigration` API to finish the migration process for both new and existing channels and chats: +Previously, this operation was limited to newly created standard channels and chats, initiated for the initial migration flow. -### Complete Channel Migration +### [Complete channel migration](#tab/completechannelmigration) -* When a channel is created in migration mode for the initial import flow, calling the **completeMigration** API updates the migrationMode property to completed. **This change is permanent and marks the channel as fully migrated.** -* After calling completeMigration, you can still import extra messages by using the startMigration API. +* When a channel is created in migration mode for the initial import flow, calling the `completeMigration` API updates the `migrationMode` property to completed. This change is permanent and marks the channel as fully migrated. +* After calling `completeMigration`, you can still import extra messages by using the `startMigration` API. -#### Request for Completing Channel Migration +#### Request for completing channel migration ```HTTP POST /teams/{team-id}/channels/{channel-id}/completeMigration ``` -### Complete Chat Migration +### [Complete chat migration](#tab/completechatmigration) -* For existing chats already in migration mode, call the **completeMigration** API to update the migrationMode property to completed. **This marks the chat as fully migrated.** -* After calling completeMigration on a new or existing chat, you can continue importing messages by using the startMigration API. +* For existing chats, which are already in migration mode, call `completeMigration` API to update the `migrationMode` property to completed. This process marks the chat as fully migrated. +* After calling `completeMigration` on a new or existing chat, you can continue importing messages by using `startMigration` API. #### Request for Completing Chat Migration @@ -172,19 +319,28 @@ POST /teams/{team-id}/channels/{channel-id}/completeMigration POST /chats/{chat-id}/completeMigration ``` -> [!IMPORTANT] -> Don't include a request body when calling this method for channels or chats. If the request is successful, the method returns a 204 No Content status code. The response body is empty. -> -> [!NOTE] -> -> In Migration Mode: -> -> * Certain operations such as sending messages and adding members are restricted. -> * Calling the completeMigration API means that channel or chat migration is complete and normal operations can resume. +## Step 6: Call GET API to verify migrationMode + +Call `GET channel` or `GET chat` API, to verify that the migrationMode property is marked as completed. + +### Import content scope -## Call GET API to verify migrationMode +The following table provides the content scope: -To verify that the migrationMode property is marked as **completed** +|In-scope | Out-of-scope| +|----------|--------------------------| +|Team and channel messages|1:1 and group chat messages| +|Created time of the original message|Private channels| +|Inline images as part of the message|At mentions| +|Links to existing files in SPO or OneDrive|Reactions| +|Messages with rich text|Videos| +|Message reply chain|Announcements| +|High throughput processing|Code snippets| +||Stickers| +||Emojis| +||Quotes| +||Cross posts between channels| +||Shared channels| ## See also From 1af3bba20e561d676e65051fd69569f44fbe5aef Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 29 Sep 2025 16:41:55 +0530 Subject: [PATCH 24/72] removed tunnel --- .../import-external-platform-messages-to-teams.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index e784df914ce..71c09c0eaa2 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -297,7 +297,7 @@ HTTP/1.1 200 OK Use `completeMigration` API to finish the migration process for both new and existing channels and chats: Previously, this operation was limited to newly created standard channels and chats, initiated for the initial migration flow. -### [Complete channel migration](#tab/completechannelmigration) +### Complete channel migration * When a channel is created in migration mode for the initial import flow, calling the `completeMigration` API updates the `migrationMode` property to completed. This change is permanent and marks the channel as fully migrated. * After calling `completeMigration`, you can still import extra messages by using the `startMigration` API. @@ -308,12 +308,12 @@ Previously, this operation was limited to newly created standard channels and ch POST /teams/{team-id}/channels/{channel-id}/completeMigration ``` -### [Complete chat migration](#tab/completechatmigration) +### Complete chat migration * For existing chats, which are already in migration mode, call `completeMigration` API to update the `migrationMode` property to completed. This process marks the chat as fully migrated. * After calling `completeMigration` on a new or existing chat, you can continue importing messages by using `startMigration` API. -#### Request for Completing Chat Migration +#### Request for completing chat migration ```HTTP POST /chats/{chat-id}/completeMigration @@ -321,7 +321,7 @@ POST /chats/{chat-id}/completeMigration ## Step 6: Call GET API to verify migrationMode -Call `GET channel` or `GET chat` API, to verify that the migrationMode property is marked as completed. +Call `GET channel` or `GET chat` API, to verify that the `migrationMode` property is marked as completed. ### Import content scope From 3daa96f6fd8cd02d0701b49786a3623793d0fec1 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 29 Sep 2025 16:56:16 +0530 Subject: [PATCH 25/72] Update import-external-platform-messages-to-teams.md --- .../import-external-platform-messages-to-teams.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 71c09c0eaa2..fb52fd753ce 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -50,7 +50,7 @@ Delegated authentication isn't supported. ### Supported channel and chat types -|Entities |Sub type |Migration mode Support |Notes| +|Entities |Sub type |Migration mode support |Notes| |---------|---------|---------|---------| |**Channels** | Standard, Private, Shared | New and existing | Must be created or already in migration mode | |**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | @@ -133,15 +133,6 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ``` -> [!NOTE] -> -> If no request body is provided, the API uses the current date and time as the minimum timestamp. -> `conversationCreationDateTime` must be: -> -> * Greater than the minimum value for `DateTimeOffset`. -> -> * Less than the current value of the channel or chat's `creationDateTime`. - ## Step 3: Call GET API to check migrationMode status Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` property is set to `inProgress`. For more information on the APIs, see: From e0559735f4296fe71d97de0c6192feb787f3d1db Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 29 Sep 2025 17:05:11 +0530 Subject: [PATCH 26/72] end tabset added --- .../import-external-platform-messages-to-teams.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index fb52fd753ce..4b8c6b03ccb 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -133,6 +133,8 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ``` +### End Tabset {.tabset} + ## Step 3: Call GET API to check migrationMode status Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` property is set to `inProgress`. For more information on the APIs, see: From b5888491b5df3e4b63ae45b3904cbf51e63f28a2 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 29 Sep 2025 17:13:15 +0530 Subject: [PATCH 27/72] ending loop component --- .../import-external-platform-messages-to-teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 4b8c6b03ccb..6f99b5e4390 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -133,7 +133,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ``` -### End Tabset {.tabset} +--- ## Step 3: Call GET API to check migrationMode status From debfdbde5171d1f5e2a8afd396844deee8b5d43b Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Tue, 30 Sep 2025 20:45:26 +0530 Subject: [PATCH 28/72] incorporated review changes --- ...ort-external-platform-messages-to-teams.md | 57 +++++++------------ 1 file changed, 22 insertions(+), 35 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 6f99b5e4390..a138d7c904e 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -10,37 +10,12 @@ ms.date: 09/26/2025 # Import external platform messages to Teams via Microsoft Graph -Use Microsoft Graph to migrate users' existing message history and data from an external system into Teams. Users can continue their conversations seamlessly without interruption, by recreating the messaging hierarchy from a third-party platform directly within Teams. +Use Microsoft Graph to import users' existing message history and data from an external system into Teams. Users can continue their conversations seamlessly without interruption, by recreating the messaging hierarchy from a third-party platform directly within Teams. > [!NOTE] > In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. -## Prerequisites - -### Analyze and prepare message data - -* Review the third-party messages to decide what is migrated. -* Extract the selected data from the third-party channel or chat. -* Map the third-party channel or chat structure to the Teams structure. -* Convert imported data into a format that's suitable for migration. - -### Set up your Microsoft 365 tenant - -* Ensure that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). -* Make sure that team members are in Microsoft Entra ID. For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Microsoft Entra ID. - -## Understand the migration workflow - -You can ensure a seamless transition of historical messages, in both existing and newly created channels or chats by performing the following steps: - -* [Step 1: Create or select an existing channel or chat](#step-1-create-or-select-an-existing-channel-or-chat) -* [Step 2: Use startMigration API to import messages](#step-2-use-startmigration-api-to-import-messages) -* [Step 3: Call GET API to check migrationMode status](#step-3-call-get-api-to-check-migrationmode-status) -* [Step 4: Import messages using POST API](#step-4-import-messages-using-post-api) -* [Step 5: Complete channel and chat migration](#step-5-complete-channel-and-chat-migration) -* [Step 6: Call GET API to verify migrationMode](#step-6-call-get-api-to-verify-migrationmode) - -### Permissions +## Permissions Delegated authentication isn't supported. @@ -55,18 +30,28 @@ Delegated authentication isn't supported. |**Channels** | Standard, Private, Shared | New and existing | Must be created or already in migration mode | |**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | -## Step 1: Create or select an existing channel or chat +## Understand the import process -You can create a new channel or chat in a Team, or use an existing one, to migrate users' message history from an external application to Teams. +You can import historical messages seamlessly, in both; existing and newly created channels or chats by performing the following migration steps: -## Step 2: Use startMigration API to import messages +1. [Create or use an existing channel or chat](#step-1-create-or-use-an-existing-channel-or-chat) +1. [Step 2: Enable migration mode to import messages](#step-2-enable-migration-mode-to-import-messages) +1. [Step 3: Call GET API to check migrationMode status](#step-3-call-get-api-to-check-migrationmode-status) +1. [Step 4: Import messages using POST API](#step-4-import-messages-using-post-api) +1. [Step 5: Complete channel and chat migration](#step-5-complete-channel-and-chat-migration) +1. [Step 6: Call GET API to verify migrationMode](#step-6-call-get-api-to-verify-migrationmode) -* Use `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. Previously, import operations were restricted to newly created standard channels and chats in an empty state. -* Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current `creationDateTime` and replaces it during migration. +## Step 1: Create or use an existing channel or chat -### [Channel migration](#tab/channelmigration) +You can create a new channel or chat in a team, or use existing ones, to migrate users' message history from an external application to Teams. + +## Step 2: Enable migration mode to import messages -You can provide a request body to specify the minimum timestamp for the messages to be migrated, optionally. +* Use the `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. +* Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current `createdDateTime`. The provided timestamp replaces the existing `createdDateTime` of the channel. +* The`creationDateTime`property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as a minimum timestamp. + +### [Channel migration](#tab/channelmigration) #### Channel request @@ -78,6 +63,8 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` +`conversationCreationDateTime` must be greater than the minimum value for`DateTimeOffset` and less than the current value of the channel's `createdDateTime`. + #### Channel response If the request is successful, the method returns the following status: @@ -100,7 +87,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ### [Chat migration](#tab/chatmigration) -* `startMigration` API initiates the message migration process by setting the migrationMode property to 'inProgress' for a specified chat. +The `startMigration` API initiates the message migration process by setting the `migrationMode` property to `inProgress` for a specified chat. #### Chat request From a2436ac7db67a76348c7db91bf8e70512313ca1a Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Tue, 30 Sep 2025 21:54:36 +0530 Subject: [PATCH 29/72] Update import-external-platform-messages-to-teams.md --- ...ort-external-platform-messages-to-teams.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index a138d7c904e..3ac4b8a424d 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -5,7 +5,7 @@ ms.localizationpriority: high author: "surbhigupta" ms.topic: overview ms.owner: mehakagarwal -ms.date: 09/26/2025 +ms.date: 09/30/2025 --- # Import external platform messages to Teams via Microsoft Graph @@ -35,11 +35,11 @@ Delegated authentication isn't supported. You can import historical messages seamlessly, in both; existing and newly created channels or chats by performing the following migration steps: 1. [Create or use an existing channel or chat](#step-1-create-or-use-an-existing-channel-or-chat) -1. [Step 2: Enable migration mode to import messages](#step-2-enable-migration-mode-to-import-messages) -1. [Step 3: Call GET API to check migrationMode status](#step-3-call-get-api-to-check-migrationmode-status) -1. [Step 4: Import messages using POST API](#step-4-import-messages-using-post-api) -1. [Step 5: Complete channel and chat migration](#step-5-complete-channel-and-chat-migration) -1. [Step 6: Call GET API to verify migrationMode](#step-6-call-get-api-to-verify-migrationmode) +1. [Enable migration mode to import messages](#step-2-enable-migration-mode-to-import-messages) +1. [Call GET API to check the migration status](#step-3-call-get-api-to-check-the-migration-status) +1. +1. [Complete channel and chat migration](#step-5-complete-channel-and-chat-migration) +1. [Call GET API to verify migrationMode](#step-6-call-get-api-to-verify-migrationmode) ## Step 1: Create or use an existing channel or chat @@ -122,16 +122,16 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 --- -## Step 3: Call GET API to check migrationMode status +## Step 3: check the migration status -Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` property is set to `inProgress`. For more information on the APIs, see: +Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` property is set to `inProgress`. For more information see: * [GET channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) * [GET chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) -## Step 4: Import messages using POST API +## Step 4: Import messages -Use POST API to import back-in-time messages using the `createdDateTime` and `from` keys in the request body. +Use the `POST` API to import back-in-time messages using the `createdDateTime` and `from` keys in the request body. > [!NOTE] > From 957b062c5a9e25dc29c6ee5ac963f24e47af8a3a Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Tue, 30 Sep 2025 22:11:39 +0530 Subject: [PATCH 30/72] Self review --- ...ort-external-platform-messages-to-teams.md | 23 +++++++++---------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 3ac4b8a424d..25f00181cb1 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -27,17 +27,17 @@ Delegated authentication isn't supported. |Entities |Sub type |Migration mode support |Notes| |---------|---------|---------|---------| -|**Channels** | Standard, Private, Shared | New and existing | Must be created or already in migration mode | +|**Channels** | Standard, Private, Shared | New and existing | Channels must be created or already in migration mode | |**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | ## Understand the import process -You can import historical messages seamlessly, in both; existing and newly created channels or chats by performing the following migration steps: +You can import historical messages seamlessly, in both; existing and newly created channels or chats by performing the following steps: 1. [Create or use an existing channel or chat](#step-1-create-or-use-an-existing-channel-or-chat) 1. [Enable migration mode to import messages](#step-2-enable-migration-mode-to-import-messages) -1. [Call GET API to check the migration status](#step-3-call-get-api-to-check-the-migration-status) -1. +1. [Check the migration status](#step-3-check-the-migration-status) +1. [Import messages](#step-4-import-messages) 1. [Complete channel and chat migration](#step-5-complete-channel-and-chat-migration) 1. [Call GET API to verify migrationMode](#step-6-call-get-api-to-verify-migrationmode) @@ -122,14 +122,14 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 --- -## Step 3: check the migration status +## Step 3: Check the migration status -Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` property is set to `inProgress`. For more information see: +Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` property is set to `inProgress`. For more information, see: * [GET channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) * [GET chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) -## Step 4: Import messages +## Step 4: Import messages Use the `POST` API to import back-in-time messages using the `createdDateTime` and `from` keys in the request body. @@ -274,8 +274,7 @@ HTTP/1.1 200 OK ## Step 5: Complete channel and chat migration -Use `completeMigration` API to finish the migration process for both new and existing channels and chats: -Previously, this operation was limited to newly created standard channels and chats, initiated for the initial migration flow. +Use the `completeMigration` API to finish the migration process for both new and existing channels and chats, as follows: ### Complete channel migration @@ -290,8 +289,8 @@ POST /teams/{team-id}/channels/{channel-id}/completeMigration ### Complete chat migration -* For existing chats, which are already in migration mode, call `completeMigration` API to update the `migrationMode` property to completed. This process marks the chat as fully migrated. -* After calling `completeMigration` on a new or existing chat, you can continue importing messages by using `startMigration` API. +* For existing chats, which are already in migration mode, call the `completeMigration` API to update the `migrationMode` property to completed. This process marks the chat as fully migrated. +* After calling `completeMigration` on a new or existing chat, you can continue importing messages by using the `startMigration` API. #### Request for completing chat migration @@ -301,7 +300,7 @@ POST /chats/{chat-id}/completeMigration ## Step 6: Call GET API to verify migrationMode -Call `GET channel` or `GET chat` API, to verify that the `migrationMode` property is marked as completed. +Call `GET channel` or `GET chat` APIs, to verify that the `migrationMode` property is marked as completed. ### Import content scope From a134244cf3a0aad88682f59e682aa42fef173e9f Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 6 Nov 2025 12:46:00 +0530 Subject: [PATCH 31/72] Fixes from SME and peer review --- ...ort-external-platform-messages-to-teams.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 25f00181cb1..f2767684091 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -5,12 +5,12 @@ ms.localizationpriority: high author: "surbhigupta" ms.topic: overview ms.owner: mehakagarwal -ms.date: 09/30/2025 +ms.date: 11/06/2025 --- -# Import external platform messages to Teams via Microsoft Graph +# Import external platform messages to Teams with Microsoft Graph -Use Microsoft Graph to import users' existing message history and data from an external system into Teams. Users can continue their conversations seamlessly without interruption, by recreating the messaging hierarchy from a third-party platform directly within Teams. +Use Microsoft Graph to import users' existing message history and data from an external system into Teams. Users can continue their conversations seamlessly without interruption, as their messaging hierarchy from the third-party platform is recreated directly within Teams. > [!NOTE] > In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. @@ -21,27 +21,27 @@ Delegated authentication isn't supported. |ScopeName|DisplayName| Type|APIs covered| |---------|---------|---------|---------| -| `Teamwork.Migrate.All`| Manage migration to Microsoft Teams | Application-only |`POST /teams`| +| `Teamwork.Migrate.All`| Manage migration to Microsoft Teams | Application-only|`POST/teams`| -### Supported channel and chat types +## Supported channel and chat types |Entities |Sub type |Migration mode support |Notes| |---------|---------|---------|---------| |**Channels** | Standard, Private, Shared | New and existing | Channels must be created or already in migration mode | |**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | -## Understand the import process +## Import historical messages into Teams -You can import historical messages seamlessly, in both; existing and newly created channels or chats by performing the following steps: +You can import historical messages seamlessly, in both; the existing and newly created channels or chats by performing the following steps: -1. [Create or use an existing channel or chat](#step-1-create-or-use-an-existing-channel-or-chat) +1. [Create new or use an existing channel or chat](#step-1-create-new-or-use-an-existing-channel-or-chat) 1. [Enable migration mode to import messages](#step-2-enable-migration-mode-to-import-messages) -1. [Check the migration status](#step-3-check-the-migration-status) +1. [Check migration status](#step-3-check-migration-status) 1. [Import messages](#step-4-import-messages) -1. [Complete channel and chat migration](#step-5-complete-channel-and-chat-migration) +1. [Complete migration](#step-5-complete-migration) 1. [Call GET API to verify migrationMode](#step-6-call-get-api-to-verify-migrationmode) -## Step 1: Create or use an existing channel or chat +## Step 1: Create new or use an existing channel or chat You can create a new channel or chat in a team, or use existing ones, to migrate users' message history from an external application to Teams. @@ -59,7 +59,7 @@ You can create a new channel or chat in a team, or use existing ones, to migrate POST /teams/{team-id}/channels/{channel-id}/startMigration { -"conversationcreationDateTime": "2024-01-01T00:00:00Z" +"conversationCreationDateTime": "2024-01-01T00:00:00Z" } ``` @@ -80,7 +80,7 @@ Example: ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration { -“conversationcreationDateTime”: “2024-01-01T00:00:00Z” +“conversationCreationDateTime”: “2024-01-01T00:00:00Z” } ``` @@ -95,7 +95,7 @@ The `startMigration` API initiates the message migration process by setting the POST /chats/{chat-id}/startMigration { -"conversationcreationDateTime": "2024-01-01T00:00:00Z" +"conversationCreationDateTime": "2024-01-01T00:00:00Z" } ``` @@ -115,14 +115,14 @@ Example: POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration { -“conversationcreationDateTime”: “2024-01-01T00:00:00Z” +“conversationCreationDateTime”: “2024-01-01T00:00:00Z” } ``` --- -## Step 3: Check the migration status +## Step 3: Check migration status Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` property is set to `inProgress`. For more information, see: @@ -272,7 +272,7 @@ HTTP/1.1 200 OK } ``` -## Step 5: Complete channel and chat migration +## Step 5: Complete migration Use the `completeMigration` API to finish the migration process for both new and existing channels and chats, as follows: From e5853ea503b4e534a872dfdf702eb0a4f3f1b99b Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 6 Nov 2025 13:02:20 +0530 Subject: [PATCH 32/72] part 2 changes --- .../import-external-platform-messages-to-teams.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index f2767684091..031cd683bef 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -41,11 +41,11 @@ You can import historical messages seamlessly, in both; the existing and newly c 1. [Complete migration](#step-5-complete-migration) 1. [Call GET API to verify migrationMode](#step-6-call-get-api-to-verify-migrationmode) -## Step 1: Create new or use an existing channel or chat +### Step 1: Create new or use an existing channel or chat -You can create a new channel or chat in a team, or use existing ones, to migrate users' message history from an external application to Teams. +You can create a new channel or chat in a team, or use the ones existing on Teams, to migrate users' message history from an external application to Teams. -## Step 2: Enable migration mode to import messages +### Step 2: Enable migration mode to import messages * Use the `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. * Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current `createdDateTime`. The provided timestamp replaces the existing `createdDateTime` of the channel. @@ -122,14 +122,14 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 --- -## Step 3: Check migration status +### Step 3: Check migration status Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` property is set to `inProgress`. For more information, see: * [GET channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) * [GET chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) -## Step 4: Import messages +### Step 4: Import messages Use the `POST` API to import back-in-time messages using the `createdDateTime` and `from` keys in the request body. @@ -272,7 +272,7 @@ HTTP/1.1 200 OK } ``` -## Step 5: Complete migration +### Step 5: Complete migration Use the `completeMigration` API to finish the migration process for both new and existing channels and chats, as follows: @@ -298,7 +298,7 @@ POST /teams/{team-id}/channels/{channel-id}/completeMigration POST /chats/{chat-id}/completeMigration ``` -## Step 6: Call GET API to verify migrationMode +### Step 6: Call GET API to verify migrationMode Call `GET channel` or `GET chat` APIs, to verify that the `migrationMode` property is marked as completed. From 39027300f403e5e2e3d7679ff8eeaeb81d539650 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 6 Nov 2025 16:45:46 +0530 Subject: [PATCH 33/72] Update import-external-platform-messages-to-teams.md --- ...ort-external-platform-messages-to-teams.md | 35 ++++++++----------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 031cd683bef..f792210610b 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -50,10 +50,11 @@ You can create a new channel or chat in a team, or use the ones existing on Team * Use the `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. * Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current `createdDateTime`. The provided timestamp replaces the existing `createdDateTime` of the channel. * The`creationDateTime`property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as a minimum timestamp. +* The `startMigration` API initiates the message migration process by setting the `migrationMode` property to `inProgress` for a specified channel or chat. ### [Channel migration](#tab/channelmigration) -#### Channel request +#### request ```HTTP POST /teams/{team-id}/channels/{channel-id}/startMigration @@ -65,17 +66,15 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration `conversationCreationDateTime` must be greater than the minimum value for`DateTimeOffset` and less than the current value of the channel's `createdDateTime`. -#### Channel response +#### response -If the request is successful, the method returns the following status: +If the request is successful, the method returns an empty status: ```http HTTP/1.1 204 No Content ``` -The response body is empty. - -Example: +**Example**: ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration @@ -87,9 +86,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ### [Chat migration](#tab/chatmigration) -The `startMigration` API initiates the message migration process by setting the `migrationMode` property to `inProgress` for a specified chat. - -#### Chat request +#### request ```HTTP POST /chats/{chat-id}/startMigration @@ -99,17 +96,15 @@ POST /chats/{chat-id}/startMigration } ``` -#### Chat response +#### response -If the request is successful, the method returns the following status: +If the request is successful, the method returns an empty status: ```http HTTP/1.1 204 No Content ``` -The response body is empty. - -Example: +***Example**: ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration @@ -131,7 +126,7 @@ Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` proper ### Step 4: Import messages -Use the `POST` API to import back-in-time messages using the `createdDateTime` and `from` keys in the request body. +Use the `POST` API to import back-in-time messages using the `createdDateTime` and from keys in the request body. > [!NOTE] > @@ -212,8 +207,7 @@ HTTP/1.1 200 OK > [!NOTE] > -> * There are no special permission scopes in this scenario since the request is part of `chatMessage`. -> * The scopes for `chatMessage` apply here. +> No additional permission scopes are required. Use the standard `chatMessage` scopes. ```http POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages @@ -274,7 +268,7 @@ HTTP/1.1 200 OK ### Step 5: Complete migration -Use the `completeMigration` API to finish the migration process for both new and existing channels and chats, as follows: +Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. ### Complete channel migration @@ -300,9 +294,10 @@ POST /chats/{chat-id}/completeMigration ### Step 6: Call GET API to verify migrationMode -Call `GET channel` or `GET chat` APIs, to verify that the `migrationMode` property is marked as completed. +Call `GET channel` or `GET chat` APIs, to verify that the `migrationMode` property is marked as completed. For more information, see [GET channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or +[GET chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) -### Import content scope +## Import content scope The following table provides the content scope: From 65b7c169cc2a94c986425313f20bed4f69287be4 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 6 Nov 2025 16:49:41 +0530 Subject: [PATCH 34/72] Update import-external-platform-messages-to-teams.md --- .../import-external-platform-messages-to-teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index f792210610b..624c0d8076d 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -295,7 +295,7 @@ POST /chats/{chat-id}/completeMigration ### Step 6: Call GET API to verify migrationMode Call `GET channel` or `GET chat` APIs, to verify that the `migrationMode` property is marked as completed. For more information, see [GET channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or -[GET chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) +[GET chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true). ## Import content scope From 7331e29415798d7957949b602e82c18584e5781d Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 10 Nov 2025 12:17:54 +0530 Subject: [PATCH 35/72] Review comments addressed part 1 --- ...ort-external-platform-messages-to-teams.md | 45 +++++++++++-------- 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 624c0d8076d..46a59577340 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -1,28 +1,30 @@ --- -title: Import External Platform Messages Using Microsoft Graphs +title: Import external platform messages to Teams with Microsoft Graphs description: Learn how to use Microsoft Graph to import historical messages and data from all third-party platforms to Teams. ms.localizationpriority: high author: "surbhigupta" ms.topic: overview ms.owner: mehakagarwal -ms.date: 11/06/2025 +ms.date: 11/10/2025 --- -# Import external platform messages to Teams with Microsoft Graph +# Use Microsoft Graph APIs to import external messages into Teams -Use Microsoft Graph to import users' existing message history and data from an external system into Teams. Users can continue their conversations seamlessly without interruption, as their messaging hierarchy from the third-party platform is recreated directly within Teams. +Use Microsoft Graph to import users' existing message history and data from any third-party platform into Teams. Users can continue their conversations seamlessly without interruption, as their messaging hierarchy from the third-party platform is recreated directly within Teams. > [!NOTE] > In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. ## Permissions -Delegated authentication isn't supported. - -|ScopeName|DisplayName| Type|APIs covered| +|ScopeName|DisplayName|Type|APIs covered| |---------|---------|---------|---------| | `Teamwork.Migrate.All`| Manage migration to Microsoft Teams | Application-only|`POST/teams`| +> [!NOTE] +> Delegated authentication isn't supported. +> + ## Supported channel and chat types |Entities |Sub type |Migration mode support |Notes| @@ -30,31 +32,38 @@ Delegated authentication isn't supported. |**Channels** | Standard, Private, Shared | New and existing | Channels must be created or already in migration mode | |**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | +## Prerequisites + +Before you set up your Microsoft 365 tenant: + +* Verify that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). +* Verify that team members are in Microsoft Entra ID. For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Microsoft Entra ID. + ## Import historical messages into Teams -You can import historical messages seamlessly, in both; the existing and newly created channels or chats by performing the following steps: +You can import historical messages seamlessly, in both the existing and newly created channels or chats by performing the following steps: -1. [Create new or use an existing channel or chat](#step-1-create-new-or-use-an-existing-channel-or-chat) +1. [Create a new channel or chat or use an existing one](#step-1-create-a-new-channel-or-chat-or-use-an-existing-one) 1. [Enable migration mode to import messages](#step-2-enable-migration-mode-to-import-messages) 1. [Check migration status](#step-3-check-migration-status) 1. [Import messages](#step-4-import-messages) 1. [Complete migration](#step-5-complete-migration) 1. [Call GET API to verify migrationMode](#step-6-call-get-api-to-verify-migrationmode) -### Step 1: Create new or use an existing channel or chat +### Step 1: Create a new channel or chat or use an existing one -You can create a new channel or chat in a team, or use the ones existing on Teams, to migrate users' message history from an external application to Teams. +You can create a new channel or chat, or use an existing one, to migrate user's message history from any third-party platform to Teams. ### Step 2: Enable migration mode to import messages * Use the `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. * Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current `createdDateTime`. The provided timestamp replaces the existing `createdDateTime` of the channel. * The`creationDateTime`property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as a minimum timestamp. -* The `startMigration` API initiates the message migration process by setting the `migrationMode` property to `inProgress` for a specified channel or chat. +* The `startMigration` API initiates the message migration process by setting migration mode to `inProgress` for a specified channel or chat. ### [Channel migration](#tab/channelmigration) -#### request +#### Request ```HTTP POST /teams/{team-id}/channels/{channel-id}/startMigration @@ -64,9 +73,9 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` -`conversationCreationDateTime` must be greater than the minimum value for`DateTimeOffset` and less than the current value of the channel's `createdDateTime`. +`conversationCreationDateTime` must be greater than the minimum value for DateTimeOffset and less than the current value of the channel's `createdDateTime`. -#### response +#### Response If the request is successful, the method returns an empty status: @@ -86,7 +95,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ### [Chat migration](#tab/chatmigration) -#### request +#### Request ```HTTP POST /chats/{chat-id}/startMigration @@ -96,7 +105,7 @@ POST /chats/{chat-id}/startMigration } ``` -#### response +#### Response If the request is successful, the method returns an empty status: @@ -107,7 +116,7 @@ HTTP/1.1 204 No Content ***Example**: ```HTTP -POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration +POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration { “conversationCreationDateTime”: “2024-01-01T00:00:00Z” From b896017eff8031133990368131925dd17f20f8fb Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 10 Nov 2025 13:02:13 +0530 Subject: [PATCH 36/72] Added a Tip --- .../import-external-platform-messages-to-teams.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 46a59577340..cdcc80f577a 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -73,7 +73,10 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` -`conversationCreationDateTime` must be greater than the minimum value for DateTimeOffset and less than the current value of the channel's `createdDateTime`. +`conversationCreationDateTime` must be greater than the minimum value for `DateTimeOffset` and less than the current value of the channel's `createdDateTime`. + +> [!TIP] +> Microsoft Graph uses DateTimeOffset to represent date and time with a UTC offset for an accurate time zone. #### Response From a93ac0f9c7bec3cffeb90ff91d28b211519ff180 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 10 Nov 2025 13:15:35 +0530 Subject: [PATCH 37/72] review comments part 3 --- .../import-external-platform-messages-to-teams.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index cdcc80f577a..eb23ad4cea1 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -73,20 +73,19 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration } ``` -`conversationCreationDateTime` must be greater than the minimum value for `DateTimeOffset` and less than the current value of the channel's `createdDateTime`. - > [!TIP] > Microsoft Graph uses DateTimeOffset to represent date and time with a UTC offset for an accurate time zone. +>The `conversationCreationDateTime` must be greater than the minimum value for `DateTimeOffset` and less than the current value of the channel's `createdDateTime`. #### Response -If the request is successful, the method returns an empty status: +If the request is successful, the method returns an empty status. ```http HTTP/1.1 204 No Content ``` -**Example**: +**Example** ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration @@ -108,6 +107,10 @@ POST /chats/{chat-id}/startMigration } ``` +> [!TIP] +> Microsoft Graph uses DateTimeOffset to represent date and time with a UTC offset for an accurate time zone. +>The `conversationCreationDateTime` must be greater than the minimum value for `DateTimeOffset` and less than the current value of the chat's `createdDateTime`. + #### Response If the request is successful, the method returns an empty status: @@ -116,7 +119,7 @@ If the request is successful, the method returns an empty status: HTTP/1.1 204 No Content ``` -***Example**: +**Example** ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration From 6279c57732c123577e8da9fabd2435b66fdaeb7d Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 10 Nov 2025 16:34:07 +0530 Subject: [PATCH 38/72] moved the content scope table and part 3 changes --- ...ort-external-platform-messages-to-teams.md | 79 ++++++++++--------- 1 file changed, 42 insertions(+), 37 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index eb23ad4cea1..67d18ebdd70 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -48,7 +48,7 @@ You can import historical messages seamlessly, in both the existing and newly cr 1. [Check migration status](#step-3-check-migration-status) 1. [Import messages](#step-4-import-messages) 1. [Complete migration](#step-5-complete-migration) -1. [Call GET API to verify migrationMode](#step-6-call-get-api-to-verify-migrationmode) +1. [Verify migration mode completion](#step-6-verify-migration-mode-completion) ### Step 1: Create a new channel or chat or use an existing one @@ -56,10 +56,14 @@ You can create a new channel or chat, or use an existing one, to migrate user's ### Step 2: Enable migration mode to import messages -* Use the `startMigration` API, to enable migration mode on Teams channels or chats, and allow import of historical messages. -* Define a minimum timestamp for messages to be migrated. The provided timestamp must be older than the channel or chat’s current `createdDateTime`. The provided timestamp replaces the existing `createdDateTime` of the channel. -* The`creationDateTime`property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as a minimum timestamp. -* The `startMigration` API initiates the message migration process by setting migration mode to `inProgress` for a specified channel or chat. +Use the `startMigration` API to enable migration mode on Teams channels or chats, and allow import of historical messages. Migration mode is a special state that prevents certain operations, like sending messages and adding members, during the data migration process. +Migration mode is a special state that blocks certain operations, such as sending messages and adding members during data migration. + +Consider the following: + +* Define a minimum timestamp for messages to migrate. The provided timestamp must be older than the channel or chat’s current `createdDateTime`. This timestamp replaces the existing `createdDateTime` of the channel. +* The`creationDateTime`property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. +* The `startMigration` API starts the message migration process by setting the migration mode to `inProgress` for a specified channel or chat. ### [Channel migration](#tab/channelmigration) @@ -134,22 +138,22 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ### Step 3: Check migration status -Call `GET channel` or `GET chat` APIs to confirm that the `migrationMode` property is set to `inProgress`. For more information, see: +Call the `Get channel` or `Get chat` API to confirm that the migration mode state is set to `inProgress`. For more information, see: -* [GET channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) -* [GET chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) +* [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) +* [Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) ### Step 4: Import messages -Use the `POST` API to import back-in-time messages using the `createdDateTime` and from keys in the request body. +Use the `POST` API to import back-in-time messages by including the `createdDateTime` and `from` properties in the request body. > [!NOTE] > -> * Messages imported with `createdDateTime` earlier than the message thread `createdDateTime` isn't supported. +> * Messages imported with `createdDateTime` earlier than the message thread `createdDateTime` aren't supported. > * `createdDateTime` must be unique across messages in the same thread. -> * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has the value of `createdDateTime` set as *2020-09-16T05:50:31.0025302Z*, then it would be converted to *2020-09-16T05:50:31.002Z* when the message is ingested. +> * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has `createdDateTime` set to *2020-09-16T05:50:31.0025302Z*, it’s converted to *2020-09-16T05:50:31.002Z* when the message is ingested. -### Request (POST message that is text-only) +#### Send a text-only message using POST ```http POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages @@ -218,7 +222,9 @@ HTTP/1.1 200 OK 400 Bad Request ``` -#### Request (POST a message with inline image) +You can receive an error message if the`createdDateTime` property is set for the future. + +#### Send a message with an inline image using POST > [!NOTE] > @@ -281,11 +287,29 @@ HTTP/1.1 200 OK } ``` +### Content scope for import + +The following table provides the content scope. + +|In-scope | Out-of-scope| +|----------|--------------------------| +|Team and channel messages|At mentions| +|Created time of the original message|Announcements| +|Inline images as part of the message|Videos| +|Links to existing files in SPO or OneDrive|Code snippets| +|Messages with rich text|Sticker| +|Message reply chain|Quotes| +|High throughput processing|Cross posts between channels| +|1:1 and group chat messages|| +|Shared and private channels|| +|Reactions and emojis|| +||| + ### Step 5: Complete migration Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. -### Complete channel migration +#### Complete channel migration * When a channel is created in migration mode for the initial import flow, calling the `completeMigration` API updates the `migrationMode` property to completed. This change is permanent and marks the channel as fully migrated. * After calling `completeMigration`, you can still import extra messages by using the `startMigration` API. @@ -296,7 +320,7 @@ Use the `completeMigration` API to finish the migration process for both new and POST /teams/{team-id}/channels/{channel-id}/completeMigration ``` -### Complete chat migration +#### Complete chat migration * For existing chats, which are already in migration mode, call the `completeMigration` API to update the `migrationMode` property to completed. This process marks the chat as fully migrated. * After calling `completeMigration` on a new or existing chat, you can continue importing messages by using the `startMigration` API. @@ -307,29 +331,10 @@ POST /teams/{team-id}/channels/{channel-id}/completeMigration POST /chats/{chat-id}/completeMigration ``` -### Step 6: Call GET API to verify migrationMode - -Call `GET channel` or `GET chat` APIs, to verify that the `migrationMode` property is marked as completed. For more information, see [GET channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or -[GET chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true). - -## Import content scope +### Step 6: Verify migration mode completion -The following table provides the content scope: - -|In-scope | Out-of-scope| -|----------|--------------------------| -|Team and channel messages|1:1 and group chat messages| -|Created time of the original message|Private channels| -|Inline images as part of the message|At mentions| -|Links to existing files in SPO or OneDrive|Reactions| -|Messages with rich text|Videos| -|Message reply chain|Announcements| -|High throughput processing|Code snippets| -||Stickers| -||Emojis| -||Quotes| -||Cross posts between channels| -||Shared channels| +Call the `Get channel` or the `Get chat` API, to verify that the migration mode state is marked as completed. For more information, see [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or +[Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true). ## See also From 98f060278c4146802e9b62eccc817c59722897a6 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 10 Nov 2025 17:02:10 +0530 Subject: [PATCH 39/72] final changes and acrolinx --- ...import-external-platform-messages-to-teams.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 67d18ebdd70..e73e1aa9efb 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -59,7 +59,7 @@ You can create a new channel or chat, or use an existing one, to migrate user's Use the `startMigration` API to enable migration mode on Teams channels or chats, and allow import of historical messages. Migration mode is a special state that prevents certain operations, like sending messages and adding members, during the data migration process. Migration mode is a special state that blocks certain operations, such as sending messages and adding members during data migration. -Consider the following: +Consider the following points: * Define a minimum timestamp for messages to migrate. The provided timestamp must be older than the channel or chat’s current `createdDateTime`. This timestamp replaces the existing `createdDateTime` of the channel. * The`creationDateTime`property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. @@ -228,7 +228,7 @@ You can receive an error message if the`createdDateTime` property is set for the > [!NOTE] > -> No additional permission scopes are required. Use the standard `chatMessage` scopes. +> No other permission scopes are required. Use the standard `chatMessage` scopes. ```http POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages @@ -311,10 +311,11 @@ Use the `completeMigration` API to finish the migration process for both new and #### Complete channel migration -* When a channel is created in migration mode for the initial import flow, calling the `completeMigration` API updates the `migrationMode` property to completed. This change is permanent and marks the channel as fully migrated. -* After calling `completeMigration`, you can still import extra messages by using the `startMigration` API. +When a channel is created in migration mode for the initial import, use the `completeMigration` API to update its migration state to completed. This change ensures that the channel remains permanently available instead of being dropped after migration. -#### Request for completing channel migration +For existing channels already in migration mode, use the `completeMigration` API to mark the migration state as completed. After you send a `completeMigration` request for new or existing channels, you can still import more messages by calling the `startMigration` API. + +#### Request ```HTTP POST /teams/{team-id}/channels/{channel-id}/completeMigration @@ -322,10 +323,9 @@ POST /teams/{team-id}/channels/{channel-id}/completeMigration #### Complete chat migration -* For existing chats, which are already in migration mode, call the `completeMigration` API to update the `migrationMode` property to completed. This process marks the chat as fully migrated. -* After calling `completeMigration` on a new or existing chat, you can continue importing messages by using the `startMigration` API. +For existing chats, which are already in migration mode, call the `completeMigration` API to update the migration mode state to completed. This process marks the chat as fully migrated. After calling `completeMigration` on a new or existing chat, you can continue importing messages by using the `startMigration` API. -#### Request for completing chat migration +#### Request ```HTTP POST /chats/{chat-id}/completeMigration From 874f400f1a9f90d661175d72349a7b7fb99c4eb0 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Tue, 11 Nov 2025 13:30:40 +0530 Subject: [PATCH 40/72] deleted extra table row and added a lead line --- .../import-external-platform-messages-to-teams.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index e73e1aa9efb..e87b36cf109 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -65,6 +65,8 @@ Consider the following points: * The`creationDateTime`property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. * The `startMigration` API starts the message migration process by setting the migration mode to `inProgress` for a specified channel or chat. +To enable channel and chat migration in Teams, see the following: + ### [Channel migration](#tab/channelmigration) #### Request @@ -303,7 +305,7 @@ The following table provides the content scope. |1:1 and group chat messages|| |Shared and private channels|| |Reactions and emojis|| -||| +| ### Step 5: Complete migration From fca027914e0ebefb71eb0bf1d54189590415c3fe Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Tue, 11 Nov 2025 13:46:25 +0530 Subject: [PATCH 41/72] Update import-external-platform-messages-to-teams.md --- .../import-external-platform-messages-to-teams.md | 1 - 1 file changed, 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index e87b36cf109..9d437b1c58b 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -305,7 +305,6 @@ The following table provides the content scope. |1:1 and group chat messages|| |Shared and private channels|| |Reactions and emojis|| -| ### Step 5: Complete migration From cf612f3c8062c377dae6a7636cac5d8ba0aa2589 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Tue, 11 Nov 2025 17:05:36 +0530 Subject: [PATCH 42/72] Update import-external-platform-messages-to-teams.md --- .../import-external-platform-messages-to-teams.md | 1 - 1 file changed, 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index 9d437b1c58b..e1fa11847a8 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -57,7 +57,6 @@ You can create a new channel or chat, or use an existing one, to migrate user's ### Step 2: Enable migration mode to import messages Use the `startMigration` API to enable migration mode on Teams channels or chats, and allow import of historical messages. Migration mode is a special state that prevents certain operations, like sending messages and adding members, during the data migration process. -Migration mode is a special state that blocks certain operations, such as sending messages and adding members during data migration. Consider the following points: From 883ec94015d415d1dbb78c55e7112c2f438fff64 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 13 Nov 2025 11:06:22 +0530 Subject: [PATCH 43/72] Deleted new file and copied final content --- .../import-external-messages-to-teams.md | 402 ------------------ ...ort-external-platform-messages-to-teams.md | 59 ++- 2 files changed, 41 insertions(+), 420 deletions(-) delete mode 100644 msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md deleted file mode 100644 index 0c4061cf885..00000000000 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ /dev/null @@ -1,402 +0,0 @@ ---- -title: Import External Platform Messages -description: Learn how to use Microsoft Graph to import messages such as message history and data from an third-party platform to Teams. -ms.localizationpriority: high -author: "akjo" -ms.topic: overview -ms.owner: vishachadha -ms.date: 09/02/2022 ---- - -# Import third-party platform messages to Teams using Microsoft Graph - -With Microsoft Graph, you can migrate users' existing message history and data from an external system into a Teams channel. By enabling the recreation of a third-party platform messaging hierarchy inside Teams, users can continue their communications in a seamless manner and proceed without interruption. - -> [!NOTE] -> In the future, Microsoft may require you or your customers to pay additional fees based on the amount of data imported. - -## Import overview - -At a high level, the import process consists of the following: - -1. [Create a team with a back-in-time timestamp](#step-1-create-a-team). -1. [Create a channel with a back-in-time timestamp](#step-2-create-a-channel). -1. [Import external back-in-time dated messages](#step-3-import-messages). -1. [Complete the team and channel migration process](#step-4-complete-migration-mode). -1. [Add team members](#step-five-add-team-members). - -## Prerequisites - -### Analyze and prepare message data - -* Review the third-party data to decide what is migrated. -* Extract the selected data from the third-party chat system. -* Map the third-party chat structure to the Teams structure. -* Convert import data into format needed for migration. - -### Set up your Microsoft 365 tenant - -* Ensure that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). -* Make sure that team members are in Microsoft Entra ID. For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Microsoft Entra ID. - -## Step 1: Create a team - -Since you're migrating existing data, maintaining the original message timestamps, and preventing messaging activity during the migration process are key to recreating the user's existing message flow in Teams. This is achieved as follows: - -> [Create a new team](/graph/api/team-post?view=graph-rest-beta&tabs=http&preserve-view=true) with a back-in-time timestamp using the team resource `createdDateTime` property. Place the new team in `migration mode`, a special state that restricts users from most activities within the team until the migration process is complete. Include the `teamCreationMode` instance attribute with the `migration` value in the POST request to explicitly identify the new team as being created for migration. - -> [!NOTE] -> The `createdDateTime` field is only populated for instances of a team or channel that are migrated. - - - -#### Permission - -|ScopeName|DisplayName|Description|Type|Admin Consent?|Entities/APIs covered| -|-|-|-|-|-|-| -|`Teamwork.Migrate.All`|Manage migration to Microsoft Teams|Creating and managing resources for migration to Teams.|**Application-only**|**Yes**|`POST /teams`| - -#### Request (create a team in migration state) - -```http -POST https://graph.microsoft.com/v1.0/teams -Content-Type: application/json - -{ - "@microsoft.graph.teamCreationMode": "migration", - "template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')", - "displayName": "My Sample Team", - "description": "My Sample Team’s Description", - "createdDateTime": "2020-03-14T11:22:17.043Z" -} -``` - -#### Response - -```http -HTTP/1.1 202 Accepted -Location: /teams/{team-id}/operations/{operation-id} -Content-Location: /teams/{team-id} -``` - -#### Error message - -```http -400 Bad Request -``` - -You can receive the error message in the following scenarios: - -* If `createdDateTime` is set for future. -* If `createdDateTime` is correctly specified, but `teamCreationMode` instance attribute is missing or set to invalid value. - -> [!div class="nextstepaction"] -> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+1%3A+Create+a+team&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-1-create-a-team&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - -## Step 2: Create a channel - -Creating a channel for the imported messages is similar to the create team scenario: - -> [Create a new channel](/graph/api/channel-post?view=graph-rest-v1.0&tabs=http&preserve-view=true) with a back-in-time timestamp using the channel resource `createdDateTime` property. Place the new channel in `migration mode`, a special state that restricts users from most chat activities within the channel until the migration process is complete. Include the `channelCreationMode` instance attribute with the `migration` value in the POST request to explicitly identify the new team as being created for migration. - -#### Permission - -|ScopeName|DisplayName|Description|Type|Admin Consent?|Entities/APIs covered| -|-|-|-|-|-|-| -|`Teamwork.Migrate.All`|Manage migration to Microsoft Teams|Creating and managing resources for migration to Teams.|**Application-only**|**Yes**|`POST /teams`| - -#### Request (create a channel in migration state) - -```http -POST https://graph.microsoft.com/v1.0/teams/{team-id}/channels -Content-Type: application/json - -{ - "@microsoft.graph.channelCreationMode": "migration", - "displayName": "Architecture Discussion", - "description": "This channel is where we debate all future architecture plans", - "membershipType": "standard", - "createdDateTime": "2020-03-14T11:22:17.047Z" -} -``` - -#### Response - -```http -HTTP/1.1 202 Accepted - -{ - "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels/$entity", - "id":"id-value", - "createdDateTime":null, - "displayName":"Architecture Discussion", - "description":"This channel is where we debate all future architecture plans", - "isFavoriteByDefault":null, - "email":null, - "webUrl":null, - "membershipType":null, - "moderationSettings":null -} -``` - -#### Error message - -```http -400 Bad Request -``` - -You can receive the error message in the following scenarios: - -* If `createdDateTime` is set for future. -* If `createdDateTime` is correctly specified but `channelCreationMode` instance attribute is missing or set to invalid value. - -> [!div class="nextstepaction"] -> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+2%3A+Create+a+channel&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-2-create-a-channel&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - -## Step 3: Import messages - -After the team and channel have been created, you can begin sending back-in-time messages using the `createdDateTime` and `from` keys in the request body. - -> [!NOTE] -> -> * Messages imported with `createdDateTime` earlier than the message thread `createdDateTime` is not supported. -> * `createdDateTime` must be unique across messages in the same thread. -> * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has the value of `createdDateTime` set as *2020-09-16T05:50:31.0025302Z*, then it would be converted to *2020-09-16T05:50:31.002Z* when the message is ingested. - -#### Request (POST message that is text-only) - -```http -POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages - -{ - "createdDateTime":"2019-02-04T19:58:15.511Z", - "from":{ - "user":{ - "id":"id-value", - "displayName":"Joh Doe", - "userIdentityType":"aadUser" - } - }, - "body":{ - "contentType":"html", - "content":"Hello World" - } -} -``` - -#### Response - -```http -HTTP/1.1 200 OK - -{ - "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels('channel-id')/messages/$entity", - "id":"id-value", - "replyToId":null, - "etag":"id-value", - "messageType":"message", - "createdDateTime":"2019-02-04T19:58:15.58Z", - "lastModifiedDateTime":null, - "deleted":false, - "subject":null, - "summary":null, - "importance":"normal", - "locale":"en-us", - "policyViolation":null, - "from":{ - "application":null, - "device":null, - "conversation":null, - "user":{ - "id":"id-value", - "displayName":"Joh Doe", - "userIdentityType":"aadUser" - } - }, - "body":{ - "contentType":"html", - "content":"Hello World" - }, - "attachments":[ - ], - "mentions":[ - ], - "reactions":[ - ] -} -``` - -#### Error message - -```http -400 Bad Request -``` - -#### Request (POST a message with inline image) - -> [!NOTE] -> -> * There are no special permission scopes in this scenario since the request is part of `chatMessage`. -> * The scopes for `chatMessage` apply here. - -```http -POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages - -{ - "body": { - "contentType": "html", - "content": "
\n
\n\n
\n\n\n
\n
" - }, - "hostedContents":[ - { - "@microsoft.graph.temporaryId": "1", - "contentBytes": "iVBORw0KGgoAAAANSUhEUgAAANcAAAExCAYAAADvFzeeAAAXjklEQVR4Ae2d/XNU1RnH+9e0FFrA0RCIyaS8hRA0HV5KbS1gHRgVpjMClY4GHJ3yYm1HCmXaWttaaZUZtIIFKYi8lFAkvOQ9u5vN225IARVBbX9/Os9NbrLZbMjmhCfJPX5+2Lmb3T25y3O+n/M599x7w9f+++UXwoMakIF7n4GvUdR7X1RqSk01A8CFuZm5GGUAuIwKi72wF3ABF+YyygBwGRUWc2Eu4AIuzGWUAeAyKizmwlzABVyYyygDwGVUWMyFuYALuDCXUQaAy6iwmAtzARdwfWXMdeuzT+TGxz3Sfb1LunrapL07IW3pePDQ5/qavqef0c+OdYAELuAac4jGGkLL9rdvfyo9N9ODQAqBGmmrwGlb/R0u3xG4gMspOC5hG882CoRaaCSA8n1ff9doIQMu4PIOrus3u+8ZVNnw6e/Od5AALuDKOyz5hmqiPnfnzi1J9bSbgRWCpvvQfY307wQu4BoxJCOFaDK8rwsQmQsUIQhWW93XSIsewAVckYdLQ24F0Ui/926AARdwRRounZ6Np7GyYdN9DzdFBC7gijRc43GMlQ1U9s/6HXJNjYELuHI<<-----Removed----->>>>", - "contentType": "image/png" - } - ] -} -``` - -#### Response - -```http -HTTP/1.1 200 OK - -{ - "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels('channel-id')/messages/$entity", - "id": "id-value", - "replyToId": null, - "etag": "id-value", - "messageType": "message", - "createdDateTime": "2019-02-04T19:58:15.511Z", - "lastModifiedDateTime": null, - "deleted": false, - "subject": null, - "summary": null, - "importance": "normal", - "locale": "en-us", - "policyViolation": null, - "from": { - "application": null, - "device": null, - "conversation": null, - "user": { - "id": "id-value", - "displayName": "Joh Doe", - "userIdentityType": "aadUser" - } - }, - "body": { - "contentType": "html", - "content": "
\n
\n\n
\n\n\n
\n
" - }, - "attachments": [], - "mentions": [], - "reactions": [] -} -``` - -> [!div class="nextstepaction"] -> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+3%3A+Import+messages&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-3-import-messages&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - -## Step 4: Complete migration mode - -After the message migration process has completed, both the team and channel are taken out of migration mode using the `completeMigration` method. This step opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team completes, all channels must be completed out of migration mode. - -#### Request (end channel migration mode) - -```http -POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/completeMigration -``` - -#### Response - -```http -HTTP/1.1 204 NoContent -``` - -#### Request (end team migration mode) - -```http -POST https://graph.microsoft.com/v1.0/teams/team-id/completeMigration -``` - -#### Response - -```http -HTTP/1.1 204 NoContent -``` - -Action called on a `team` or `channel` that isn't in `migrationMode`. - -> [!div class="nextstepaction"] -> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+4%3A+Complete+migration+mode&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-4-complete-migration-mode&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - -## Step five: Add team members - -You can add a member to a team [using the Teams UI](https://support.microsoft.com/office/add-members-to-a-team-in-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9) or Microsoft Graph [add member](/graph/api/group-post-members?view=graph-rest-beta&tabs=http&preserve-view=true) API: - -#### Request (add member) - -```http -POST https://graph.microsoft.com/beta/teams/{team-id}/members -Content-type: application/json -Content-length: 30 - -{ - "@odata.type": "#microsoft.graph.aadUserConversationMember", - "roles": [], - "user@odata.bind": "https://graph.microsoft.com/beta/users/{user-id}" -} -``` - -#### Response - -```http -HTTP/1.1 204 No Content -``` - -> [!div class="nextstepaction"] -> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+5%3A+Add+team+members&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-five-add-team-members&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - -## Tips and additional information - - - - -* After the `completeMigration` request is made, you can't import further messages into the team. - -* You can only add team members to the new team after the `completeMigration` request has returned a successful response. - -* Throttling: Messages import at five RPS per channel. - -* If you need to make a correction to the migration results, you must delete the team, repeat the steps to create the team and channel and re-migrate the messages. - -> [!NOTE] -> Inline images are the only type of media supported by the import message API schema. - -##### Import content scope - -The following table provides the content scope: - -|In-scope | Out-of-scope| -|----------|--------------------------| -|Team and channel messages|1:1 and group chat messages| -|Created time of the original message|Private channels| -|Inline images as part of the message|At mentions| -|Links to existing files in SPO or OneDrive|Reactions| -|Messages with rich text|Videos| -|Message reply chain|Announcements| -|High throughput processing|Code snippets| -||Stickers| -||Emojis| -||Quotes| -||Cross posts between channels| -||Shared channels| - -## See also - -* [Microsoft Graph and Teams integration](/graph/teams-concept-overview) -* [Export content with the Microsoft Teams Export APIs](/microsoftteams/export-teams-content) -* [Microsoft Teams service limits](/graph/throttling-limits#microsoft-teams-service-limits) -* [Licensing and payment requirements for the Microsoft Teams API](/graph/teams-licenses) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md index e1fa11847a8..6e97b8b93d9 100644 --- a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md @@ -1,6 +1,6 @@ --- title: Import external platform messages to Teams with Microsoft Graphs -description: Learn how to use Microsoft Graph to import historical messages and data from all third-party platforms to Teams. +description: Learn how to use Microsoft Graph to import messages such as message history and data from any third-party platform to Teams. ms.localizationpriority: high author: "surbhigupta" ms.topic: overview @@ -32,6 +32,23 @@ Use Microsoft Graph to import users' existing message history and data from any |**Channels** | Standard, Private, Shared | New and existing | Channels must be created or already in migration mode | |**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | +## Content scope for import + +The following table provides the content scope. + +|In-scope | Out-of-scope| +|----------|--------------------------| +|Team and channel messages|At mentions| +|Created time of the original message|Announcements| +|Inline images as part of the message|Videos| +|Links to existing files in SPO or OneDrive|Code snippets| +|Messages with rich text|Sticker| +|Message reply chain|Quotes| +|High throughput processing|Cross posts between channels| +|1:1 and group chat messages|| +|Shared and private channels|| +|Reactions and emojis|| + ## Prerequisites Before you set up your Microsoft 365 tenant: @@ -288,23 +305,6 @@ HTTP/1.1 200 OK } ``` -### Content scope for import - -The following table provides the content scope. - -|In-scope | Out-of-scope| -|----------|--------------------------| -|Team and channel messages|At mentions| -|Created time of the original message|Announcements| -|Inline images as part of the message|Videos| -|Links to existing files in SPO or OneDrive|Code snippets| -|Messages with rich text|Sticker| -|Message reply chain|Quotes| -|High throughput processing|Cross posts between channels| -|1:1 and group chat messages|| -|Shared and private channels|| -|Reactions and emojis|| - ### Step 5: Complete migration Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. @@ -342,3 +342,26 @@ Call the `Get channel` or the `Get chat` API, to verify that the migration mode * [Export content with the Microsoft Teams Export APIs](/microsoftteams/export-teams-content) * [Microsoft Teams service limits](/graph/throttling-limits#microsoft-teams-service-limits) * [Licensing and payment requirements for the Microsoft Teams API](/graph/teams-licenses) + +## Tips and additional information + + + + +* After the `completeMigration` request is made, you can't import further messages into the team. + +* You can only add team members to the new team after the `completeMigration` request has returned a successful response. + +* Throttling: Messages import at five RPS per channel. + +* If you need to make a correction to the migration results, you must delete the team, repeat the steps to create the team and channel and re-migrate the messages. + +> [!NOTE] +> Inline images are the only type of media supported by the import message API schema. + +## See also + +* [Microsoft Graph and Teams integration](/graph/teams-concept-overview) +* [Export content with the Microsoft Teams Export APIs](/microsoftteams/export-teams-content) +* [Microsoft Teams service limits](/graph/throttling-limits#microsoft-teams-service-limits) +* [Licensing and payment requirements for the Microsoft Teams API](/graph/teams-licenses) From 326326b674cf54b5c5a0eaaa6553982da28fe2d2 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 13 Nov 2025 11:30:45 +0530 Subject: [PATCH 44/72] file renamed --- ...-messages-to-teams.md => import-external-messages-to-teams.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename msteams-platform/graph-api/import-messages/{import-external-platform-messages-to-teams.md => import-external-messages-to-teams.md} (100%) diff --git a/msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md similarity index 100% rename from msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md rename to msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md From 4f6c180c83f24e6b9f656e5d1848629220234fc1 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 13 Nov 2025 12:20:25 +0530 Subject: [PATCH 45/72] removed the tunnel --- .../import-external-messages-to-teams.md | 35 ++++++++----------- 1 file changed, 15 insertions(+), 20 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 6e97b8b93d9..c41440ebcba 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -73,17 +73,12 @@ You can create a new channel or chat, or use an existing one, to migrate user's ### Step 2: Enable migration mode to import messages -Use the `startMigration` API to enable migration mode on Teams channels or chats, and allow import of historical messages. Migration mode is a special state that prevents certain operations, like sending messages and adding members, during the data migration process. +Use the `startMigration` API to enable migration mode on Teams channels or chats, and allow import of historical messages. Migration mode is a special state that prevents certain operations, like sending messages and adding members, during the data migration process. For more information, see: -Consider the following points: +* [Channel migration](#channel-migration) +* [Chat migration](#chat-migration) -* Define a minimum timestamp for messages to migrate. The provided timestamp must be older than the channel or chat’s current `createdDateTime`. This timestamp replaces the existing `createdDateTime` of the channel. -* The`creationDateTime`property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. -* The `startMigration` API starts the message migration process by setting the migration mode to `inProgress` for a specified channel or chat. - -To enable channel and chat migration in Teams, see the following: - -### [Channel migration](#tab/channelmigration) +### Channel migration #### Request @@ -117,7 +112,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ``` -### [Chat migration](#tab/chatmigration) +### Chat migration #### Request @@ -152,7 +147,11 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ``` ---- +Consider the following important points: + +* Define a minimum timestamp for messages to migrate. The provided timestamp must be older than the channel or chat’s current `createdDateTime`. This timestamp replaces the existing `createdDateTime` of the channel. +* The`creationDateTime`property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. +* The `startMigration` API starts the message migration process by setting the migration mode to `inProgress` for a specified channel or chat. ### Step 3: Check migration status @@ -307,7 +306,10 @@ HTTP/1.1 200 OK ### Step 5: Complete migration -Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. +Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. For more information, see: + +* [Complete channel migration](#complete-channel-migration) +* [Complete chat migration](#complete-chat-migration) #### Complete channel migration @@ -336,13 +338,6 @@ POST /chats/{chat-id}/completeMigration Call the `Get channel` or the `Get chat` API, to verify that the migration mode state is marked as completed. For more information, see [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or [Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true). -## See also - -* [Microsoft Graph and Teams integration](/graph/teams-concept-overview) -* [Export content with the Microsoft Teams Export APIs](/microsoftteams/export-teams-content) -* [Microsoft Teams service limits](/graph/throttling-limits#microsoft-teams-service-limits) -* [Licensing and payment requirements for the Microsoft Teams API](/graph/teams-licenses) - ## Tips and additional information @@ -350,7 +345,7 @@ Call the `Get channel` or the `Get chat` API, to verify that the migration mode * After the `completeMigration` request is made, you can't import further messages into the team. -* You can only add team members to the new team after the `completeMigration` request has returned a successful response. +* You can only add team members to the new team after the `completeMigration` request returns a successful response. * Throttling: Messages import at five RPS per channel. From 45c1dbd644ac57cabbd3293c619e18c8f6d76309 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 13 Nov 2025 12:41:45 +0530 Subject: [PATCH 46/72] added overview for channel and chat --- .../import-messages/import-external-messages-to-teams.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index c41440ebcba..c55fb2ff8e1 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -8,7 +8,7 @@ ms.owner: mehakagarwal ms.date: 11/10/2025 --- -# Use Microsoft Graph APIs to import external messages into Teams +# Import external messages into Teams with Microsoft Graph APIs Use Microsoft Graph to import users' existing message history and data from any third-party platform into Teams. Users can continue their conversations seamlessly without interruption, as their messaging hierarchy from the third-party platform is recreated directly within Teams. @@ -73,13 +73,15 @@ You can create a new channel or chat, or use an existing one, to migrate user's ### Step 2: Enable migration mode to import messages -Use the `startMigration` API to enable migration mode on Teams channels or chats, and allow import of historical messages. Migration mode is a special state that prevents certain operations, like sending messages and adding members, during the data migration process. For more information, see: +The `startMigration` API to enables migration mode on Teams channels or chats, and allows import of historical messages. Migration mode is a special state that prevents certain operations, like sending messages and adding members, during the data migration process. For more information, see: * [Channel migration](#channel-migration) * [Chat migration](#chat-migration) ### Channel migration +Use the `startMigration` API to enable migration mode on new or existing channels. This API sets the channel’s migration state to `inProgress` and begins the message import process. + #### Request ```HTTP @@ -114,6 +116,8 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ### Chat migration +Use the `startMigration` API to enable migration mode on new or existing chats. This API sets the chat’s migration state to `inProgress` and begins the message import process. + #### Request ```HTTP From 10305fbee5d13eee3de8fc5cd94d7991fb3f9475 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Fri, 14 Nov 2025 18:58:21 +0530 Subject: [PATCH 47/72] explained new and existing chats and channels --- .../import-external-messages-to-teams.md | 92 +++++++++++-------- 1 file changed, 55 insertions(+), 37 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index c55fb2ff8e1..df3486234c8 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -1,5 +1,5 @@ --- -title: Import external platform messages to Teams with Microsoft Graphs +title: Import external platform messages to Teams with Microsoft Graph description: Learn how to use Microsoft Graph to import messages such as message history and data from any third-party platform to Teams. ms.localizationpriority: high author: "surbhigupta" @@ -19,7 +19,7 @@ Use Microsoft Graph to import users' existing message history and data from any |ScopeName|DisplayName|Type|APIs covered| |---------|---------|---------|---------| -| `Teamwork.Migrate.All`| Manage migration to Microsoft Teams | Application-only|`POST/teams`| +| `Teamwork.Migrate.All`| Manage migration to Teams | Application-only|`POST/teams`| > [!NOTE] > Delegated authentication isn't supported. @@ -27,6 +27,12 @@ Use Microsoft Graph to import users' existing message history and data from any ## Supported channel and chat types +Migration mode supports all new and existing channels and chats. Here's how you can understand and use: + +* **New channels or chats**: You can create a new team and its standard channels in migration mode to import content. + +* **Existing channels or chats** : You can use any team or channel that already exists in Teams, regardless of when it was created. + |Entities |Sub type |Migration mode support |Notes| |---------|---------|---------|---------| |**Channels** | Standard, Private, Shared | New and existing | Channels must be created or already in migration mode | @@ -41,7 +47,7 @@ The following table provides the content scope. |Team and channel messages|At mentions| |Created time of the original message|Announcements| |Inline images as part of the message|Videos| -|Links to existing files in SPO or OneDrive|Code snippets| +|Links to existing files in SPO or Microsoft OneDrive (OD)|Code snippets| |Messages with rich text|Sticker| |Message reply chain|Quotes| |High throughput processing|Cross posts between channels| @@ -53,12 +59,12 @@ The following table provides the content scope. Before you set up your Microsoft 365 tenant: -* Verify that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). +* Verify that a M365 tenant exists for the import data. For more information on setting up a M365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). * Verify that team members are in Microsoft Entra ID. For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Microsoft Entra ID. ## Import historical messages into Teams -You can import historical messages seamlessly, in both the existing and newly created channels or chats by performing the following steps: +You can import historical messages seamlessly into both existing and newly created channels or chats by performing the following steps: 1. [Create a new channel or chat or use an existing one](#step-1-create-a-new-channel-or-chat-or-use-an-existing-one) 1. [Enable migration mode to import messages](#step-2-enable-migration-mode-to-import-messages) @@ -69,11 +75,25 @@ You can import historical messages seamlessly, in both the existing and newly cr ### Step 1: Create a new channel or chat or use an existing one -You can create a new channel or chat, or use an existing one, to migrate user's message history from any third-party platform to Teams. +You can create a new channel or chat, or use an existing one, to migrate a user's message history from any third-party platform to Teams. + +**When to use new vs. existing channels:** + +* **New channels**: Create when you want to establish a fresh space specifically for migrated content. This option is ideal for recreating the exact structure from your external platform. +* **Existing channels**: Use when you want to add historical context to channels that are already active in Teams. This approach maintains continuity for ongoing conversations. ### Step 2: Enable migration mode to import messages -The `startMigration` API to enables migration mode on Teams channels or chats, and allows import of historical messages. Migration mode is a special state that prevents certain operations, like sending messages and adding members, during the data migration process. For more information, see: +The `startMigration` API enables migration mode on Teams channels or chats, which allows import of historical messages. Migration mode is a special state that prevents certain operations during the data migration process to ensure data integrity. + +**What migration mode does:** + +* Temporarily restricts sending new messages to the channel or chat +* Prevents adding or removing members during migration +* Allows importing historical messages with custom timestamps +* Maintains the original conversation structure and hierarchy + +For more information, see: * [Channel migration](#channel-migration) * [Chat migration](#chat-migration) @@ -85,18 +105,17 @@ Use the `startMigration` API to enable migration mode on new or existing channel #### Request ```HTTP -POST /teams/{team-id}/channels/{channel-id}/startMigration +POST /teams/{team-id}/channels/{channel-id}/startMigration { - -"conversationCreationDateTime": "2024-01-01T00:00:00Z" + "conversationCreationDateTime": "2024-01-01T00:00:00Z" } ``` > [!TIP] > Microsoft Graph uses DateTimeOffset to represent date and time with a UTC offset for an accurate time zone. ->The `conversationCreationDateTime` must be greater than the minimum value for `DateTimeOffset` and less than the current value of the channel's `createdDateTime`. +>The `conversationCreationDateTime` value must be greater than the minimum value for `DateTimeOffset` and less than the current value of the channel's `createdDateTime`. -#### Response +#### Channel migration response If the request is successful, the method returns an empty status. @@ -104,7 +123,7 @@ If the request is successful, the method returns an empty status. HTTP/1.1 204 No Content ``` -**Example** +##### Channel migration example ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration @@ -116,15 +135,14 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ### Chat migration -Use the `startMigration` API to enable migration mode on new or existing chats. This API sets the chat’s migration state to `inProgress` and begins the message import process. +Use the `startMigration` API to enable migration mode on new or existing chats. This API sets the chat's migration state to `inProgress` and begins the message import process. -#### Request +#### Chat migration request ```HTTP -POST /chats/{chat-id}/startMigration +POST /chats/{chat-id}/startMigration { - -"conversationCreationDateTime": "2024-01-01T00:00:00Z" + "conversationCreationDateTime": "2024-01-01T00:00:00Z" } ``` @@ -140,7 +158,7 @@ If the request is successful, the method returns an empty status: HTTP/1.1 204 No Content ``` -**Example** +##### Chat migration example ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration @@ -153,8 +171,8 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 Consider the following important points: -* Define a minimum timestamp for messages to migrate. The provided timestamp must be older than the channel or chat’s current `createdDateTime`. This timestamp replaces the existing `createdDateTime` of the channel. -* The`creationDateTime`property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. +* Define a minimum timestamp for messages to migrate. The provided timestamp must be older than the channel or chat's current `createdDateTime`. This timestamp replaces the existing `createdDateTime` of the channel. +* The `creationDateTime` property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. * The `startMigration` API starts the message migration process by setting the migration mode to `inProgress` for a specified channel or chat. ### Step 3: Check migration status @@ -170,9 +188,9 @@ Use the `POST` API to import back-in-time messages by including the `createdDate > [!NOTE] > -> * Messages imported with `createdDateTime` earlier than the message thread `createdDateTime` aren't supported. +> * The API doesn't support messages imported with `createdDateTime` earlier than the message thread `createdDateTime`. > * `createdDateTime` must be unique across messages in the same thread. -> * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has `createdDateTime` set to *2020-09-16T05:50:31.0025302Z*, it’s converted to *2020-09-16T05:50:31.002Z* when the message is ingested. +> * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has `createdDateTime` set to *2020-09-16T05:50:31.0025302Z*, the API converts it to *2020-09-16T05:50:31.002Z* when ingesting the message. #### Send a text-only message using POST @@ -184,7 +202,7 @@ POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages "from":{ "user":{ "id":"id-value", - "displayName":"Joh Doe", + "displayName":"John Doe", "userIdentityType":"aadUser" } }, @@ -195,7 +213,7 @@ POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages } ``` -#### Response +#### Send text message response ```http HTTP/1.1 200 OK @@ -243,13 +261,13 @@ HTTP/1.1 200 OK 400 Bad Request ``` -You can receive an error message if the`createdDateTime` property is set for the future. +You receive an error message if you set the `createdDateTime` property to a future date and time. #### Send a message with an inline image using POST > [!NOTE] > -> No other permission scopes are required. Use the standard `chatMessage` scopes. +> Use the standard `chatMessage` scopes. No other permission scopes are required. ```http POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages @@ -269,7 +287,7 @@ POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages } ``` -#### Response +#### Send inline image response ```http HTTP/1.1 200 OK @@ -294,7 +312,7 @@ HTTP/1.1 200 OK "conversation": null, "user": { "id": "id-value", - "displayName": "Joh Doe", + "displayName": "John Doe", "userIdentityType": "aadUser" } }, @@ -317,11 +335,11 @@ Use the `completeMigration` API to finish the migration process for both new and #### Complete channel migration -When a channel is created in migration mode for the initial import, use the `completeMigration` API to update its migration state to completed. This change ensures that the channel remains permanently available instead of being dropped after migration. +When you create a channel in migration mode for the initial import, use the `completeMigration` API to update its migration state to completed. This change ensures that the channel remains permanently available instead of being dropped after migration. For existing channels already in migration mode, use the `completeMigration` API to mark the migration state as completed. After you send a `completeMigration` request for new or existing channels, you can still import more messages by calling the `startMigration` API. -#### Request +#### Complete channel migration request ```HTTP POST /teams/{team-id}/channels/{channel-id}/completeMigration @@ -329,9 +347,9 @@ POST /teams/{team-id}/channels/{channel-id}/completeMigration #### Complete chat migration -For existing chats, which are already in migration mode, call the `completeMigration` API to update the migration mode state to completed. This process marks the chat as fully migrated. After calling `completeMigration` on a new or existing chat, you can continue importing messages by using the `startMigration` API. +For existing chats already in migration mode, call the `completeMigration` API to update the migration mode state to completed. This process marks the chat as fully migrated. After calling `completeMigration` on a new or existing chat, you can continue importing messages by using the `startMigration` API. -#### Request +#### Complete chat migration request ```HTTP POST /chats/{chat-id}/completeMigration @@ -339,7 +357,7 @@ POST /chats/{chat-id}/completeMigration ### Step 6: Verify migration mode completion -Call the `Get channel` or the `Get chat` API, to verify that the migration mode state is marked as completed. For more information, see [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or +Call the `Get channel` or the `Get chat` API to verify that the migration mode state is marked as completed. For more information, see [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or [Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true). ## Tips and additional information @@ -347,13 +365,13 @@ Call the `Get channel` or the `Get chat` API, to verify that the migration mode -* After the `completeMigration` request is made, you can't import further messages into the team. +* After you make the `completeMigration` request, you can't import more messages into the Teams. -* You can only add team members to the new team after the `completeMigration` request returns a successful response. +* You can only add team members to the new Teams after the `completeMigration` request returns a successful response. * Throttling: Messages import at five RPS per channel. -* If you need to make a correction to the migration results, you must delete the team, repeat the steps to create the team and channel and re-migrate the messages. +* If you need to correct the migration results, you must delete the Teams, repeat the steps to create the Teams and channel, and re-migrate the messages. > [!NOTE] > Inline images are the only type of media supported by the import message API schema. From e21aba73736884e6abdd989caeaa4018abed62f6 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Sun, 16 Nov 2025 15:21:29 +0530 Subject: [PATCH 48/72] added federated content --- .../import-external-messages-to-teams.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index df3486234c8..fd8328e08de 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -27,17 +27,20 @@ Use Microsoft Graph to import users' existing message history and data from any ## Supported channel and chat types -Migration mode supports all new and existing channels and chats. Here's how you can understand and use: +Migration mode supports all new and existing channels and chats. Here's how you can use it: * **New channels or chats**: You can create a new team and its standard channels in migration mode to import content. -* **Existing channels or chats** : You can use any team or channel that already exists in Teams, regardless of when it was created. +* **Existing channels or chats**: You can use any team or channel that already exists in Teams, regardless of when you created it. |Entities |Sub type |Migration mode support |Notes| |---------|---------|---------|---------| |**Channels** | Standard, Private, Shared | New and existing | Channels must be created or already in migration mode | |**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | +> [!NOTE] +> Federated content can't be imported for chats, channels, or messages. Only one app can manage a thread, and all imported content must come from the authenticated tenant. If another app needs to import content, the first app must complete migration before the second app restarts the process. + ## Content scope for import The following table provides the content scope. @@ -57,10 +60,10 @@ The following table provides the content scope. ## Prerequisites -Before you set up your Microsoft 365 tenant: +Before you set up your Microsoft 365 (M365) tenant: * Verify that a M365 tenant exists for the import data. For more information on setting up a M365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). -* Verify that team members are in Microsoft Entra ID. For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Microsoft Entra ID. +* Verify that team members are in Microsoft Entra ID (Entra ID). For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Entra ID. ## Import historical messages into Teams From 397cb61d96091e3260b77371db3e486c14bc6304 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Sun, 16 Nov 2025 18:51:01 +0530 Subject: [PATCH 49/72] added two paths --- .../import-external-messages-to-teams.md | 39 ++++++++++++------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index fd8328e08de..dc88eaf0736 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -29,9 +29,9 @@ Use Microsoft Graph to import users' existing message history and data from any Migration mode supports all new and existing channels and chats. Here's how you can use it: -* **New channels or chats**: You can create a new team and its standard channels in migration mode to import content. +* **New channels or chats**: You can create a new team and its standard channels in migration mode to import content. This option is ideal for recreating the exact structure from your external platform. -* **Existing channels or chats**: You can use any team or channel that already exists in Teams, regardless of when you created it. +* **Existing channels or chats**: You can use any team or channel that already exists in Teams, regardless of when you created it. This option adds historical context to channels that are already active in Teams and maintains continuity for ongoing conversations. |Entities |Sub type |Migration mode support |Notes| |---------|---------|---------|---------| @@ -39,7 +39,10 @@ Migration mode supports all new and existing channels and chats. Here's how you |**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | > [!NOTE] -> Federated content can't be imported for chats, channels, or messages. Only one app can manage a thread, and all imported content must come from the authenticated tenant. If another app needs to import content, the first app must complete migration before the second app restarts the process. +> +> * Only standard channels are supported when creating a channel in migration mode from scratch +> +> * Federated content can't be imported for chats, channels, or messages. Only one app can manage a thread, and all imported content must come from the authenticated tenant. If another app needs to import content, the first app must complete migration before the second app restarts the process. ## Content scope for import @@ -60,10 +63,10 @@ The following table provides the content scope. ## Prerequisites -Before you set up your Microsoft 365 (M365) tenant: +Before you set up your Microsoft 365 tenant: -* Verify that a M365 tenant exists for the import data. For more information on setting up a M365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). -* Verify that team members are in Microsoft Entra ID (Entra ID). For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Entra ID. +* Verify that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). +* Verify that team members are in Microsoft Entra ID. For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Microsoft Entra ID. ## Import historical messages into Teams @@ -80,11 +83,6 @@ You can import historical messages seamlessly into both existing and newly creat You can create a new channel or chat, or use an existing one, to migrate a user's message history from any third-party platform to Teams. -**When to use new vs. existing channels:** - -* **New channels**: Create when you want to establish a fresh space specifically for migrated content. This option is ideal for recreating the exact structure from your external platform. -* **Existing channels**: Use when you want to add historical context to channels that are already active in Teams. This approach maintains continuity for ongoing conversations. - ### Step 2: Enable migration mode to import messages The `startMigration` API enables migration mode on Teams channels or chats, which allows import of historical messages. Migration mode is a special state that prevents certain operations during the data migration process to ensure data integrity. @@ -96,10 +94,21 @@ The `startMigration` API enables migration mode on Teams channels or chats, whic * Allows importing historical messages with custom timestamps * Maintains the original conversation structure and hierarchy -For more information, see: +Choose either of the two paths to initiate migration mode on channels or chats: + +* [Create a Team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode) +* Path 2: Start migration on existing channels and chats -* [Channel migration](#channel-migration) -* [Chat migration](#chat-migration) +### Create a Team and standard channel in migration mode + +To create a new team with a back-in-time timestamp: + +1. Use the team resource `createdDateTime` property to place the new team in migration mode. +1. Include the `teamCreationMode` instance attribute with the `migration` value in the POST request to identify the team as created for migration. +Since you're migrating existing data, maintaining the original message timestamps, and preventing messaging activity during the migration process are key to recreating the user's existing message flow in Teams. + +> [!NOTE] +> The `createdDateTime` field is only populated for migrated teams or channels. ### Channel migration @@ -191,7 +200,7 @@ Use the `POST` API to import back-in-time messages by including the `createdDate > [!NOTE] > -> * The API doesn't support messages imported with `createdDateTime` earlier than the message thread `createdDateTime`. +> * Messages imported with `createdDateTime` earlier than the message thread `createdDateTime` aren't supported. > * `createdDateTime` must be unique across messages in the same thread. > * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has `createdDateTime` set to *2020-09-16T05:50:31.0025302Z*, the API converts it to *2020-09-16T05:50:31.002Z* when ingesting the message. From 81c003c011283a97a4231a6e88d00cd1cb3c0685 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 17 Nov 2025 11:13:45 +0530 Subject: [PATCH 50/72] updated content for Path 1 --- .../import-external-messages-to-teams.md | 105 ++++++++++++++++-- 1 file changed, 95 insertions(+), 10 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index dc88eaf0736..144639757b2 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -29,9 +29,9 @@ Use Microsoft Graph to import users' existing message history and data from any Migration mode supports all new and existing channels and chats. Here's how you can use it: -* **New channels or chats**: You can create a new team and its standard channels in migration mode to import content. This option is ideal for recreating the exact structure from your external platform. +* **New channels or chats**: Create a new team and its standard channels in migration mode to import content. This option is ideal for recreating the exact structure from your external platform. -* **Existing channels or chats**: You can use any team or channel that already exists in Teams, regardless of when you created it. This option adds historical context to channels that are already active in Teams and maintains continuity for ongoing conversations. +* **Existing channels or chats**: Use any team or channel that already exists in Teams, regardless of when you created it. This option adds historical context to channels that are already active in Teams and maintains continuity for ongoing conversations. |Entities |Sub type |Migration mode support |Notes| |---------|---------|---------|---------| @@ -65,8 +65,8 @@ The following table provides the content scope. Before you set up your Microsoft 365 tenant: -* Verify that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). -* Verify that team members are in Microsoft Entra ID. For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Microsoft Entra ID. +* Verify that a Microsoft 365 (M365) tenant exists for the import data. For more information on setting up a M365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). +* Verify that team members are in Microsoft Entra ID (Entra ID). For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Entra ID. ## Import historical messages into Teams @@ -81,13 +81,16 @@ You can import historical messages seamlessly into both existing and newly creat ### Step 1: Create a new channel or chat or use an existing one -You can create a new channel or chat, or use an existing one, to migrate a user's message history from any third-party platform to Teams. +You can create a new channel or chat, or use an existing one, to migrate a user's message history from any third-party platform to Teams. For more information, see: + +* [Path 1: Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode) +* [Path 2: Start migration on existing channels and chats](#start-migration-on-existing-channels-and-chats) ### Step 2: Enable migration mode to import messages The `startMigration` API enables migration mode on Teams channels or chats, which allows import of historical messages. Migration mode is a special state that prevents certain operations during the data migration process to ensure data integrity. -**What migration mode does:** +The migration mode: * Temporarily restricts sending new messages to the channel or chat * Prevents adding or removing members during migration @@ -96,10 +99,12 @@ The `startMigration` API enables migration mode on Teams channels or chats, whic Choose either of the two paths to initiate migration mode on channels or chats: -* [Create a Team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode) -* Path 2: Start migration on existing channels and chats +* [Path 1: Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode) +* [Path 2: Start migration on existing channels and chats](#start-migration-on-existing-channels-and-chats) + +### Create a team and standard channel in migration mode -### Create a Team and standard channel in migration mode +To start migration mode, you need to create a new team in Teams and then create a channel. Currently, you can only create a standard channel. To create a new team with a back-in-time timestamp: @@ -110,6 +115,86 @@ Since you're migrating existing data, maintaining the original message timestamp > [!NOTE] > The `createdDateTime` field is only populated for migrated teams or channels. +#### Request (create a team in migration state) + +```HTTP +POST https://graph.microsoft.com/v1.0/teams +Content-Type: application/json + +{ + "@microsoft.graph.teamCreationMode": "migration", + "template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')", + "displayName": "My Sample Team", + "description": "My Sample Team’s Description", + "createdDateTime": "2020-03-14T11:22:17.043Z" +} +``` + +#### Response for new team creation + +```HTTP +HTTP/1.1 202 Accepted +Location: /teams/{team-id}/operations/{operation-id} +Content-Location: /teams/{team-id} +``` + +You can receive the error message in the following scenarios: + +If you set `createdDateTime` for a future date. +If you correctly specify `createdDateTime`, but you omit or set an invalid value for the `teamCreationMode` instance attribute. + +#### Error Message + +```HTTP +400 Bad Request +``` + +To create a new channel with a back-in-time timestamp: + +1. Use the channel resource `createdDateTime` property to place the new channel in migration mode. +1. Include the `channelCreationMode` instance attribute with the `migration` value in the POST request to identify the team as created for migration. + +#### Request (create a channel in migration state) + +```HTTP +POST https://graph.microsoft.com/v1.0/teams/{team-id}/channels +Content-Type: application/json + +{ + "@microsoft.graph.channelCreationMode": "migration", + "displayName": "Architecture Discussion", + "description": "This channel is where we debate all future architecture plans", + "membershipType": "standard", + "createdDateTime": "2020-03-14T11:22:17.047Z" +} +``` + +#### Response of new channel creation + +```HTTP +HTTP/1.1 202 Accepted + +{ + "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels/$entity", + "id":"id-value", + "createdDateTime":null, + "displayName":"Architecture Discussion", + "description":"This channel is where we debate all future architecture plans", + "isFavoriteByDefault":null, + "email":null, + "webUrl":null, + "membershipType":null, + "moderationSettings":null +} +``` + +You can receive the error message in the following scenarios: + +If you set `createdDateTime` for a future date. +If you correctly specify `createdDateTime`, but you omit or set an invalid value for the `channelCreationMode` instance attribute. + +### Start migration on existing channels and chats + ### Channel migration Use the `startMigration` API to enable migration mode on new or existing channels. This API sets the channel’s migration state to `inProgress` and begins the message import process. @@ -200,7 +285,7 @@ Use the `POST` API to import back-in-time messages by including the `createdDate > [!NOTE] > -> * Messages imported with `createdDateTime` earlier than the message thread `createdDateTime` aren't supported. +> * The API doesn't support messages imported with `createdDateTime` earlier than the message thread `createdDateTime`. > * `createdDateTime` must be unique across messages in the same thread. > * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has `createdDateTime` set to *2020-09-16T05:50:31.0025302Z*, the API converts it to *2020-09-16T05:50:31.002Z* when ingesting the message. From 8a22417952e31c47538a19ceb1b6a3200b5ed147 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 17 Nov 2025 12:25:15 +0530 Subject: [PATCH 51/72] updated steps as per new flow --- .../import-external-messages-to-teams.md | 62 +++++++++++-------- 1 file changed, 37 insertions(+), 25 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 144639757b2..885eda87093 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -40,32 +40,33 @@ Migration mode supports all new and existing channels and chats. Here's how you > [!NOTE] > -> * Only standard channels are supported when creating a channel in migration mode from scratch +> * Only standard channels are supported when creating a channel in migration mode from scratch. > -> * Federated content can't be imported for chats, channels, or messages. Only one app can manage a thread, and all imported content must come from the authenticated tenant. If another app needs to import content, the first app must complete migration before the second app restarts the process. +> * Federated content can't be imported for chats, channels, or messages. All imported content must come from the authenticated tenant and only one app can manage a thread. If another app needs to import content, the first app must complete migration before the second app restarts the process. ## Content scope for import -The following table provides the content scope. +The following table provides the content scope for existing channels and chats. |In-scope | Out-of-scope| |----------|--------------------------| -|Team and channel messages|At mentions| -|Created time of the original message|Announcements| -|Inline images as part of the message|Videos| -|Links to existing files in SPO or Microsoft OneDrive (OD)|Code snippets| -|Messages with rich text|Sticker| +|Team (general) and standard, private, and shared channel messages|Announcements| +|Created time of the original message|Videos| +|Inline images as part of the message|Code snippets| +|Links to existing files in Microsoft 365 (M365) SharePoint Oneline (SPO) or OneDrive (OD)|Stickers| +|Messages with rich text|Cross posts between channels| |Message reply chain|Quotes| -|High throughput processing|Cross posts between channels| +|High throughput processing|| |1:1 and group chat messages|| |Shared and private channels|| -|Reactions and emojis|| +|Up to 250 reactions|| +|At mentions and emojis|| ## Prerequisites Before you set up your Microsoft 365 tenant: -* Verify that a Microsoft 365 (M365) tenant exists for the import data. For more information on setting up a M365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). +* Verify that a M365 tenant exists for the import data. For more information on setting up a M365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). * Verify that team members are in Microsoft Entra ID (Entra ID). For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Entra ID. ## Import historical messages into Teams @@ -113,9 +114,9 @@ To create a new team with a back-in-time timestamp: Since you're migrating existing data, maintaining the original message timestamps, and preventing messaging activity during the migration process are key to recreating the user's existing message flow in Teams. > [!NOTE] -> The `createdDateTime` field is only populated for migrated teams or channels. +> The `createdDateTime` field is only populated for migrated teams or channels. If you update `createdDateTime` to a past timestamp, you can't move it to a future timestamp again. -#### Request (create a team in migration state) +#### Request for new team creation in migration state ```HTTP POST https://graph.microsoft.com/v1.0/teams @@ -140,10 +141,10 @@ Content-Location: /teams/{team-id} You can receive the error message in the following scenarios: -If you set `createdDateTime` for a future date. -If you correctly specify `createdDateTime`, but you omit or set an invalid value for the `teamCreationMode` instance attribute. +* If you set `createdDateTime` for a future date. +* If you correctly specify `createdDateTime`, but you omit or set an invalid value for the `teamCreationMode` instance attribute. -#### Error Message +#### Error message for team creation ```HTTP 400 Bad Request @@ -154,7 +155,7 @@ To create a new channel with a back-in-time timestamp: 1. Use the channel resource `createdDateTime` property to place the new channel in migration mode. 1. Include the `channelCreationMode` instance attribute with the `migration` value in the POST request to identify the team as created for migration. -#### Request (create a channel in migration state) +#### Request for new channel creation in migration state ```HTTP POST https://graph.microsoft.com/v1.0/teams/{team-id}/channels @@ -190,16 +191,27 @@ HTTP/1.1 202 Accepted You can receive the error message in the following scenarios: -If you set `createdDateTime` for a future date. -If you correctly specify `createdDateTime`, but you omit or set an invalid value for the `channelCreationMode` instance attribute. +* If you set `createdDateTime` for a future date. +* If you correctly specify `createdDateTime`, but you omit or set an invalid value for the `channelCreationMode` instance attribute. + +#### Error message for channel creation + +```HTTP +400 Bad Request +``` ### Start migration on existing channels and chats -### Channel migration +Use the `startMigration` API to enable migration mode on existing channels or chats. `startMigration` sets the channel’s or chat's migration state to `inProgress` and begins the message import process. For more information, see: + +* [Existing channel migration](#existing-channel-migration) +* [Existing chat migration](#existing-chat-migration) + +### Existing channel migration -Use the `startMigration` API to enable migration mode on new or existing channels. This API sets the channel’s migration state to `inProgress` and begins the message import process. +Learn how to enable migration mode on existing channels here including the request, response, and an example. -#### Request +#### Request for existing channel migration ```HTTP POST /teams/{team-id}/channels/{channel-id}/startMigration @@ -230,9 +242,9 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ``` -### Chat migration +### Existing chat migration -Use the `startMigration` API to enable migration mode on new or existing chats. This API sets the chat's migration state to `inProgress` and begins the message import process. +Learn how to enable migration mode on existing chats here including the request, response, and an example. #### Chat migration request @@ -247,7 +259,7 @@ POST /chats/{chat-id}/startMigration > Microsoft Graph uses DateTimeOffset to represent date and time with a UTC offset for an accurate time zone. >The `conversationCreationDateTime` must be greater than the minimum value for `DateTimeOffset` and less than the current value of the chat's `createdDateTime`. -#### Response +#### Chat migration response If the request is successful, the method returns an empty status: From ff088e966165b60ae7da062ff46abbd7481e7fbb Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 17 Nov 2025 14:54:48 +0530 Subject: [PATCH 52/72] channel migration completion --- .../import-external-messages-to-teams.md | 51 ++++++++++++++----- 1 file changed, 39 insertions(+), 12 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 885eda87093..6d06a521c1c 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -5,7 +5,7 @@ ms.localizationpriority: high author: "surbhigupta" ms.topic: overview ms.owner: mehakagarwal -ms.date: 11/10/2025 +ms.date: 11/17/2025 --- # Import external messages into Teams with Microsoft Graph APIs @@ -50,7 +50,7 @@ The following table provides the content scope for existing channels and chats. |In-scope | Out-of-scope| |----------|--------------------------| -|Team (general) and standard, private, and shared channel messages|Announcements| +|Team (general)|Announcements| |Created time of the original message|Videos| |Inline images as part of the message|Code snippets| |Links to existing files in Microsoft 365 (M365) SharePoint Oneline (SPO) or OneDrive (OD)|Stickers| @@ -58,7 +58,7 @@ The following table provides the content scope for existing channels and chats. |Message reply chain|Quotes| |High throughput processing|| |1:1 and group chat messages|| -|Shared and private channels|| +|Standard, private, and shared channel messages|| |Up to 250 reactions|| |At mentions and emojis|| @@ -209,7 +209,7 @@ Use the `startMigration` API to enable migration mode on existing channels or ch ### Existing channel migration -Learn how to enable migration mode on existing channels here including the request, response, and an example. +Learn how to enable migration mode on existing channels including the request, response, and an example. #### Request for existing channel migration @@ -244,7 +244,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ### Existing chat migration -Learn how to enable migration mode on existing chats here including the request, response, and an example. +Learn how to enable migration mode on existing chats, including the request, response, and an example. #### Chat migration request @@ -280,7 +280,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 Consider the following important points: -* Define a minimum timestamp for messages to migrate. The provided timestamp must be older than the channel or chat's current `createdDateTime`. This timestamp replaces the existing `createdDateTime` of the channel. +* Define a minimum timestamp for messages to migrate. The provided timestamp must be older than the channel or chat's current `createdDateTime`. This timestamp replaces the existing `createdDateTime` of the channel. If you update `createdDateTime` to a past timestamp, you can't move it to a future timestamp again. * The `creationDateTime` property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. * The `startMigration` API starts the message migration process by setting the migration mode to `inProgress` for a specified channel or chat. @@ -439,14 +439,41 @@ HTTP/1.1 200 OK Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. For more information, see: -* [Complete channel migration](#complete-channel-migration) -* [Complete chat migration](#complete-chat-migration) +* [Complete the new team and channel migration](#complete-the-new-team-and-channel-migration) +* [Complete existing channel migration](#complete-existing-channel-migration) +* [Complete existing chat migration](#complete-existing-chat-migration) -#### Complete channel migration +#### Complete the new team and channel migration -When you create a channel in migration mode for the initial import, use the `completeMigration` API to update its migration state to completed. This change ensures that the channel remains permanently available instead of being dropped after migration. +After the message migration process completes, use the `completeMigration` method to take both the team and channel out of migration mode. This step opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team completes, you must complete all channels out of migration mode. -For existing channels already in migration mode, use the `completeMigration` API to mark the migration state as completed. After you send a `completeMigration` request for new or existing channels, you can still import more messages by calling the `startMigration` API. +#### Request for channel migration mode end + +```http +POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/completeMigration +``` + +#### Response for channel migration mode end + +```http +HTTP/1.1 204 NoContent +``` + +#### Request for team migration mode end + +```http +POST https://graph.microsoft.com/v1.0/teams/team-id/completeMigration +``` + +#### Response for team migration mode end + +```http +HTTP/1.1 204 NoContent +``` + +#### Complete existing channel migration + +For existing channels already in migration mode, use the `completeMigration` API to mark the migration state as completed. This change ensures that the channel remains permanently available instead of being dropped after migration.After you send a `completeMigration` request for new or existing channels, you can still import more messages by calling the `startMigration` API. #### Complete channel migration request @@ -454,7 +481,7 @@ For existing channels already in migration mode, use the `completeMigration` API POST /teams/{team-id}/channels/{channel-id}/completeMigration ``` -#### Complete chat migration +#### Complete existing chat migration For existing chats already in migration mode, call the `completeMigration` API to update the migration mode state to completed. This process marks the chat as fully migrated. After calling `completeMigration` on a new or existing chat, you can continue importing messages by using the `startMigration` API. From 57595ade9a5ebefdb43a4bb85a3ec67ed94cd9b4 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 17 Nov 2025 19:00:39 +0530 Subject: [PATCH 53/72] internal review incorporated --- .../import-external-messages-to-teams.md | 80 +++++++++---------- 1 file changed, 39 insertions(+), 41 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 6d06a521c1c..046f7118d80 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -27,22 +27,26 @@ Use Microsoft Graph to import users' existing message history and data from any ## Supported channel and chat types -Migration mode supports all new and existing channels and chats. Here's how you can use it: +All channels and chats, either new or existing support migration mode for importing historical messages. Migration mode is a special state that prevents certain operations during the data migration process to ensure data integrity. -* **New channels or chats**: Create a new team and its standard channels in migration mode to import content. This option is ideal for recreating the exact structure from your external platform. +The migration mode: -* **Existing channels or chats**: Use any team or channel that already exists in Teams, regardless of when you created it. This option adds historical context to channels that are already active in Teams and maintains continuity for ongoing conversations. +* Temporarily restricts sending new messages to the channel or chat +* Prevents adding or removing members during migration +* Allows importing historical messages with custom timestamps +* Maintains the original conversation structure and hierarchy -|Entities |Sub type |Migration mode support |Notes| -|---------|---------|---------|---------| -|**Channels** | Standard, Private, Shared | New and existing | Channels must be created or already in migration mode | -|**Chats** | Group, 1:1 | New and existing | Meeting chats not supported; external members supported | +Here's how you can enable migration of historical messages: + +* **New channels or chats**: Create a new team and its standard channels in migration mode to import content. This approach allows you to recreate the exact structure from your external platform. + +* **Existing channels or chats**: Use any team or channel that already exists in Teams, regardless of when you created it. This approach allows you to add historical context to channels that are already active in Teams and maintains continuity for ongoing conversations. > [!NOTE] > > * Only standard channels are supported when creating a channel in migration mode from scratch. > -> * Federated content can't be imported for chats, channels, or messages. All imported content must come from the authenticated tenant and only one app can manage a thread. If another app needs to import content, the first app must complete migration before the second app restarts the process. +> * Federated content can’t be imported. All imported content must come from the authenticated tenant and only one app can manage a thread at a time. Another app can import content only after the first app completes migration. ## Content scope for import @@ -60,7 +64,7 @@ The following table provides the content scope for existing channels and chats. |1:1 and group chat messages|| |Standard, private, and shared channel messages|| |Up to 250 reactions|| -|At mentions and emojis|| +|@mentions and emojis|| ## Prerequisites @@ -71,34 +75,17 @@ Before you set up your Microsoft 365 tenant: ## Import historical messages into Teams -You can import historical messages seamlessly into both existing and newly created channels or chats by performing the following steps: +You can import historical messages seamlessly into both existing and newly created channels or chats by performing the following five steps: 1. [Create a new channel or chat or use an existing one](#step-1-create-a-new-channel-or-chat-or-use-an-existing-one) -1. [Enable migration mode to import messages](#step-2-enable-migration-mode-to-import-messages) -1. [Check migration status](#step-3-check-migration-status) -1. [Import messages](#step-4-import-messages) -1. [Complete migration](#step-5-complete-migration) -1. [Verify migration mode completion](#step-6-verify-migration-mode-completion) +1. [Check migration status](#step-2-check-migration-status) +1. [Import messages](#step-3-import-messages) +1. [Complete migration](#step-4-complete-migration) +1. [Verify migration mode completion](#step-5-verify-migration-mode-completion) ### Step 1: Create a new channel or chat or use an existing one -You can create a new channel or chat, or use an existing one, to migrate a user's message history from any third-party platform to Teams. For more information, see: - -* [Path 1: Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode) -* [Path 2: Start migration on existing channels and chats](#start-migration-on-existing-channels-and-chats) - -### Step 2: Enable migration mode to import messages - -The `startMigration` API enables migration mode on Teams channels or chats, which allows import of historical messages. Migration mode is a special state that prevents certain operations during the data migration process to ensure data integrity. - -The migration mode: - -* Temporarily restricts sending new messages to the channel or chat -* Prevents adding or removing members during migration -* Allows importing historical messages with custom timestamps -* Maintains the original conversation structure and hierarchy - -Choose either of the two paths to initiate migration mode on channels or chats: +You can create a new channel or chat or use an existing one to import a user's message history from any third-party platform to Teams. For more information, see: * [Path 1: Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode) * [Path 2: Start migration on existing channels and chats](#start-migration-on-existing-channels-and-chats) @@ -144,7 +131,7 @@ You can receive the error message in the following scenarios: * If you set `createdDateTime` for a future date. * If you correctly specify `createdDateTime`, but you omit or set an invalid value for the `teamCreationMode` instance attribute. -#### Error message for team creation +#### Error message for new team creation ```HTTP 400 Bad Request @@ -200,6 +187,13 @@ You can receive the error message in the following scenarios: 400 Bad Request ``` +After you create a new team and channel, perform the following steps: + +1. [Check migration status](#step-2-check-migration-status) +1. [Import messages](#step-3-import-messages) +1. [Complete migration](#step-4-complete-migration) +1. [Verify migration mode completion](#step-5-verify-migration-mode-completion) + ### Start migration on existing channels and chats Use the `startMigration` API to enable migration mode on existing channels or chats. `startMigration` sets the channel’s or chat's migration state to `inProgress` and begins the message import process. For more information, see: @@ -284,14 +278,14 @@ Consider the following important points: * The `creationDateTime` property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. * The `startMigration` API starts the message migration process by setting the migration mode to `inProgress` for a specified channel or chat. -### Step 3: Check migration status +### Step 2: Check migration status Call the `Get channel` or `Get chat` API to confirm that the migration mode state is set to `inProgress`. For more information, see: * [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) * [Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) -### Step 4: Import messages +### Step 3: Import messages Use the `POST` API to import back-in-time messages by including the `createdDateTime` and `from` properties in the request body. @@ -435,7 +429,7 @@ HTTP/1.1 200 OK } ``` -### Step 5: Complete migration +### Step 4: Complete migration Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. For more information, see: @@ -447,30 +441,32 @@ Use the `completeMigration` API to finish the migration process for both new and After the message migration process completes, use the `completeMigration` method to take both the team and channel out of migration mode. This step opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team completes, you must complete all channels out of migration mode. -#### Request for channel migration mode end +#### Request for end of channel migration mode ```http POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/completeMigration ``` -#### Response for channel migration mode end +#### Response for end of channel migration mode ```http HTTP/1.1 204 NoContent ``` -#### Request for team migration mode end +#### Request for end of team migration mode ```http POST https://graph.microsoft.com/v1.0/teams/team-id/completeMigration ``` -#### Response for team migration mode end +#### Response for end of team migration mode ```http HTTP/1.1 204 NoContent ``` +Go to [Step 5: Verify migration mode completion](#step-5-verify-migration-mode-completion). + #### Complete existing channel migration For existing channels already in migration mode, use the `completeMigration` API to mark the migration state as completed. This change ensures that the channel remains permanently available instead of being dropped after migration.After you send a `completeMigration` request for new or existing channels, you can still import more messages by calling the `startMigration` API. @@ -481,6 +477,8 @@ For existing channels already in migration mode, use the `completeMigration` API POST /teams/{team-id}/channels/{channel-id}/completeMigration ``` +Go to [Step 5: Verify migration mode completion](#step-5-verify-migration-mode-completion), after you complete the existing channel migration. + #### Complete existing chat migration For existing chats already in migration mode, call the `completeMigration` API to update the migration mode state to completed. This process marks the chat as fully migrated. After calling `completeMigration` on a new or existing chat, you can continue importing messages by using the `startMigration` API. @@ -491,7 +489,7 @@ For existing chats already in migration mode, call the `completeMigration` API t POST /chats/{chat-id}/completeMigration ``` -### Step 6: Verify migration mode completion +### Step 5: Verify migration mode completion Call the `Get channel` or the `Get chat` API to verify that the migration mode state is marked as completed. For more information, see [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or [Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true). From aada80cc3b558b308f45aa5018a2bcb0cdbe8716 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Mon, 17 Nov 2025 19:45:54 +0530 Subject: [PATCH 54/72] part 2 changes --- .../import-external-messages-to-teams.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 046f7118d80..069b061d3a0 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -27,7 +27,7 @@ Use Microsoft Graph to import users' existing message history and data from any ## Supported channel and chat types -All channels and chats, either new or existing support migration mode for importing historical messages. Migration mode is a special state that prevents certain operations during the data migration process to ensure data integrity. +All channels and chats, either new or existing, support migration mode for importing historical messages. Migration mode is a special state that prevents certain operations during the data migration process to ensure data integrity. The migration mode: @@ -46,7 +46,7 @@ Here's how you can enable migration of historical messages: > > * Only standard channels are supported when creating a channel in migration mode from scratch. > -> * Federated content can’t be imported. All imported content must come from the authenticated tenant and only one app can manage a thread at a time. Another app can import content only after the first app completes migration. +> * Federated content can't be imported. All imported content must come from the authenticated tenant and only one app can manage a thread at a time. Another app can import content only after the first app completes migration. ## Content scope for import @@ -57,7 +57,7 @@ The following table provides the content scope for existing channels and chats. |Team (general)|Announcements| |Created time of the original message|Videos| |Inline images as part of the message|Code snippets| -|Links to existing files in Microsoft 365 (M365) SharePoint Oneline (SPO) or OneDrive (OD)|Stickers| +|Links to existing files in Microsoft 365 (Microsoft 365) SharePoint Online (SPO) or OneDrive (OD)|Stickers| |Messages with rich text|Cross posts between channels| |Message reply chain|Quotes| |High throughput processing|| @@ -70,7 +70,7 @@ The following table provides the content scope for existing channels and chats. Before you set up your Microsoft 365 tenant: -* Verify that a M365 tenant exists for the import data. For more information on setting up a M365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). +* Verify that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). * Verify that team members are in Microsoft Entra ID (Entra ID). For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Entra ID. ## Import historical messages into Teams @@ -140,7 +140,7 @@ You can receive the error message in the following scenarios: To create a new channel with a back-in-time timestamp: 1. Use the channel resource `createdDateTime` property to place the new channel in migration mode. -1. Include the `channelCreationMode` instance attribute with the `migration` value in the POST request to identify the team as created for migration. +1. Include the `channelCreationMode` instance attribute with the `migration` value in the POST request to identify the team created for migration. #### Request for new channel creation in migration state @@ -220,7 +220,7 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration #### Channel migration response -If the request is successful, the method returns an empty status. +If the request is successful, the method returns an empty HTTP response. ```http HTTP/1.1 204 No Content @@ -255,7 +255,7 @@ POST /chats/{chat-id}/startMigration #### Chat migration response -If the request is successful, the method returns an empty status: +If the request is successful, the method returns an empty HTTP response. ```http HTTP/1.1 204 No Content @@ -469,7 +469,7 @@ Go to [Step 5: Verify migration mode completion](#step-5-verify-migration-mode-c #### Complete existing channel migration -For existing channels already in migration mode, use the `completeMigration` API to mark the migration state as completed. This change ensures that the channel remains permanently available instead of being dropped after migration.After you send a `completeMigration` request for new or existing channels, you can still import more messages by calling the `startMigration` API. +For existing channels already in migration mode, use the `completeMigration` API to mark the migration state as completed. This change ensures that the channel remains permanently available instead of being dropped after migration. After you send a `completeMigration` request for new or existing channels, you can still import more messages by calling the `startMigration` API. #### Complete channel migration request From 79fb8bab372350e892b8a6d1b1a8b8c33492aabf Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Tue, 18 Nov 2025 05:40:28 +0530 Subject: [PATCH 55/72] internal review comments addressed-part 1 --- .../import-external-messages-to-teams.md | 67 +++++++++---------- 1 file changed, 33 insertions(+), 34 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 069b061d3a0..7d623898a19 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -1,5 +1,5 @@ --- -title: Import external platform messages to Teams with Microsoft Graph +title: Import third-party platform messages to Teams using Microsoft Graph description: Learn how to use Microsoft Graph to import messages such as message history and data from any third-party platform to Teams. ms.localizationpriority: high author: "surbhigupta" @@ -8,18 +8,18 @@ ms.owner: mehakagarwal ms.date: 11/17/2025 --- -# Import external messages into Teams with Microsoft Graph APIs +# Import third-party platform messages to Teams using Microsoft Graph -Use Microsoft Graph to import users' existing message history and data from any third-party platform into Teams. Users can continue their conversations seamlessly without interruption, as their messaging hierarchy from the third-party platform is recreated directly within Teams. +With Microsoft Graph, you can migrate users' existing message history and data from an external system into a Teams channel. By enabling the recreation of a third-party platform messaging hierarchy inside Teams, users can continue their communications in a seamless manner and proceed without interruption. > [!NOTE] > In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. ## Permissions -|ScopeName|DisplayName|Type|APIs covered| -|---------|---------|---------|---------| -| `Teamwork.Migrate.All`| Manage migration to Teams | Application-only|`POST/teams`| +| ScopeName | DisplayName | Description | Type | Admin Consent? | Entities/APIs covered | +|-----------------------|------------------------------------|-------------------------------------------------|------------------|----------------|-------------------------| +| Teamwork.Migrate.All | Manage migration to Microsoft Teams| Creating and managing resources for migration to Teams. | **Application-only** | Yes | POST /team | > [!NOTE] > Delegated authentication isn't supported. @@ -27,16 +27,9 @@ Use Microsoft Graph to import users' existing message history and data from any ## Supported channel and chat types -All channels and chats, either new or existing, support migration mode for importing historical messages. Migration mode is a special state that prevents certain operations during the data migration process to ensure data integrity. +All new and existing channels and chats support migration mode for importing historical messages. Migration mode is a special state that prevents certain operations during the data migration process to ensure data integrity. -The migration mode: - -* Temporarily restricts sending new messages to the channel or chat -* Prevents adding or removing members during migration -* Allows importing historical messages with custom timestamps -* Maintains the original conversation structure and hierarchy - -Here's how you can enable migration of historical messages: +Understand the approach for new or existing channels and chats: * **New channels or chats**: Create a new team and its standard channels in migration mode to import content. This approach allows you to recreate the exact structure from your external platform. @@ -68,10 +61,17 @@ The following table provides the content scope for existing channels and chats. ## Prerequisites -Before you set up your Microsoft 365 tenant: +### Analyze and prepare message data + +* Review the third-party data to decide what is migrated. +* Extract the selected data from the third-party chat system. +* Map the third-party chat structure to the Teams structure. +* Convert import data into format needed for migration. -* Verify that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). -* Verify that team members are in Microsoft Entra ID (Entra ID). For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Entra ID. +### Set up your Microsoft 365 tenant + +* Ensure that a Microsoft 365 tenant exists for the import data. For more information on setting up a Microsoft 365 tenancy for Teams, see [prepare your Microsoft 365 tenant](../../concepts/build-and-test/prepare-your-o365-tenant.md). +* Make sure that team members are in Microsoft Entra ID (Entra ID). For more information, see [add a new user](/azure/active-directory/fundamentals/add-users-azure-active-directory) to Entra ID. ## Import historical messages into Teams @@ -87,23 +87,23 @@ You can import historical messages seamlessly into both existing and newly creat You can create a new channel or chat or use an existing one to import a user's message history from any third-party platform to Teams. For more information, see: -* [Path 1: Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode) +* [Path 1: Create a team and standard channel in migration mode](#path-1-create-a-team-and-standard-channel-in-migration-mode) * [Path 2: Start migration on existing channels and chats](#start-migration-on-existing-channels-and-chats) -### Create a team and standard channel in migration mode +#### Path 1: Create a team and standard channel in migration mode To start migration mode, you need to create a new team in Teams and then create a channel. Currently, you can only create a standard channel. -To create a new team with a back-in-time timestamp: +#### Create a new team + +[Create a new team](/graph/api/team-post?view=graph-rest-beta&tabs=http&preserve-view=true) with a back-in-time timestamp using the team resource `createdDateTime` property. Place the new team in migration mode, a special state that restricts users from most activities within the team until the migration process is complete. Include the `teamCreationMode` instance attribute with the `migration value` in the POST request to explicitly identify the new team as being created for migration. -1. Use the team resource `createdDateTime` property to place the new team in migration mode. -1. Include the `teamCreationMode` instance attribute with the `migration` value in the POST request to identify the team as created for migration. Since you're migrating existing data, maintaining the original message timestamps, and preventing messaging activity during the migration process are key to recreating the user's existing message flow in Teams. > [!NOTE] > The `createdDateTime` field is only populated for migrated teams or channels. If you update `createdDateTime` to a past timestamp, you can't move it to a future timestamp again. -#### Request for new team creation in migration state +#### Request (Create a team in migration state) ```HTTP POST https://graph.microsoft.com/v1.0/teams @@ -118,7 +118,7 @@ Content-Type: application/json } ``` -#### Response for new team creation +#### Response ```HTTP HTTP/1.1 202 Accepted @@ -126,21 +126,20 @@ Location: /teams/{team-id}/operations/{operation-id} Content-Location: /teams/{team-id} ``` -You can receive the error message in the following scenarios: - -* If you set `createdDateTime` for a future date. -* If you correctly specify `createdDateTime`, but you omit or set an invalid value for the `teamCreationMode` instance attribute. - -#### Error message for new team creation +#### Error message (new team creation) ```HTTP 400 Bad Request ``` -To create a new channel with a back-in-time timestamp: +You can receive the error message in the following scenarios: + +* If `createdDateTime` is set for future. +* If `createdDateTime` is correctly specified, but `teamCreationMode` instance attribute is missing or set to an invalid value. + +#### Create a new channel -1. Use the channel resource `createdDateTime` property to place the new channel in migration mode. -1. Include the `channelCreationMode` instance attribute with the `migration` value in the POST request to identify the team created for migration. +[Create a new channel](/graph/api/channel-post?view=graph-rest-1.0&viewFallbackFrom=graph-rest-v1.0&tabs=http&preserve-view=true) with a back-in-time timestamp using the channel resource `createdDateTime` property. Place the new channel in migration mode, a special state that restricts users from most chat activities within the channel until the migration process is complete. Include the `channelCreationMode` instance attribute with the `migration` value in the POST request to explicitly identify the new team as being created for migration. #### Request for new channel creation in migration state From df5597ec9d4304879c38df4e48dbd9ff5353555e Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Tue, 18 Nov 2025 07:07:56 +0530 Subject: [PATCH 56/72] internal review-part 2 --- .../import-external-messages-to-teams.md | 120 ++++++++++-------- 1 file changed, 69 insertions(+), 51 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 7d623898a19..9475355e038 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -31,7 +31,7 @@ All new and existing channels and chats support migration mode for importing hi Understand the approach for new or existing channels and chats: -* **New channels or chats**: Create a new team and its standard channels in migration mode to import content. This approach allows you to recreate the exact structure from your external platform. +* **New standard channels**: Create a new team and its standard channels in migration mode to import content. This approach allows you to recreate the exact structure from your external platform. * **Existing channels or chats**: Use any team or channel that already exists in Teams, regardless of when you created it. This approach allows you to add historical context to channels that are already active in Teams and maintains continuity for ongoing conversations. @@ -75,22 +75,22 @@ The following table provides the content scope for existing channels and chats. ## Import historical messages into Teams -You can import historical messages seamlessly into both existing and newly created channels or chats by performing the following five steps: +You can import historical messages seamlessly into both existing and newly created channels or chats by performing the following steps: -1. [Create a new channel or chat or use an existing one](#step-1-create-a-new-channel-or-chat-or-use-an-existing-one) +1. [Start migration](#step-1-start-migration) 1. [Check migration status](#step-2-check-migration-status) 1. [Import messages](#step-3-import-messages) -1. [Complete migration](#step-4-complete-migration) +1. [Complete migration mode](#step-4-complete-migration-mode) 1. [Verify migration mode completion](#step-5-verify-migration-mode-completion) -### Step 1: Create a new channel or chat or use an existing one +## Step 1: Start migration -You can create a new channel or chat or use an existing one to import a user's message history from any third-party platform to Teams. For more information, see: +To start migration, you can either create a new standard channel or use an existing channel or chat to import a user's message history from any third-party platform to Teams. Depending on your scenario, choose either of the two paths: * [Path 1: Create a team and standard channel in migration mode](#path-1-create-a-team-and-standard-channel-in-migration-mode) * [Path 2: Start migration on existing channels and chats](#start-migration-on-existing-channels-and-chats) -#### Path 1: Create a team and standard channel in migration mode +### Path 1: Create a team and standard channel in migration mode To start migration mode, you need to create a new team in Teams and then create a channel. Currently, you can only create a standard channel. @@ -141,7 +141,7 @@ You can receive the error message in the following scenarios: [Create a new channel](/graph/api/channel-post?view=graph-rest-1.0&viewFallbackFrom=graph-rest-v1.0&tabs=http&preserve-view=true) with a back-in-time timestamp using the channel resource `createdDateTime` property. Place the new channel in migration mode, a special state that restricts users from most chat activities within the channel until the migration process is complete. Include the `channelCreationMode` instance attribute with the `migration` value in the POST request to explicitly identify the new team as being created for migration. -#### Request for new channel creation in migration state +#### Request (create a channel in migration state) ```HTTP POST https://graph.microsoft.com/v1.0/teams/{team-id}/channels @@ -156,7 +156,7 @@ Content-Type: application/json } ``` -#### Response of new channel creation +#### Response (create a channel in migration state) ```HTTP HTTP/1.1 202 Accepted @@ -175,22 +175,22 @@ HTTP/1.1 202 Accepted } ``` -You can receive the error message in the following scenarios: - -* If you set `createdDateTime` for a future date. -* If you correctly specify `createdDateTime`, but you omit or set an invalid value for the `channelCreationMode` instance attribute. - -#### Error message for channel creation +#### Error message ```HTTP 400 Bad Request ``` -After you create a new team and channel, perform the following steps: +You can receive the error message in the following scenarios: + +* If `createdDateTime` is set for future. +* If `createdDateTime` is correctly specified but `channelCreationMode` instance attribute is missing or set to an invalid value. + +Complete the following steps after you create a new team and standard channel: 1. [Check migration status](#step-2-check-migration-status) 1. [Import messages](#step-3-import-messages) -1. [Complete migration](#step-4-complete-migration) +1. [Complete migration mode](#step-4-complete-migration-mode) 1. [Verify migration mode completion](#step-5-verify-migration-mode-completion) ### Start migration on existing channels and chats @@ -204,7 +204,7 @@ Use the `startMigration` API to enable migration mode on existing channels or ch Learn how to enable migration mode on existing channels including the request, response, and an example. -#### Request for existing channel migration +#### Request (existing channel migration) ```HTTP POST /teams/{team-id}/channels/{channel-id}/startMigration @@ -217,7 +217,7 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration > Microsoft Graph uses DateTimeOffset to represent date and time with a UTC offset for an accurate time zone. >The `conversationCreationDateTime` value must be greater than the minimum value for `DateTimeOffset` and less than the current value of the channel's `createdDateTime`. -#### Channel migration response +#### Response (existing channel migration) If the request is successful, the method returns an empty HTTP response. @@ -239,7 +239,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 Learn how to enable migration mode on existing chats, including the request, response, and an example. -#### Chat migration request +#### Request (existing chat migration) ```HTTP POST /chats/{chat-id}/startMigration @@ -252,7 +252,7 @@ POST /chats/{chat-id}/startMigration > Microsoft Graph uses DateTimeOffset to represent date and time with a UTC offset for an accurate time zone. >The `conversationCreationDateTime` must be greater than the minimum value for `DateTimeOffset` and less than the current value of the chat's `createdDateTime`. -#### Chat migration response +#### Response (existing chat migration) If the request is successful, the method returns an empty HTTP response. @@ -277,14 +277,14 @@ Consider the following important points: * The `creationDateTime` property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. * The `startMigration` API starts the message migration process by setting the migration mode to `inProgress` for a specified channel or chat. -### Step 2: Check migration status +## Step 2: Check migration status Call the `Get channel` or `Get chat` API to confirm that the migration mode state is set to `inProgress`. For more information, see: * [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) * [Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) -### Step 3: Import messages +## Step 3: Import messages Use the `POST` API to import back-in-time messages by including the `createdDateTime` and `from` properties in the request body. @@ -294,7 +294,7 @@ Use the `POST` API to import back-in-time messages by including the `createdDate > * `createdDateTime` must be unique across messages in the same thread. > * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has `createdDateTime` set to *2020-09-16T05:50:31.0025302Z*, the API converts it to *2020-09-16T05:50:31.002Z* when ingesting the message. -#### Send a text-only message using POST +### Request (POST message that is text-only) ```http POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages @@ -315,7 +315,7 @@ POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages } ``` -#### Send text message response +### Response ```http HTTP/1.1 200 OK @@ -357,7 +357,7 @@ HTTP/1.1 200 OK } ``` -#### Error message +### Error message ```http 400 Bad Request @@ -365,11 +365,12 @@ HTTP/1.1 200 OK You receive an error message if you set the `createdDateTime` property to a future date and time. -#### Send a message with an inline image using POST +### Request (POST a message with inline image) > [!NOTE] > -> Use the standard `chatMessage` scopes. No other permission scopes are required. +> * There are no special permission scopes in this scenario since the request is part of `chatMessage`. +> * The scopes for `chatMessage` apply here. ```http POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages @@ -389,7 +390,7 @@ POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages } ``` -#### Send inline image response +### Response (inline image) ```http HTTP/1.1 200 OK @@ -428,61 +429,78 @@ HTTP/1.1 200 OK } ``` -### Step 4: Complete migration +## Step 4: Complete migration mode -Use the `completeMigration` API to finish the migration process for both new and existing channels and chats. For more information, see: +Use the `completeMigration` method to finish the migration process for new channels and the `completeMigration` API to finish migration for existing channels and chats. For more information, see: * [Complete the new team and channel migration](#complete-the-new-team-and-channel-migration) -* [Complete existing channel migration](#complete-existing-channel-migration) -* [Complete existing chat migration](#complete-existing-chat-migration) +* [Complete existing channel or chat migration](#complete-existing-channel-or-chat-migration) -#### Complete the new team and channel migration +### Complete the new team and channel migration -After the message migration process completes, use the `completeMigration` method to take both the team and channel out of migration mode. This step opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team completes, you must complete all channels out of migration mode. +After the message migration process is complete, both the team and channel are taken out of migration mode using the `completeMigration` method. This step opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team completes, all channels must be completed out of migration mode. -#### Request for end of channel migration mode +#### Request (end channel migration mode) ```http POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/completeMigration ``` -#### Response for end of channel migration mode +#### Response (end channel migration mode) ```http HTTP/1.1 204 NoContent ``` -#### Request for end of team migration mode +#### Request (end team migration mode) ```http POST https://graph.microsoft.com/v1.0/teams/team-id/completeMigration ``` -#### Response for end of team migration mode +#### Response (end team migration mode) ```http HTTP/1.1 204 NoContent ``` -Go to [Step 5: Verify migration mode completion](#step-5-verify-migration-mode-completion). +### Add Team members -#### Complete existing channel migration +You can add a member to a team using the Teams UI or Microsoft Graph add member API: -For existing channels already in migration mode, use the `completeMigration` API to mark the migration state as completed. This change ensures that the channel remains permanently available instead of being dropped after migration. After you send a `completeMigration` request for new or existing channels, you can still import more messages by calling the `startMigration` API. +#### Request (add member) -#### Complete channel migration request +```http +POST https://graph.microsoft.com/beta/teams/{team-id}/members +Content-type: application/json +Content-length: 30 -```HTTP -POST /teams/{team-id}/channels/{channel-id}/completeMigration +{ + "@odata.type": "#microsoft.graph.aadUserConversationMember", + "roles": [], + "user@odata.bind": "https://graph.microsoft.com/beta/users/{user-id}" +} ``` -Go to [Step 5: Verify migration mode completion](#step-5-verify-migration-mode-completion), after you complete the existing channel migration. +#### Response (add member) -#### Complete existing chat migration +```http +HTTP/1.1 204 No Content +``` + +Go to [Step 5: Verify migration mode completion](#step-5-verify-migration-mode-completion). -For existing chats already in migration mode, call the `completeMigration` API to update the migration mode state to completed. This process marks the chat as fully migrated. After calling `completeMigration` on a new or existing chat, you can continue importing messages by using the `startMigration` API. +### Complete existing channel or chat migration + +For existing channels or chats already in migration mode, use the `completeMigration` API to mark the migration state as completed. This process ensures that the channel or chat remains permanently available instead of being dropped after migration. + +#### Request (existing channel migration completion) + +```HTTP +POST /teams/{team-id}/channels/{channel-id}/completeMigration +``` -#### Complete chat migration request +#### Request (existing chat migration completion) ```HTTP POST /chats/{chat-id}/completeMigration @@ -498,9 +516,9 @@ Call the `Get channel` or the `Get chat` API to verify that the migration mode s -* After you make the `completeMigration` request, you can't import more messages into the Teams. +* After calling `completeMigration` on an existing channel or chat, you can continue importing messages by using the `startMigration` API. -* You can only add team members to the new Teams after the `completeMigration` request returns a successful response. +* You can only add team members to the new Teams after the `completeMigration` request returns a successful response. This is applicable only for the newly created team and standard channel. * Throttling: Messages import at five RPS per channel. From 75a83e1f258eab2c0f9477b0a735f165290aa23b Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Tue, 18 Nov 2025 07:15:45 +0530 Subject: [PATCH 57/72] Update import-external-messages-to-teams.md --- .../import-messages/import-external-messages-to-teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 9475355e038..40fce332e56 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -506,7 +506,7 @@ POST /teams/{team-id}/channels/{channel-id}/completeMigration POST /chats/{chat-id}/completeMigration ``` -### Step 5: Verify migration mode completion +## Step 5: Verify migration mode completion Call the `Get channel` or the `Get chat` API to verify that the migration mode state is marked as completed. For more information, see [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or [Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true). From 0fdbb84540437d63f831a151632caf46a6862c55 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Tue, 18 Nov 2025 11:28:32 +0530 Subject: [PATCH 58/72] Update import-external-messages-to-teams.md --- .../import-messages/import-external-messages-to-teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 40fce332e56..58e8768d6c4 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -466,7 +466,7 @@ HTTP/1.1 204 NoContent ### Add Team members -You can add a member to a team using the Teams UI or Microsoft Graph add member API: +You can add a member to a team using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9) or Microsoft Graph [add member](/graph/api/group-post-members?view=graph-rest-beta&tabs=http&preserve-view=true) API: #### Request (add member) From 0f116e9ced3a6e45d2900746d0ef6e85a46d9244 Mon Sep 17 00:00:00 2001 From: SukanyaDas-MSFT Date: Tue, 18 Nov 2025 16:47:55 +0530 Subject: [PATCH 59/72] Draft enhancement 1 --- .../import-external-messages-to-teams.md | 134 +++++++++--------- 1 file changed, 65 insertions(+), 69 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 58e8768d6c4..2ec078a74bc 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -17,29 +17,30 @@ With Microsoft Graph, you can migrate users' existing message history and data f ## Permissions -| ScopeName | DisplayName | Description | Type | Admin Consent? | Entities/APIs covered | -|-----------------------|------------------------------------|-------------------------------------------------|------------------|----------------|-------------------------| -| Teamwork.Migrate.All | Manage migration to Microsoft Teams| Creating and managing resources for migration to Teams. | **Application-only** | Yes | POST /team | +| Scope name | Display name | Description | Type | Admin consent required | Entities/APIs covered | +|---------- |-------------|-------------|------|----------------|-------------------------| +| Teamwork.Migrate.All | [Manage migration to Microsoft Teams](https://learn.microsoft.com/en-us/graph/permissions-reference#teamworkmigrateall)| Creating and managing resources for migration to Teams. | **Application-only** | Yes | POST /team | > [!NOTE] > Delegated authentication isn't supported. -> ## Supported channel and chat types -All new and existing channels and chats support migration mode for importing historical messages. Migration mode is a special state that prevents certain operations during the data migration process to ensure data integrity. - -Understand the approach for new or existing channels and chats: +You can migrate user's existing message history and data from an external system in either of the following ways: -* **New standard channels**: Create a new team and its standard channels in migration mode to import content. This approach allows you to recreate the exact structure from your external platform. +* **Create a new standard channels**: Create a new team and its standard channels in migration mode to import content. To enable migration mode*, set team or channel creation mode to **migration**. +This allows you to import the exact structure of your external system into the new channel. -* **Existing channels or chats**: Use any team or channel that already exists in Teams, regardless of when you created it. This approach allows you to add historical context to channels that are already active in Teams and maintains continuity for ongoing conversations. +* **Use an existing team, channel or chat**: Use any team, channel or chat that already exists in Teams, regardless of when you created it. To enable migration mode in an existing channel or chat, see [Existing channel migration](#existing-channel-migration). This approach allows you to add existing context to channels that are already active in Teams and maintains continuity for ongoing conversations. > [!NOTE] > > * Only standard channels are supported when creating a channel in migration mode from scratch. -> > * Federated content can't be imported. All imported content must come from the authenticated tenant and only one app can manage a thread at a time. Another app can import content only after the first app completes migration. +> * Migration mode ensure the following till the migration is completed: +> * Restricts receipt of new messages to the channel or chat +> * Prevents adding or removing members during migration +> * Allows importing historical messages with custom timestamps ## Content scope for import @@ -85,25 +86,25 @@ You can import historical messages seamlessly into both existing and newly creat ## Step 1: Start migration -To start migration, you can either create a new standard channel or use an existing channel or chat to import a user's message history from any third-party platform to Teams. Depending on your scenario, choose either of the two paths: +To start migrating a user's message history from any third-party platform to Teams, you can either create a new standard channel or use an existing channel or chat. Depending on your scenario, choose either of the two paths: -* [Path 1: Create a team and standard channel in migration mode](#path-1-create-a-team-and-standard-channel-in-migration-mode) -* [Path 2: Start migration on existing channels and chats](#start-migration-on-existing-channels-and-chats) +* [Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode) +* [Start migration on existing channels and chats](#start-migration-on-existing-channels-and-chats) -### Path 1: Create a team and standard channel in migration mode +### Create a team and standard channel in migration mode -To start migration mode, you need to create a new team in Teams and then create a channel. Currently, you can only create a standard channel. +In this scenario, create a new team and standard channels under it in migration mode to proceed with importing existing messages. Migration mode is supported only for standard channels. #### Create a new team -[Create a new team](/graph/api/team-post?view=graph-rest-beta&tabs=http&preserve-view=true) with a back-in-time timestamp using the team resource `createdDateTime` property. Place the new team in migration mode, a special state that restricts users from most activities within the team until the migration process is complete. Include the `teamCreationMode` instance attribute with the `migration value` in the POST request to explicitly identify the new team as being created for migration. - -Since you're migrating existing data, maintaining the original message timestamps, and preventing messaging activity during the migration process are key to recreating the user's existing message flow in Teams. +* [Create a new team](/graph/api/team-post?view=graph-rest-beta&tabs=http&preserve-view=true) with a back-in-time timestamp using the `createdDateTime` property. +* Place the new team in migration mode by setting **teamCreationMode** to **migration**. > [!NOTE] > The `createdDateTime` field is only populated for migrated teams or channels. If you update `createdDateTime` to a past timestamp, you can't move it to a future timestamp again. +> Migration mode ensures that the original message timestamps are preserved and prevents new messages from being sent during the migration process. -#### Request (Create a team in migration state) +#### Request for creating a new team in migration mode ```HTTP POST https://graph.microsoft.com/v1.0/teams @@ -126,22 +127,20 @@ Location: /teams/{team-id}/operations/{operation-id} Content-Location: /teams/{team-id} ``` -#### Error message (new team creation) +#### Error message + +The following error message is visible if `createdDateTime` is set for future; or `createdDateTime` is correctly specified, but `teamCreationMode` instance attribute is missing or set to an invalid value. ```HTTP 400 Bad Request ``` -You can receive the error message in the following scenarios: - -* If `createdDateTime` is set for future. -* If `createdDateTime` is correctly specified, but `teamCreationMode` instance attribute is missing or set to an invalid value. - #### Create a new channel -[Create a new channel](/graph/api/channel-post?view=graph-rest-1.0&viewFallbackFrom=graph-rest-v1.0&tabs=http&preserve-view=true) with a back-in-time timestamp using the channel resource `createdDateTime` property. Place the new channel in migration mode, a special state that restricts users from most chat activities within the channel until the migration process is complete. Include the `channelCreationMode` instance attribute with the `migration` value in the POST request to explicitly identify the new team as being created for migration. +* [Create a new channel](/graph/api/channel-post?view=graph-rest-1.0&viewFallbackFrom=graph-rest-v1.0&tabs=http&preserve-view=true) with a back-in-time timestamp using the channel resource `createdDateTime` property. +* Place the new channel in migration mode by setting **channelCreationMode** to **migration**. -#### Request (create a channel in migration state) +#### Request for creating a channel in migration mode ```HTTP POST https://graph.microsoft.com/v1.0/teams/{team-id}/channels @@ -156,7 +155,7 @@ Content-Type: application/json } ``` -#### Response (create a channel in migration state) +#### Response ```HTTP HTTP/1.1 202 Accepted @@ -177,16 +176,13 @@ HTTP/1.1 202 Accepted #### Error message +The following error message is visible if `createdDateTime` is set for future; or `createdDateTime` is correctly specified, but `channelCreationMode` instance attribute is missing or set to an invalid value. + ```HTTP 400 Bad Request ``` -You can receive the error message in the following scenarios: - -* If `createdDateTime` is set for future. -* If `createdDateTime` is correctly specified but `channelCreationMode` instance attribute is missing or set to an invalid value. - -Complete the following steps after you create a new team and standard channel: +Once you've creted a new team and standard channel, complete migration with the following steps: 1. [Check migration status](#step-2-check-migration-status) 1. [Import messages](#step-3-import-messages) @@ -195,16 +191,16 @@ Complete the following steps after you create a new team and standard channel: ### Start migration on existing channels and chats -Use the `startMigration` API to enable migration mode on existing channels or chats. `startMigration` sets the channel’s or chat's migration state to `inProgress` and begins the message import process. For more information, see: +In this scenario, use the `startMigration` API to enable migration mode on existing channels or chats. `startMigration` sets the channel’s or chat's migration state to `inProgress` and begins the message import process. For more information, see: * [Existing channel migration](#existing-channel-migration) * [Existing chat migration](#existing-chat-migration) -### Existing channel migration +#### Existing channel migration Learn how to enable migration mode on existing channels including the request, response, and an example. -#### Request (existing channel migration) +##### Request for existing channel migration ```HTTP POST /teams/{team-id}/channels/{channel-id}/startMigration @@ -214,10 +210,10 @@ POST /teams/{team-id}/channels/{channel-id}/startMigration ``` > [!TIP] -> Microsoft Graph uses DateTimeOffset to represent date and time with a UTC offset for an accurate time zone. +> Microsoft Graph uses **DateTimeOffset** to represent date and time with a UTC offset for an accurate time zone. >The `conversationCreationDateTime` value must be greater than the minimum value for `DateTimeOffset` and less than the current value of the channel's `createdDateTime`. -#### Response (existing channel migration) +##### Response If the request is successful, the method returns an empty HTTP response. @@ -225,7 +221,7 @@ If the request is successful, the method returns an empty HTTP response. HTTP/1.1 204 No Content ``` -##### Channel migration example +##### Example ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/channels/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration @@ -235,11 +231,11 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 ``` -### Existing chat migration +#### Existing chat migration Learn how to enable migration mode on existing chats, including the request, response, and an example. -#### Request (existing chat migration) +##### Request for existing chat migration ```HTTP POST /chats/{chat-id}/startMigration @@ -249,10 +245,10 @@ POST /chats/{chat-id}/startMigration ``` > [!TIP] -> Microsoft Graph uses DateTimeOffset to represent date and time with a UTC offset for an accurate time zone. +> Microsoft Graph uses **DateTimeOffset** to represent date and time with a UTC offset for an accurate time zone. >The `conversationCreationDateTime` must be greater than the minimum value for `DateTimeOffset` and less than the current value of the chat's `createdDateTime`. -#### Response (existing chat migration) +##### Response If the request is successful, the method returns an empty HTTP response. @@ -260,7 +256,7 @@ If the request is successful, the method returns an empty HTTP response. HTTP/1.1 204 No Content ``` -##### Chat migration example +##### Example ```HTTP POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration @@ -279,18 +275,18 @@ Consider the following important points: ## Step 2: Check migration status -Call the `Get channel` or `Get chat` API to confirm that the migration mode state is set to `inProgress`. For more information, see: +Call `Get channel` or `Get chat` to confirm that the migration mode state is set to `inProgress`. For more information, see: * [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) * [Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) ## Step 3: Import messages -Use the `POST` API to import back-in-time messages by including the `createdDateTime` and `from` properties in the request body. +Now you can import back-in-time messages by including the `createdDateTime` and `from` keys in the request body. > [!NOTE] > -> * The API doesn't support messages imported with `createdDateTime` earlier than the message thread `createdDateTime`. +> * The API doesn't support messages imported with a creation date and time earlier than the `createdDateTime` for the message thread. > * `createdDateTime` must be unique across messages in the same thread. > * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has `createdDateTime` set to *2020-09-16T05:50:31.0025302Z*, the API converts it to *2020-09-16T05:50:31.002Z* when ingesting the message. @@ -359,13 +355,13 @@ HTTP/1.1 200 OK ### Error message +You receive the following error message if you set the `createdDateTime` property to a future date and time. + ```http 400 Bad Request ``` -You receive an error message if you set the `createdDateTime` property to a future date and time. - -### Request (POST a message with inline image) +#### Request to post a message with inline image > [!NOTE] > @@ -390,7 +386,7 @@ POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages } ``` -### Response (inline image) +### Response ```http HTTP/1.1 200 OK @@ -429,36 +425,36 @@ HTTP/1.1 200 OK } ``` -## Step 4: Complete migration mode +## Step 4: Complete migration -Use the `completeMigration` method to finish the migration process for new channels and the `completeMigration` API to finish migration for existing channels and chats. For more information, see: +Use `completeMigration` to finish the migration process for new and existing channels and chats. For more information, see: * [Complete the new team and channel migration](#complete-the-new-team-and-channel-migration) * [Complete existing channel or chat migration](#complete-existing-channel-or-chat-migration) -### Complete the new team and channel migration +### Complete new team and channel migration -After the message migration process is complete, both the team and channel are taken out of migration mode using the `completeMigration` method. This step opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team completes, all channels must be completed out of migration mode. +Use `completeMigration` method to complete migration for the new team and channel. This opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team message migration is completed, migration on all channels must be completed. -#### Request (end channel migration mode) +#### Request to end channel migration ```http -POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/completeMigration +POST https://graph.microsoft.com/beta/teams/team-id/channels/channel-id/completeMigration ``` -#### Response (end channel migration mode) +#### Response ```http HTTP/1.1 204 NoContent ``` -#### Request (end team migration mode) +#### Request to end team migration ```http -POST https://graph.microsoft.com/v1.0/teams/team-id/completeMigration +POST https://graph.microsoft.com/beta/teams/team-id/completeMigration ``` -#### Response (end team migration mode) +#### Response ```http HTTP/1.1 204 NoContent @@ -466,9 +462,9 @@ HTTP/1.1 204 NoContent ### Add Team members -You can add a member to a team using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9) or Microsoft Graph [add member](/graph/api/group-post-members?view=graph-rest-beta&tabs=http&preserve-view=true) API: +You can add a single member to a team using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9) or Microsoft Graph [add member](/graph/api/group-post-members?view=graph-rest-beta&tabs=http&preserve-view=true) API: -#### Request (add member) +#### Request to add a member ```http POST https://graph.microsoft.com/beta/teams/{team-id}/members @@ -482,7 +478,7 @@ Content-length: 30 } ``` -#### Response (add member) +#### Response ```http HTTP/1.1 204 No Content @@ -494,13 +490,13 @@ Go to [Step 5: Verify migration mode completion](#step-5-verify-migration-mode-c For existing channels or chats already in migration mode, use the `completeMigration` API to mark the migration state as completed. This process ensures that the channel or chat remains permanently available instead of being dropped after migration. -#### Request (existing channel migration completion) +#### Request to complete existing channel migration ```HTTP POST /teams/{team-id}/channels/{channel-id}/completeMigration ``` -#### Request (existing chat migration completion) +#### Request to complete existing chat migration ```HTTP POST /chats/{chat-id}/completeMigration @@ -508,8 +504,8 @@ POST /chats/{chat-id}/completeMigration ## Step 5: Verify migration mode completion -Call the `Get channel` or the `Get chat` API to verify that the migration mode state is marked as completed. For more information, see [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or -[Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true). +Call [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or +[Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) to verify that the migration mode state is marked as completed. ## Tips and additional information From 9bb04c6781483a07840119554fd6527e9f043c40 Mon Sep 17 00:00:00 2001 From: SukanyaDas-MSFT Date: Tue, 18 Nov 2025 17:58:13 +0530 Subject: [PATCH 60/72] Dev 0 changes --- .../import-external-messages-to-teams.md | 80 ++++++++++++------- 1 file changed, 50 insertions(+), 30 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 2ec078a74bc..76f64cab779 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -10,7 +10,7 @@ ms.date: 11/17/2025 # Import third-party platform messages to Teams using Microsoft Graph -With Microsoft Graph, you can migrate users' existing message history and data from an external system into a Teams channel. By enabling the recreation of a third-party platform messaging hierarchy inside Teams, users can continue their communications in a seamless manner and proceed without interruption. +With Microsoft Graph, you can migrate users' existing message history and data from an external system into Teams. By enabling the recreation of a third-party platform messaging hierarchy inside Teams, users can continue their communications in a seamless manner and proceed without interruption. > [!NOTE] > In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. @@ -28,7 +28,7 @@ With Microsoft Graph, you can migrate users' existing message history and data f You can migrate user's existing message history and data from an external system in either of the following ways: -* **Create a new standard channels**: Create a new team and its standard channels in migration mode to import content. To enable migration mode*, set team or channel creation mode to **migration**. +* **Create a new standard channels**: Create a new team and its standard channels in migration mode to import content. To enable migration mode* for a new standard team and channel, see [Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode). This allows you to import the exact structure of your external system into the new channel. * **Use an existing team, channel or chat**: Use any team, channel or chat that already exists in Teams, regardless of when you created it. To enable migration mode in an existing channel or chat, see [Existing channel migration](#existing-channel-migration). This approach allows you to add existing context to channels that are already active in Teams and maintains continuity for ongoing conversations. @@ -37,6 +37,7 @@ This allows you to import the exact structure of your external system into the n > > * Only standard channels are supported when creating a channel in migration mode from scratch. > * Federated content can't be imported. All imported content must come from the authenticated tenant and only one app can manage a thread at a time. Another app can import content only after the first app completes migration. +> > * Migration mode ensure the following till the migration is completed: > * Restricts receipt of new messages to the channel or chat > * Prevents adding or removing members during migration @@ -86,25 +87,25 @@ You can import historical messages seamlessly into both existing and newly creat ## Step 1: Start migration -To start migrating a user's message history from any third-party platform to Teams, you can either create a new standard channel or use an existing channel or chat. Depending on your scenario, choose either of the two paths: +To start migrating a user's message history from any third-party platform to Teams, you can either create a new team and standard channel or use an existing channel or chat. Depending on your scenario, choose either of the two paths: * [Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode) * [Start migration on existing channels and chats](#start-migration-on-existing-channels-and-chats) ### Create a team and standard channel in migration mode -In this scenario, create a new team and standard channels under it in migration mode to proceed with importing existing messages. Migration mode is supported only for standard channels. +In this scenario, create a new team and standard channel under it in migration mode to proceed with importing existing messages. Migration mode is supported only for standard channels. #### Create a new team * [Create a new team](/graph/api/team-post?view=graph-rest-beta&tabs=http&preserve-view=true) with a back-in-time timestamp using the `createdDateTime` property. -* Place the new team in migration mode by setting **teamCreationMode** to **migration**. +* Place the new team in migration mode by setting `teamCreationMode` to `migration`. > [!NOTE] > The `createdDateTime` field is only populated for migrated teams or channels. If you update `createdDateTime` to a past timestamp, you can't move it to a future timestamp again. -> Migration mode ensures that the original message timestamps are preserved and prevents new messages from being sent during the migration process. +> Migration mode ensures that the original message timestamps are preserved, and prevents new messages from being sent when the migration is in progress. -#### Request for creating a new team in migration mode +##### Request for creating a new team in migration mode ```HTTP POST https://graph.microsoft.com/v1.0/teams @@ -119,7 +120,7 @@ Content-Type: application/json } ``` -#### Response +##### Response ```HTTP HTTP/1.1 202 Accepted @@ -127,7 +128,7 @@ Location: /teams/{team-id}/operations/{operation-id} Content-Location: /teams/{team-id} ``` -#### Error message +##### Error message The following error message is visible if `createdDateTime` is set for future; or `createdDateTime` is correctly specified, but `teamCreationMode` instance attribute is missing or set to an invalid value. @@ -137,8 +138,8 @@ The following error message is visible if `createdDateTime` is set for future; o #### Create a new channel -* [Create a new channel](/graph/api/channel-post?view=graph-rest-1.0&viewFallbackFrom=graph-rest-v1.0&tabs=http&preserve-view=true) with a back-in-time timestamp using the channel resource `createdDateTime` property. -* Place the new channel in migration mode by setting **channelCreationMode** to **migration**. +* [Create a new channel](/graph/api/channel-post?view=graph-rest-1.0&viewFallbackFrom=graph-rest-v1.0&tabs=http&preserve-view=true) with a back-in-time timestamp using the `createdDateTime` property of the channel resource. +* Place the new channel in migration mode by setting `channelCreationMode` to `migration`. #### Request for creating a channel in migration mode @@ -182,7 +183,7 @@ The following error message is visible if `createdDateTime` is set for future; o 400 Bad Request ``` -Once you've creted a new team and standard channel, complete migration with the following steps: +Once you've created a new team and standard channel, complete migration with the following steps: 1. [Check migration status](#step-2-check-migration-status) 1. [Import messages](#step-3-import-messages) @@ -191,26 +192,26 @@ Once you've creted a new team and standard channel, complete migration with the ### Start migration on existing channels and chats -In this scenario, use the `startMigration` API to enable migration mode on existing channels or chats. `startMigration` sets the channel’s or chat's migration state to `inProgress` and begins the message import process. For more information, see: +In this scenario, use the `startMigration` API to enable migration mode on existing channels or chats. `startMigration` sets the migration state to `InProgress` and begins the message import process. For more information, see: * [Existing channel migration](#existing-channel-migration) * [Existing chat migration](#existing-chat-migration) #### Existing channel migration -Learn how to enable migration mode on existing channels including the request, response, and an example. +To enable migration mode on existing channels, refer the following. ##### Request for existing channel migration ```HTTP -POST /teams/{team-id}/channels/{channel-id}/startMigration +POST https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}/startMigration { "conversationCreationDateTime": "2024-01-01T00:00:00Z" } ``` > [!TIP] -> Microsoft Graph uses **DateTimeOffset** to represent date and time with a UTC offset for an accurate time zone. +> Microsoft Graph uses `DateTimeOffset` to represent date and time with a UTC offset for an accurate time zone. >The `conversationCreationDateTime` value must be greater than the minimum value for `DateTimeOffset` and less than the current value of the channel's `createdDateTime`. ##### Response @@ -233,19 +234,19 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 #### Existing chat migration -Learn how to enable migration mode on existing chats, including the request, response, and an example. +To enable migration mode on existing chats, refer the following. ##### Request for existing chat migration ```HTTP -POST /chats/{chat-id}/startMigration +POST https://graph.microsoft.com/beta/chats/{chat-id}/startMigration { "conversationCreationDateTime": "2024-01-01T00:00:00Z" } ``` > [!TIP] -> Microsoft Graph uses **DateTimeOffset** to represent date and time with a UTC offset for an accurate time zone. +> Microsoft Graph uses `DateTimeOffset` to represent date and time with a UTC offset for an accurate time zone. >The `conversationCreationDateTime` must be greater than the minimum value for `DateTimeOffset` and less than the current value of the chat's `createdDateTime`. ##### Response @@ -271,11 +272,11 @@ Consider the following important points: * Define a minimum timestamp for messages to migrate. The provided timestamp must be older than the channel or chat's current `createdDateTime`. This timestamp replaces the existing `createdDateTime` of the channel. If you update `createdDateTime` to a past timestamp, you can't move it to a future timestamp again. * The `creationDateTime` property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. -* The `startMigration` API starts the message migration process by setting the migration mode to `inProgress` for a specified channel or chat. +* The `startMigration` API starts the message migration process by setting the migration mode to `InProgress` for a specified channel or chat. ## Step 2: Check migration status -Call `Get channel` or `Get chat` to confirm that the migration mode state is set to `inProgress`. For more information, see: +Call `Get channel` or `Get chat` to confirm that the 'migrationMode' state is set to `InProgress`. For more information, see: * [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) * [Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) @@ -290,7 +291,7 @@ Now you can import back-in-time messages by including the `createdDateTime` and > * `createdDateTime` must be unique across messages in the same thread. > * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has `createdDateTime` set to *2020-09-16T05:50:31.0025302Z*, the API converts it to *2020-09-16T05:50:31.002Z* when ingesting the message. -### Request (POST message that is text-only) +### Request to post message that is text-only ```http POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages @@ -427,14 +428,14 @@ HTTP/1.1 200 OK ## Step 4: Complete migration -Use `completeMigration` to finish the migration process for new and existing channels and chats. For more information, see: +Use `completeMigration` API to finish the migration process for new and existing channels and chats. For more information, see: -* [Complete the new team and channel migration](#complete-the-new-team-and-channel-migration) +* [Complete new team and channel migration](#complete-new-team-and-channel-migration) * [Complete existing channel or chat migration](#complete-existing-channel-or-chat-migration) ### Complete new team and channel migration -Use `completeMigration` method to complete migration for the new team and channel. This opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team message migration is completed, migration on all channels must be completed. +Use `completeMigration` API to complete migration for the new team and channel. This opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team message migration is completed, migration on all channels must be completed. #### Request to end channel migration @@ -460,9 +461,9 @@ POST https://graph.microsoft.com/beta/teams/team-id/completeMigration HTTP/1.1 204 NoContent ``` -### Add Team members +### Add team members -You can add a single member to a team using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9) or Microsoft Graph [add member](/graph/api/group-post-members?view=graph-rest-beta&tabs=http&preserve-view=true) API: +You can add a single member to a team using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9) or Microsoft Graph [add member](/graph/api/group-post-members?view=graph-rest-beta&tabs=http&preserve-view=true) API. #### Request to add a member @@ -484,7 +485,7 @@ Content-length: 30 HTTP/1.1 204 No Content ``` -Go to [Step 5: Verify migration mode completion](#step-5-verify-migration-mode-completion). +Once you've completed new team and channel migration, go to [Step 5: Verify migration mode completion](#step-5-verify-migration-mode-completion). ### Complete existing channel or chat migration @@ -493,13 +494,26 @@ For existing channels or chats already in migration mode, use the `completeMigra #### Request to complete existing channel migration ```HTTP -POST /teams/{team-id}/channels/{channel-id}/completeMigration +POST https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}/completeMigration + +``` + +#### Response + +```http +HTTP/1.1 204 NoContent ``` #### Request to complete existing chat migration ```HTTP -POST /chats/{chat-id}/completeMigration +POST https://graph.microsoft.com/beta/chats/{chat-id}/completeMigration +``` + +#### Response + +```http +HTTP/1.1 204 NoContent ``` ## Step 5: Verify migration mode completion @@ -523,6 +537,12 @@ Call [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve > [!NOTE] > Inline images are the only type of media supported by the import message API schema. +## Code sample + +| Sample name | Description | Node.js | C# | Python | +| --- | --- | --- | --- | --- | +| Graph chat migration | This sample app can be used to migrate historical messages from external platforms to Teams. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/graph-chat-migration/nodejs) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/graph-chat-migration/csharp) | NA | + ## See also * [Microsoft Graph and Teams integration](/graph/teams-concept-overview) From 67296b1d6e181c4bee7e687a0b707a76f7f2934b Mon Sep 17 00:00:00 2001 From: SukanyaDas-MSFT Date: Tue, 18 Nov 2025 19:54:22 +0530 Subject: [PATCH 61/72] Edits --- .../import-external-messages-to-teams.md | 79 ++++++++----------- 1 file changed, 33 insertions(+), 46 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 76f64cab779..1b77d2ccf27 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -19,29 +19,30 @@ With Microsoft Graph, you can migrate users' existing message history and data f | Scope name | Display name | Description | Type | Admin consent required | Entities/APIs covered | |---------- |-------------|-------------|------|----------------|-------------------------| -| Teamwork.Migrate.All | [Manage migration to Microsoft Teams](https://learn.microsoft.com/en-us/graph/permissions-reference#teamworkmigrateall)| Creating and managing resources for migration to Teams. | **Application-only** | Yes | POST /team | +| Teamwork.Migrate.All | [Manage migration to Microsoft Teams](https://learn.microsoft.com/graph/permissions-reference#teamworkmigrateall)| Creating and managing resources for migration to Teams. | **Application-only** | Yes | POST /team | > [!NOTE] > Delegated authentication isn't supported. ## Supported channel and chat types -You can migrate user's existing message history and data from an external system in either of the following ways: +You can migrate user's existing message history and data from an external system either in a new team and standard channel or in an existing team, channel, or chat. -* **Create a new standard channels**: Create a new team and its standard channels in migration mode to import content. To enable migration mode* for a new standard team and channel, see [Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode). +* **New team and standard channel**: Create a new team and its standard channels in migration mode to import content. To enable `migrationMode` for a new standard team and channel, see [Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode). This allows you to import the exact structure of your external system into the new channel. -* **Use an existing team, channel or chat**: Use any team, channel or chat that already exists in Teams, regardless of when you created it. To enable migration mode in an existing channel or chat, see [Existing channel migration](#existing-channel-migration). This approach allows you to add existing context to channels that are already active in Teams and maintains continuity for ongoing conversations. +* **Existing team, channel or chat**: Use any team, channel or chat that already exists in Teams, regardless of when you created it. To enable migration mode in an existing channel or chat, see [Existing channel migration](#existing-channel-migration). This allows you to add existing context to channels that are already active in Teams and maintains continuity for ongoing conversations. > [!NOTE] > > * Only standard channels are supported when creating a channel in migration mode from scratch. > * Federated content can't be imported. All imported content must come from the authenticated tenant and only one app can manage a thread at a time. Another app can import content only after the first app completes migration. -> -> * Migration mode ensure the following till the migration is completed: -> * Restricts receipt of new messages to the channel or chat -> * Prevents adding or removing members during migration -> * Allows importing historical messages with custom timestamps + +`migrationMode` ensure the following till the migration is completed: + +* Restricts receipt of new messages to the channel or chat +* Prevents adding or removing members during migration +* Allows importing historical messages with custom timestamps ## Content scope for import @@ -105,7 +106,7 @@ In this scenario, create a new team and standard channel under it in migration m > The `createdDateTime` field is only populated for migrated teams or channels. If you update `createdDateTime` to a past timestamp, you can't move it to a future timestamp again. > Migration mode ensures that the original message timestamps are preserved, and prevents new messages from being sent when the migration is in progress. -##### Request for creating a new team in migration mode +##### Request (create a team in migration state) ```HTTP POST https://graph.microsoft.com/v1.0/teams @@ -130,18 +131,21 @@ Content-Location: /teams/{team-id} ##### Error message -The following error message is visible if `createdDateTime` is set for future; or `createdDateTime` is correctly specified, but `teamCreationMode` instance attribute is missing or set to an invalid value. - ```HTTP 400 Bad Request ``` +You can receive the error message in the following scenarios: + +* If `createdDateTime` is set for future. +* If `createdDateTime` is correctly specified, but `teamCreationMode` instance attribute is missing or set to invalid value. + #### Create a new channel * [Create a new channel](/graph/api/channel-post?view=graph-rest-1.0&viewFallbackFrom=graph-rest-v1.0&tabs=http&preserve-view=true) with a back-in-time timestamp using the `createdDateTime` property of the channel resource. * Place the new channel in migration mode by setting `channelCreationMode` to `migration`. -#### Request for creating a channel in migration mode +#### Request (create a channel in migration state) ```HTTP POST https://graph.microsoft.com/v1.0/teams/{team-id}/channels @@ -177,12 +181,15 @@ HTTP/1.1 202 Accepted #### Error message -The following error message is visible if `createdDateTime` is set for future; or `createdDateTime` is correctly specified, but `channelCreationMode` instance attribute is missing or set to an invalid value. - ```HTTP 400 Bad Request ``` +You can receive the error message in the following scenarios: + +* If `createdDateTime` is set for future. +* If `createdDateTime` is correctly specified but `channelCreationMode` instance attribute is missing or set to invalid value. + Once you've created a new team and standard channel, complete migration with the following steps: 1. [Check migration status](#step-2-check-migration-status) @@ -201,7 +208,7 @@ In this scenario, use the `startMigration` API to enable migration mode on exist To enable migration mode on existing channels, refer the following. -##### Request for existing channel migration +##### Request (use existing channel in migration state) ```HTTP POST https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}/startMigration @@ -236,7 +243,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 To enable migration mode on existing chats, refer the following. -##### Request for existing chat migration +##### Request (use existing chat in migration state) ```HTTP POST https://graph.microsoft.com/beta/chats/{chat-id}/startMigration @@ -291,7 +298,7 @@ Now you can import back-in-time messages by including the `createdDateTime` and > * `createdDateTime` must be unique across messages in the same thread. > * `createdDateTime` supports timestamps with milliseconds precision. For example, if the incoming request message has `createdDateTime` set to *2020-09-16T05:50:31.0025302Z*, the API converts it to *2020-09-16T05:50:31.002Z* when ingesting the message. -### Request to post message that is text-only +### Request (POST message that is text-only) ```http POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages @@ -362,7 +369,7 @@ You receive the following error message if you set the `createdDateTime` propert 400 Bad Request ``` -#### Request to post a message with inline image +#### Request (POST message with an inline image) > [!NOTE] > @@ -426,7 +433,7 @@ HTTP/1.1 200 OK } ``` -## Step 4: Complete migration +## Step 4: Complete migration mode Use `completeMigration` API to finish the migration process for new and existing channels and chats. For more information, see: @@ -437,7 +444,7 @@ Use `completeMigration` API to finish the migration process for new and existing Use `completeMigration` API to complete migration for the new team and channel. This opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team message migration is completed, migration on all channels must be completed. -#### Request to end channel migration +#### Request (end channel migration mode) ```http POST https://graph.microsoft.com/beta/teams/team-id/channels/channel-id/completeMigration @@ -449,7 +456,7 @@ POST https://graph.microsoft.com/beta/teams/team-id/channels/channel-id/complete HTTP/1.1 204 NoContent ``` -#### Request to end team migration +#### Request (end team migration mode) ```http POST https://graph.microsoft.com/beta/teams/team-id/completeMigration @@ -463,35 +470,15 @@ HTTP/1.1 204 NoContent ### Add team members -You can add a single member to a team using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9) or Microsoft Graph [add member](/graph/api/group-post-members?view=graph-rest-beta&tabs=http&preserve-view=true) API. - -#### Request to add a member - -```http -POST https://graph.microsoft.com/beta/teams/{team-id}/members -Content-type: application/json -Content-length: 30 - -{ - "@odata.type": "#microsoft.graph.aadUserConversationMember", - "roles": [], - "user@odata.bind": "https://graph.microsoft.com/beta/users/{user-id}" -} -``` - -#### Response - -```http -HTTP/1.1 204 No Content -``` +After completing migration of external messages, you can add a single member to a team using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9)., You can also use Microsoft Graph to [add single member](/graph/api/team-post-members?view=graph-rest-1.0&branch=pr-en-us-26836&tabs=http) or [add members in bulk](/graph/api/conversationmembers-add?view=graph-rest-1.0&tabs=http) -Once you've completed new team and channel migration, go to [Step 5: Verify migration mode completion](#step-5-verify-migration-mode-completion). +Once you've completed new team and channel migration, [verify migration mode completion](#step-5-verify-migration-mode-completion). ### Complete existing channel or chat migration For existing channels or chats already in migration mode, use the `completeMigration` API to mark the migration state as completed. This process ensures that the channel or chat remains permanently available instead of being dropped after migration. -#### Request to complete existing channel migration +#### Request (complete existing channel migration) ```HTTP POST https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}/completeMigration @@ -504,7 +491,7 @@ POST https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}/comp HTTP/1.1 204 NoContent ``` -#### Request to complete existing chat migration +#### Request (complete existing chat migration) ```HTTP POST https://graph.microsoft.com/beta/chats/{chat-id}/completeMigration From 6cca8502c2889883bf8114d7ed2b6021527cf28e Mon Sep 17 00:00:00 2001 From: SukanyaDas-MSFT Date: Tue, 18 Nov 2025 21:05:37 +0530 Subject: [PATCH 62/72] Update --- .../import-external-messages-to-teams.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 1b77d2ccf27..f2d5883c203 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -26,23 +26,25 @@ With Microsoft Graph, you can migrate users' existing message history and data f ## Supported channel and chat types -You can migrate user's existing message history and data from an external system either in a new team and standard channel or in an existing team, channel, or chat. +The supported channel and chat types for migrating external messages to teams are as\s follows: -* **New team and standard channel**: Create a new team and its standard channels in migration mode to import content. To enable `migrationMode` for a new standard team and channel, see [Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode). -This allows you to import the exact structure of your external system into the new channel. +* **New team and standard channel**: Create a new team and its standard channels in migration mode to import content. This allows you to import the exact structure of your external system into the new channel. +To enable `migrationMode` for a new standard team and channel, see [Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode). -* **Existing team, channel or chat**: Use any team, channel or chat that already exists in Teams, regardless of when you created it. To enable migration mode in an existing channel or chat, see [Existing channel migration](#existing-channel-migration). This allows you to add existing context to channels that are already active in Teams and maintains continuity for ongoing conversations. +* **Existing team, channel or chat**: Use any team, channel or chat that already exists in Teams, regardless of when you created it. This allows you to add existing context to channels that are already active in Teams and maintains continuity for ongoing conversations. +To enable migration mode in an existing channel or chat, see [Existing channel migration](#existing-channel-migration). > [!NOTE] > > * Only standard channels are supported when creating a channel in migration mode from scratch. > * Federated content can't be imported. All imported content must come from the authenticated tenant and only one app can manage a thread at a time. Another app can import content only after the first app completes migration. -`migrationMode` ensure the following till the migration is completed: +`migrationMode` is a special state that prevents certain operations during the data migration process to ensure data integrity. It does the following: * Restricts receipt of new messages to the channel or chat * Prevents adding or removing members during migration * Allows importing historical messages with custom timestamps +* Maintains the original conversation structure and hierarchy ## Content scope for import @@ -106,7 +108,7 @@ In this scenario, create a new team and standard channel under it in migration m > The `createdDateTime` field is only populated for migrated teams or channels. If you update `createdDateTime` to a past timestamp, you can't move it to a future timestamp again. > Migration mode ensures that the original message timestamps are preserved, and prevents new messages from being sent when the migration is in progress. -##### Request (create a team in migration state) +##### Request (create a team in migration mode) ```HTTP POST https://graph.microsoft.com/v1.0/teams @@ -145,7 +147,7 @@ You can receive the error message in the following scenarios: * [Create a new channel](/graph/api/channel-post?view=graph-rest-1.0&viewFallbackFrom=graph-rest-v1.0&tabs=http&preserve-view=true) with a back-in-time timestamp using the `createdDateTime` property of the channel resource. * Place the new channel in migration mode by setting `channelCreationMode` to `migration`. -#### Request (create a channel in migration state) +#### Request (create a channel in migration mode) ```HTTP POST https://graph.microsoft.com/v1.0/teams/{team-id}/channels @@ -199,7 +201,7 @@ Once you've created a new team and standard channel, complete migration with the ### Start migration on existing channels and chats -In this scenario, use the `startMigration` API to enable migration mode on existing channels or chats. `startMigration` sets the migration state to `InProgress` and begins the message import process. For more information, see: +In this scenario, use the `startMigration` API to [enable migration mode](/graph/api/channel-startmigration?view=graph-rest-beta&branch=pr-en-us-26836) on existing channels or chats. `startMigration` sets the migration state to `InProgress` and begins the message import process. For more information, see: * [Existing channel migration](#existing-channel-migration) * [Existing chat migration](#existing-chat-migration) @@ -208,7 +210,7 @@ In this scenario, use the `startMigration` API to enable migration mode on exist To enable migration mode on existing channels, refer the following. -##### Request (use existing channel in migration state) +##### Request (use existing channel in migration mode) ```HTTP POST https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}/startMigration @@ -243,7 +245,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 To enable migration mode on existing chats, refer the following. -##### Request (use existing chat in migration state) +##### Request (existing chat in migration mode) ```HTTP POST https://graph.microsoft.com/beta/chats/{chat-id}/startMigration From 9841cf9344977c9f44e9c0e712002a7232721ee3 Mon Sep 17 00:00:00 2001 From: SukanyaDas-MSFT Date: Tue, 18 Nov 2025 21:30:59 +0530 Subject: [PATCH 63/72] Update import-external-messages-to-teams.md --- .../import-messages/import-external-messages-to-teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index f2d5883c203..0b9e9ec8a50 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -285,7 +285,7 @@ Consider the following important points: ## Step 2: Check migration status -Call `Get channel` or `Get chat` to confirm that the 'migrationMode' state is set to `InProgress`. For more information, see: +Call `Get channel` or `Get chat` to confirm that the `migrationMode` state is set to `InProgress`. For more information, see: * [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) * [Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) From 8aecc362bbcbb82134fb36d33af78e390655e21d Mon Sep 17 00:00:00 2001 From: SukanyaDas-MSFT Date: Tue, 18 Nov 2025 21:34:46 +0530 Subject: [PATCH 64/72] Update import-external-messages-to-teams.md --- .../import-messages/import-external-messages-to-teams.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 0b9e9ec8a50..fd5f9e3bc32 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -444,7 +444,7 @@ Use `completeMigration` API to finish the migration process for new and existing ### Complete new team and channel migration -Use `completeMigration` API to complete migration for the new team and channel. This opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team message migration is completed, migration on all channels must be completed. +Use `completeMigration` API to [complete migration for the new team and channel](/graph/api/chat-completemigration?view=graph-rest-beta&viewFallbackFrom=graph-rest-1.0&branch=pr-en-us-26836). This opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team message migration is completed, migration on all channels must be completed. #### Request (end channel migration mode) @@ -478,7 +478,7 @@ Once you've completed new team and channel migration, [verify migration mode com ### Complete existing channel or chat migration -For existing channels or chats already in migration mode, use the `completeMigration` API to mark the migration state as completed. This process ensures that the channel or chat remains permanently available instead of being dropped after migration. +For existing channels or chats already in migration mode, use the `completeMigration` API to [mark the migration state as completed](/graph/api/channel-completemigration?view=graph-rest-beta&branch=pr-en-us-26836&tabs=http). This process ensures that the channel or chat remains permanently available instead of being dropped after migration. #### Request (complete existing channel migration) From bd4260da97bdb920a31cc4ff950892b3444a39e0 Mon Sep 17 00:00:00 2001 From: SukanyaDas-MSFT Date: Wed, 19 Nov 2025 10:19:45 +0530 Subject: [PATCH 65/72] Update import-external-messages-to-teams.md --- .../import-messages/import-external-messages-to-teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index fd5f9e3bc32..68ae918d7a7 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -31,7 +31,7 @@ The supported channel and chat types for migrating external messages to teams ar * **New team and standard channel**: Create a new team and its standard channels in migration mode to import content. This allows you to import the exact structure of your external system into the new channel. To enable `migrationMode` for a new standard team and channel, see [Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode). -* **Existing team, channel or chat**: Use any team, channel or chat that already exists in Teams, regardless of when you created it. This allows you to add existing context to channels that are already active in Teams and maintains continuity for ongoing conversations. +* **Existing channel or chat**: Use any channel or chat that already exists in Teams, regardless of when you created it. This allows you to add existing context to channels that are already active in Teams and maintains continuity for ongoing conversations. To enable migration mode in an existing channel or chat, see [Existing channel migration](#existing-channel-migration). > [!NOTE] From ce78a766abecd452ead0215537672d72b642b97a Mon Sep 17 00:00:00 2001 From: SukanyaDas-MSFT Date: Wed, 19 Nov 2025 12:07:11 +0530 Subject: [PATCH 66/72] PR final updates-SD --- .../import-external-messages-to-teams.md | 75 +++++++++++++------ 1 file changed, 53 insertions(+), 22 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 68ae918d7a7..1b6dc73dfc9 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -26,12 +26,12 @@ With Microsoft Graph, you can migrate users' existing message history and data f ## Supported channel and chat types -The supported channel and chat types for migrating external messages to teams are as\s follows: +Teams supports migrating external messages to the following channel and chat types: -* **New team and standard channel**: Create a new team and its standard channels in migration mode to import content. This allows you to import the exact structure of your external system into the new channel. +* **New team and standard channel**: Create a new team and its standard channels in migration mode to import content. This approach lets you import the exact structure of your external system into the new channel. To enable `migrationMode` for a new standard team and channel, see [Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode). -* **Existing channel or chat**: Use any channel or chat that already exists in Teams, regardless of when you created it. This allows you to add existing context to channels that are already active in Teams and maintains continuity for ongoing conversations. +* **Existing channel or chat**: Use any channel or chat that already exists in Teams, regardless of when you created it. This approach lets you add existing context to channels that are already active in Teams and maintains continuity for ongoing conversations. To enable migration mode in an existing channel or chat, see [Existing channel migration](#existing-channel-migration). > [!NOTE] @@ -39,12 +39,14 @@ To enable migration mode in an existing channel or chat, see [Existing channel m > * Only standard channels are supported when creating a channel in migration mode from scratch. > * Federated content can't be imported. All imported content must come from the authenticated tenant and only one app can manage a thread at a time. Another app can import content only after the first app completes migration. -`migrationMode` is a special state that prevents certain operations during the data migration process to ensure data integrity. It does the following: +`migrationMode` is a special state that ensures data integrity by preventing the following operations during data migration. -* Restricts receipt of new messages to the channel or chat -* Prevents adding or removing members during migration -* Allows importing historical messages with custom timestamps -* Maintains the original conversation structure and hierarchy +* For new teams and standard channels: + * It restricts receipt of new messages + * It prevents adding or removing members +* For all supported channels and chat types: + * It allows importing historical messages with custom timestamps + * It maintains the original conversation structure and hierarchy ## Content scope for import @@ -68,10 +70,10 @@ The following table provides the content scope for existing channels and chats. ### Analyze and prepare message data -* Review the third-party data to decide what is migrated. +* Review the third-party data to decide what to migrate. * Extract the selected data from the third-party chat system. * Map the third-party chat structure to the Teams structure. -* Convert import data into format needed for migration. +* Convert import data into the format needed for migration. ### Set up your Microsoft 365 tenant @@ -90,7 +92,7 @@ You can import historical messages seamlessly into both existing and newly creat ## Step 1: Start migration -To start migrating a user's message history from any third-party platform to Teams, you can either create a new team and standard channel or use an existing channel or chat. Depending on your scenario, choose either of the two paths: +To start migrating a user's message history from any third-party platform to Teams, you can either create a new team and standard channel or use an existing channel or chat. Depending on your scenario, choose either of the following options: * [Create a team and standard channel in migration mode](#create-a-team-and-standard-channel-in-migration-mode) * [Start migration on existing channels and chats](#start-migration-on-existing-channels-and-chats) @@ -192,7 +194,7 @@ You can receive the error message in the following scenarios: * If `createdDateTime` is set for future. * If `createdDateTime` is correctly specified but `channelCreationMode` instance attribute is missing or set to invalid value. -Once you've created a new team and standard channel, complete migration with the following steps: +After you create a new team and standard channel, complete migration with the following steps: 1. [Check migration status](#step-2-check-migration-status) 1. [Import messages](#step-3-import-messages) @@ -201,16 +203,16 @@ Once you've created a new team and standard channel, complete migration with the ### Start migration on existing channels and chats -In this scenario, use the `startMigration` API to [enable migration mode](/graph/api/channel-startmigration?view=graph-rest-beta&branch=pr-en-us-26836) on existing channels or chats. `startMigration` sets the migration state to `InProgress` and begins the message import process. For more information, see: +On existing channels or chats, use the `startMigration` API to [enable migration mode](/graph/api/channel-startmigration?view=graph-rest-beta&branch=pr-en-us-26836). `startMigration` sets the migration state to `InProgress` and begins the message import process. For more information, see: * [Existing channel migration](#existing-channel-migration) * [Existing chat migration](#existing-chat-migration) #### Existing channel migration -To enable migration mode on existing channels, refer the following. +To enable migration mode on existing channels, use the `startMigration` API. -##### Request (use existing channel in migration mode) +##### Request (existing channel in migration mode) ```HTTP POST https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}/startMigration @@ -243,7 +245,7 @@ POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5 #### Existing chat migration -To enable migration mode on existing chats, refer the following. +To enable migration mode on existing chats, use the `startMigration` API. ##### Request (existing chat in migration mode) @@ -283,6 +285,9 @@ Consider the following important points: * The `creationDateTime` property is optional in a request body. If omitted, the `startMigration` API uses the current date and time as the minimum timestamp. * The `startMigration` API starts the message migration process by setting the migration mode to `InProgress` for a specified channel or chat. +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+5%3A+Add+team+members&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-five-add-team-members&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + ## Step 2: Check migration status Call `Get channel` or `Get chat` to confirm that the `migrationMode` state is set to `InProgress`. For more information, see: @@ -435,16 +440,19 @@ HTTP/1.1 200 OK } ``` +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+5%3A+Add+team+members&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-five-add-team-members&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + ## Step 4: Complete migration mode -Use `completeMigration` API to finish the migration process for new and existing channels and chats. For more information, see: +Use the `completeMigration` API to finish the migration process for new and existing channels and chats. For more information, see: * [Complete new team and channel migration](#complete-new-team-and-channel-migration) * [Complete existing channel or chat migration](#complete-existing-channel-or-chat-migration) ### Complete new team and channel migration -Use `completeMigration` API to [complete migration for the new team and channel](/graph/api/chat-completemigration?view=graph-rest-beta&viewFallbackFrom=graph-rest-1.0&branch=pr-en-us-26836). This opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before the team message migration is completed, migration on all channels must be completed. +Use the `completeMigration` API to [complete migration for the new team and channel](/graph/api/chat-completemigration?view=graph-rest-beta&viewFallbackFrom=graph-rest-1.0&branch=pr-en-us-26836). This action opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before you complete the team message migration, you must complete migration on all channels. #### Request (end channel migration mode) @@ -472,9 +480,29 @@ HTTP/1.1 204 NoContent ### Add team members -After completing migration of external messages, you can add a single member to a team using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9)., You can also use Microsoft Graph to [add single member](/graph/api/team-post-members?view=graph-rest-1.0&branch=pr-en-us-26836&tabs=http) or [add members in bulk](/graph/api/conversationmembers-add?view=graph-rest-1.0&tabs=http) +After completing migration of external messages, you can add a single member to a team by using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9). You can also use Microsoft Graph to [add single member](/graph/api/team-post-members?view=graph-rest-1.0&branch=pr-en-us-26836&tabs=http) or [add members in bulk](/graph/api/conversationmembers-add?view=graph-rest-1.0&tabs=http). + +#### Request (add member) + +```http +POST https://graph.microsoft.com/beta/teams/{team-id}/members +Content-type: application/json +Content-length: 30 + +{ + "@odata.type": "#microsoft.graph.aadUserConversationMember", + "roles": [], + "user@odata.bind": "https://graph.microsoft.com/beta/users/{user-id}" +} +``` + +#### Response + +```http +HTTP/1.1 204 No Content +``` -Once you've completed new team and channel migration, [verify migration mode completion](#step-5-verify-migration-mode-completion). +Once you complete new team and channel migration, [verify migration mode completion](#step-5-verify-migration-mode-completion). ### Complete existing channel or chat migration @@ -508,7 +536,10 @@ HTTP/1.1 204 NoContent ## Step 5: Verify migration mode completion Call [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or -[Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) to verify that the migration mode state is marked as completed. +[Get chat](/graph/api/chat-get?view=graph-rest-1.0&tabs=http&preserve-view=true) to verify that the `migrationMode` is marked as `Completed`. + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Step+5%3A+Add+team+members&&author=%40AkJo&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams%23step-five-add-team-members&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fgraph-api%2Fimport-messages%2Fimport-external-messages-to-teams.md&documentVersionIndependentId=ce77e760-90cf-e6b1-3cec-ae55ee50c33e&platformId=c9cc8ad3-6c28-7c8c-af03-219bbefa1d38&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) ## Tips and additional information @@ -517,7 +548,7 @@ Call [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve * After calling `completeMigration` on an existing channel or chat, you can continue importing messages by using the `startMigration` API. -* You can only add team members to the new Teams after the `completeMigration` request returns a successful response. This is applicable only for the newly created team and standard channel. +* You can only add team members to the new Teams after the `completeMigration` request returns a successful response. This rule applies only to the newly created team and standard channel. * Throttling: Messages import at five RPS per channel. From e24c7c2f61bd9c9b4433b1e04d5f70c1e4c9cebf Mon Sep 17 00:00:00 2001 From: SukanyaDas-MSFT Date: Wed, 19 Nov 2025 12:15:06 +0530 Subject: [PATCH 67/72] Update import-external-messages-to-teams.md --- .../import-messages/import-external-messages-to-teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 1b6dc73dfc9..19bba404bfa 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -19,7 +19,7 @@ With Microsoft Graph, you can migrate users' existing message history and data f | Scope name | Display name | Description | Type | Admin consent required | Entities/APIs covered | |---------- |-------------|-------------|------|----------------|-------------------------| -| Teamwork.Migrate.All | [Manage migration to Microsoft Teams](https://learn.microsoft.com/graph/permissions-reference#teamworkmigrateall)| Creating and managing resources for migration to Teams. | **Application-only** | Yes | POST /team | +| Teamwork.Migrate.All | [Manage migration to Microsoft Teams](/graph/permissions-reference#teamworkmigrateall)| Creating and managing resources for migration to Teams. | **Application-only** | Yes | POST /team | > [!NOTE] > Delegated authentication isn't supported. From 714ec081d69d5f978e310d3a0672269bc6b2a3b5 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Wed, 19 Nov 2025 12:33:48 +0530 Subject: [PATCH 68/72] update to whats new.md --- msteams-platform/whats-new.md | 1 + 1 file changed, 1 insertion(+) diff --git a/msteams-platform/whats-new.md b/msteams-platform/whats-new.md index 5d7003d5698..b077c7cf560 100644 --- a/msteams-platform/whats-new.md +++ b/msteams-platform/whats-new.md @@ -498,6 +498,7 @@ Developer preview is a public program that provides early access to unreleased T | **Date** | **Update** | **Find here** | | -------- | --------- | ---------------- | +| 19/11/2025 | Import messages from third-party platforms into Teams and recreate the user message hierarchy using Microsoft Graph APIs. All new and existing channels and chats are supported. | [Import third-party platform messages to Teams using Microsoft Graph](graph-api/import-messages/import-external-messages-to-teams.md)| | 24/09/2025 | Ad hoc calls (spontaneous, unscheduled meetings) are now receiving enhanced support across Graph APIs. | Build apps for Teams meetings and calls > Get meetings, transcripts, recordings and AI summaries > [Meeting transcripts and recordings](graph-api/meeting-transcripts/overview-transcripts.md)| | 18/09/2025 | Teams AI library supports Python in developer preview. It provides a simplified SDK, support for Model Context Protocol (MCP), Agent-to-Agent communication (A2A), and streamlined tools to enable developers to build intelligent agents for Teams. | [Teams AI library](/microsoftteams/platform/teams-ai-library/welcome) | | 10/04/2025 | Introducing custom engine agents support for Microsoft 365 Copilot Chat. | Build bots and agents > Teams AI library v1 > [Build with Teams AI library](bots/how-to/teams-conversational-ai/how-conversation-ai-get-started.md#add-support-for-microsoft-365-copilot-chat) | From 2e77e6acf5f470e69f801d14c9f969c806e93f9f Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Wed, 19 Nov 2025 12:46:58 +0530 Subject: [PATCH 69/72] fixed warnings --- .../import-messages/import-external-messages-to-teams.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 19bba404bfa..34ff9d09b23 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -203,7 +203,7 @@ After you create a new team and standard channel, complete migration with the fo ### Start migration on existing channels and chats -On existing channels or chats, use the `startMigration` API to [enable migration mode](/graph/api/channel-startmigration?view=graph-rest-beta&branch=pr-en-us-26836). `startMigration` sets the migration state to `InProgress` and begins the message import process. For more information, see: +On existing channels or chats, use the `startMigration` API to [enable migration mode](/graph/api/channel-startmigration?view=graph-rest-beta&branch=pr-en-us-26836&preserve-view=true ). `startMigration` sets the migration state to `InProgress` and begins the message import process. For more information, see: * [Existing channel migration](#existing-channel-migration) * [Existing chat migration](#existing-chat-migration) @@ -452,7 +452,7 @@ Use the `completeMigration` API to finish the migration process for new and exis ### Complete new team and channel migration -Use the `completeMigration` API to [complete migration for the new team and channel](/graph/api/chat-completemigration?view=graph-rest-beta&viewFallbackFrom=graph-rest-1.0&branch=pr-en-us-26836). This action opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before you complete the team message migration, you must complete migration on all channels. +Use the `completeMigration` API to [complete migration for the new team and channel](/graph/api/chat-completemigration?view=graph-rest-beta&viewFallbackFrom=graph-rest-1.0&branch=pr-en-us-26836&preserve-view=true ). This action opens the team and channel resources for general use by team members. The action is bound to the `team` instance. Before you complete the team message migration, you must complete migration on all channels. #### Request (end channel migration mode) @@ -480,7 +480,7 @@ HTTP/1.1 204 NoContent ### Add team members -After completing migration of external messages, you can add a single member to a team by using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9). You can also use Microsoft Graph to [add single member](/graph/api/team-post-members?view=graph-rest-1.0&branch=pr-en-us-26836&tabs=http) or [add members in bulk](/graph/api/conversationmembers-add?view=graph-rest-1.0&tabs=http). +After completing migration of external messages, you can add a single member to a team by using the [Teams UI](https://support.microsoft.com/en-us/office/add-members-to-a-team-in-microsoft-teams-aff2249d-b456-4bc3-81e7-52327b6b38e9&preserve-view=true ). You can also use Microsoft Graph to [add single member](/graph/api/team-post-members?view=graph-rest-1.0&branch=pr-en-us-26836&tabs=http&preserve-view=true ) or [add members in bulk](/graph/api/conversationmembers-add?view=graph-rest-1.0&tabs=http&preserve-view=true ). #### Request (add member) @@ -506,7 +506,7 @@ Once you complete new team and channel migration, [verify migration mode complet ### Complete existing channel or chat migration -For existing channels or chats already in migration mode, use the `completeMigration` API to [mark the migration state as completed](/graph/api/channel-completemigration?view=graph-rest-beta&branch=pr-en-us-26836&tabs=http). This process ensures that the channel or chat remains permanently available instead of being dropped after migration. +For existing channels or chats already in migration mode, use the `completeMigration` API to [mark the migration state as completed](/graph/api/channel-completemigration?view=graph-rest-beta&branch=pr-en-us-26836&tabs=http&preserve-view=true ). This process ensures that the channel or chat remains permanently available instead of being dropped after migration. #### Request (complete existing channel migration) From d30781cfceb5d8bd8fe9077c40e4039a80823fc4 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 20 Nov 2025 12:31:15 +0530 Subject: [PATCH 70/72] updated the new optional step --- .../import-external-messages-to-teams.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 34ff9d09b23..7bc01dc4c86 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -10,7 +10,7 @@ ms.date: 11/17/2025 # Import third-party platform messages to Teams using Microsoft Graph -With Microsoft Graph, you can migrate users' existing message history and data from an external system into Teams. By enabling the recreation of a third-party platform messaging hierarchy inside Teams, users can continue their communications in a seamless manner and proceed without interruption. +With Microsoft Graph, you can migrate users' existing message history and data from an external system into Teams. Users can continue their communications in a seamless manner and proceed without interruption by enabling the recreation of a third-party platform messaging hierarchy inside Teams. > [!NOTE] > In the future, Microsoft might require you or your customers to pay extra fees based on the amount of data imported. @@ -533,6 +533,22 @@ POST https://graph.microsoft.com/beta/chats/{chat-id}/completeMigration HTTP/1.1 204 NoContent ``` +#### Optional: Update group chat member history after migration + +When you complete message migration in a group chat, you can optionally update members’ share history by using the `visibleHistoryStartDateTime` property in Microsoft Graph. This property defines the earliest point in time from which a chat member can view messages in a conversation. If imported messages are earlier than the member’s, they don’t appear unless you update this value. + +To update the `visibleHistoryStartDateTime` property: + +1. [Remove the member](/graph/api/chat-delete-members?view=graph-rest-1.0&tabs=http) from the chat. +1. [Add the member](/graph/api/chat-post-members?view=graph-rest-1.0&tabs=http) back with a new `visibleHistoryStartDateTime` that includes the imported messages. + +##### Example + +For a member A, if the chat was created at 10 PM, messages imported at 9 AM, and member A’s share history starts at 10 AM, then: + +1. Remove member A from the chat. +1. Add member A with `visibleHistoryStartDateTime` set before 9 AM. + ## Step 5: Verify migration mode completion Call [Get channel](/graph/api/channel-get?view=graph-rest-1.0&tabs=http&preserve-view=true) or From 7ef9f68ecec7b4a9852a5cd19a7c1086a21bbf6c Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 20 Nov 2025 12:35:29 +0530 Subject: [PATCH 71/72] fixed warning --- .../import-messages/import-external-messages-to-teams.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index 7bc01dc4c86..c87540cb459 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -539,8 +539,8 @@ When you complete message migration in a group chat, you can optionally update m To update the `visibleHistoryStartDateTime` property: -1. [Remove the member](/graph/api/chat-delete-members?view=graph-rest-1.0&tabs=http) from the chat. -1. [Add the member](/graph/api/chat-post-members?view=graph-rest-1.0&tabs=http) back with a new `visibleHistoryStartDateTime` that includes the imported messages. +1. [Remove the member](/graph/api/chat-delete-members?view=graph-rest-1.0&tabs=http&preserve-view=true) from the chat. +1. [Add the member](/graph/api/chat-post-members?view=graph-rest-1.0&tabs=http&preserve-view=true) back with a new `visibleHistoryStartDateTime` that includes the imported messages. ##### Example From 943225a8b6572a1d1602c9278fa0346283e9cc98 Mon Sep 17 00:00:00 2001 From: NehaHEDAU-MSFT Date: Thu, 20 Nov 2025 15:15:51 +0530 Subject: [PATCH 72/72] re-worded the example --- .../import-messages/import-external-messages-to-teams.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md index c87540cb459..4b411b0c6e5 100644 --- a/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md +++ b/msteams-platform/graph-api/import-messages/import-external-messages-to-teams.md @@ -535,7 +535,7 @@ HTTP/1.1 204 NoContent #### Optional: Update group chat member history after migration -When you complete message migration in a group chat, you can optionally update members’ share history by using the `visibleHistoryStartDateTime` property in Microsoft Graph. This property defines the earliest point in time from which a chat member can view messages in a conversation. If imported messages are earlier than the member’s, they don’t appear unless you update this value. +When you complete message migration in a group chat, you can optionally update members’ share history by using the `visibleHistoryStartDateTime` property in Microsoft Graph. This property sets the earliest time a chat member can view messages in a conversation. If imported messages are older than the property's value, they don’t appear unless you update the property. To update the `visibleHistoryStartDateTime` property: @@ -544,10 +544,11 @@ To update the `visibleHistoryStartDateTime` property: ##### Example -For a member A, if the chat was created at 10 PM, messages imported at 9 AM, and member A’s share history starts at 10 AM, then: +Consider a scenario where the original chat was created at 10 PM, updated at 1 AM, messages were imported at 9 AM, and member A’s share history starts at 10 AM. +To ensure that member A can see the 9 AM imported messages: 1. Remove member A from the chat. -1. Add member A with `visibleHistoryStartDateTime` set before 9 AM. +1. Add member A with the `visibleHistoryStartDateTime` property set before 9 AM. ## Step 5: Verify migration mode completion