[Doc Feature] [ADO 4595639] New Draft for Migrating External Message to Teams

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)

msteams-platform/graph-api/import-messages/import-external-platform-messages-to-teams.md

@@ -0,0 +1,329 @@
+---
+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: "surbhigupta"
+ms.topic: overview
+ms.owner: mehakagarwal
+ms.date: 09/30/2025
+---
+
+# Import external platform messages to Teams via 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.
+
+> [!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|
+|---------|---------|---------|---------|
+| `Teamwork.Migrate.All`|  Manage migration to Microsoft Teams | Application-only  |`POST /teams`|
+
+### 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
+
+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. [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)
+
+## Step 1: Create 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.
+
+## 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.
+
+### [Channel migration](#tab/channelmigration)
+
+#### Channel request
+
+```HTTP
+POST  /teams/{team-id}/channels/{channel-id}/startMigration
+{
+
+"conversationcreationDateTime": "2024-01-01T00:00:00Z"
+}
+```
+
+`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:
+
+```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:[email protected]/startMigration
+{
+“conversationcreationDateTime”: “2024-01-01T00:00:00Z”
+}
+
+```
+
+### [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
+
+```HTTP
+POST   /chats/{chat-id}/startMigration 
+{
+
+"conversationcreationDateTime": "2024-01-01T00:00:00Z"
+}
+```
+
+#### Chat response
+
+If the request is successful, the method returns the following status:
+
+```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:[email protected]/startMigration 
+
+{ 
+“conversationcreationDateTime”: “2024-01-01T00:00:00Z” 
+} 
+
+```
+
+---
+
+## 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:
+
+* [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.
+
+> [!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": "<div><div>\n<div><span><img height=\"250\" src=\"../hostedContents/1/$value\" width=\"176.2295081967213\" style=\"vertical-align:bottom; width:176px; height:250px\"></span>\n\n</div>\n\n\n</div>\n</div>"
+    },
+    "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": "<div><div>\n<div><span><img height=\"250\" src=\"https://graph.microsoft.com/teams/teamId/channels/channelId/messages/id-value/hostedContents/hostedContentId/$value\" width=\"176.2295081967213\" style=\"vertical-align:bottom; width:176px; height:250px\"></span>\n\n</div>\n\n\n</div>\n</div>"
+    },
+    "attachments": [],
+    "mentions": [],
+    "reactions": []
+}
+```
+
+## Step 5: Complete channel and chat migration
+
+Use the `completeMigration` API to finish the migration process for both new and existing channels and chats, as follows:
+
+### 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, 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
+
+```HTTP
+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.
+
+### 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)