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..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 @@ -1,64 +1,118 @@ --- -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. +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: "akjo" +author: "surbhigupta" ms.topic: overview -ms.owner: vishachadha -ms.date: 09/02/2022 +ms.owner: mehakagarwal +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. 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 may require you or your customers to pay additional 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. -## Import overview +## Permissions -At a high level, the import process consists of the following: +| Scope name | Display name | Description | Type | Admin consent required | Entities/APIs covered | +|---------- |-------------|-------------|------|----------------|-------------------------| +| 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 | -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). +> [!NOTE] +> Delegated authentication isn't supported. + +## Supported channel and chat types + +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 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 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] +> +> * 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 ensures data integrity by preventing the following operations during data migration. + +* 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 + +The following table provides the content scope for existing channels and chats. + +|In-scope | Out-of-scope| +|----------|--------------------------| +|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 (Microsoft 365) SharePoint Online (SPO) or OneDrive (OD)|Stickers| +|Messages with rich text|Cross posts between channels| +|Message reply chain|Quotes| +|High throughput processing|| +|1:1 and group chat messages|| +|Standard, private, and shared channel messages|| +|Up to 250 reactions|| +|@mentions and emojis|| ## 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. +* 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 the 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. +* 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. -## Step 1: Create a team +## Import historical messages into Teams -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: +You can import historical messages seamlessly into both existing and newly created channels or chats by performing the following steps: -> [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. [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 mode](#step-4-complete-migration-mode) +1. [Verify migration mode completion](#step-5-verify-migration-mode-completion) -> [!NOTE] -> The `createdDateTime` field is only populated for instances of a team or channel that are migrated. +## 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 following options: -#### Permission +* [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) -|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`| +### Create a team and standard channel in migration mode -#### Request (create a team in migration state) +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. -```http +#### 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`. + +> [!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 when the migration is in progress. + +##### Request (create a team in migration mode) + +```HTTP POST https://graph.microsoft.com/v1.0/teams Content-Type: application/json @@ -71,17 +125,17 @@ Content-Type: application/json } ``` -#### Response +##### Response -```http +```HTTP HTTP/1.1 202 Accepted Location: /teams/{team-id}/operations/{operation-id} Content-Location: /teams/{team-id} ``` -#### Error message +##### Error message -```http +```HTTP 400 Bad Request ``` @@ -90,25 +144,14 @@ 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 +#### Create a new 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-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`. -> [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 +#### Request (create a channel in migration mode) -|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 +```HTTP POST https://graph.microsoft.com/v1.0/teams/{team-id}/channels Content-Type: application/json @@ -123,7 +166,7 @@ Content-Type: application/json #### Response -```http +```HTTP HTTP/1.1 202 Accepted { @@ -142,7 +185,7 @@ HTTP/1.1 202 Accepted #### Error message -```http +```HTTP 400 Bad Request ``` @@ -151,20 +194,118 @@ 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. +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) +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 + +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) + +#### Existing channel migration + +To enable migration mode on existing channels, use the `startMigration` API. + +##### Request (existing channel in migration mode) + +```HTTP +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. +>The `conversationCreationDateTime` value 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 HTTP response. + +```http +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 +{ +“conversationCreationDateTime”: “2024-01-01T00:00:00Z” +} + +``` + +#### Existing chat migration + +To enable migration mode on existing chats, use the `startMigration` API. + +##### Request (existing chat in migration mode) + +```HTTP +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. +>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 HTTP response. + +```http +HTTP/1.1 204 No Content +``` + +##### Example + +```HTTP +POST https://graph.microsoft.com/beta/teams/57fb72d0-d811-46f4-8947-305e6072eaa5/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration + +{ +“conversationCreationDateTime”: “2024-01-01T00:00:00Z” +} + +``` + +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. + > [!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) +> [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: + +* [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 -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. +Now you can import back-in-time messages by including the `createdDateTime` and `from` keys in the request body. > [!NOTE] > -> * Messages imported with `createdDateTime` earlier than the message thread `createdDateTime` is not supported. +> * 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 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*, the API converts it to *2020-09-16T05:50:31.002Z* when ingesting the message. -#### Request (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 @@ -174,7 +315,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" } }, @@ -185,7 +326,7 @@ POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages } ``` -#### Response +### Response ```http HTTP/1.1 200 OK @@ -227,13 +368,15 @@ HTTP/1.1 200 OK } ``` -#### Error message +### Error message + +You receive the following error message if you set the `createdDateTime` property to a future date and time. ```http 400 Bad Request ``` -#### Request (POST a message with inline image) +#### Request (POST message with an inline image) > [!NOTE] > @@ -258,7 +401,7 @@ POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages } ``` -#### Response +### Response ```http HTTP/1.1 200 OK @@ -283,7 +426,7 @@ HTTP/1.1 200 OK "conversation": null, "user": { "id": "id-value", - "displayName": "Joh Doe", + "displayName": "John Doe", "userIdentityType": "aadUser" } }, @@ -296,17 +439,25 @@ 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) +> [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 -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. +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 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) ```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 @@ -318,7 +469,7 @@ HTTP/1.1 204 NoContent #### Request (end team migration mode) ```http -POST https://graph.microsoft.com/v1.0/teams/team-id/completeMigration +POST https://graph.microsoft.com/beta/teams/team-id/completeMigration ``` #### Response @@ -327,15 +478,9 @@ POST https://graph.microsoft.com/v1.0/teams/team-id/completeMigration 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 +### 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: +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) @@ -357,6 +502,59 @@ Content-length: 30 HTTP/1.1 204 No Content ``` +Once you complete 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](/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) + +```HTTP +POST https://graph.microsoft.com/beta/teams/{team-id}/channels/{channel-id}/completeMigration + +``` + +#### Response + +```http +HTTP/1.1 204 NoContent +``` + +#### Request (complete existing chat migration) + +```HTTP +POST https://graph.microsoft.com/beta/chats/{chat-id}/completeMigration +``` + +#### Response + +```http +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 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: + +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 + +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 the `visibleHistoryStartDateTime` property 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 +[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) @@ -365,37 +563,22 @@ HTTP/1.1 204 No Content -* After the `completeMigration` request is made, you can't import further messages into the team. +* 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 team after the `completeMigration` request has returned a successful response. +* 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. -* 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. +## Code sample -##### 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| - +| 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 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) |