Merge pull request #28896 from microsoftgraph/main

Off schedule merge for Evan Park.

Author: Danipocket

api-reference/beta/api/channel-completemigration.md

@@ -20,6 +20,8 @@ Consider the following points when completing migration for new and existing cha
 
 - When a channel is created in migration mode for the initial import flow, the property **migrationMode** for a [channel](../resources/channel.md) in a team is updated to `completed` instead of being dropped, and the state is permanently marked for chats or channels. Migration mode is a special state that prevents certain operations, such as sending messages and adding members, during the data migration process. The parent team isn't marked with migration mode, as teams can't enter migration mode; only their child channels (general, standard, private, and shared) can.
 - For *existing* channels that are already in migration mode, the API completes the message migration process by updating **migrationMode** to `completed` for a [channel](../resources/channel.md) in a team.
+- The application that calls **completeMigration** must be the same application that initiated the migration session by calling [startMigration](channel-startmigration.md) on the target channel. This is the same application that is allowed to call [import message](channel-post-messages.md#example-2-import-a-message) during the migration session.
+- Calling **completeMigration** removes the import mode banner visible to Teams client users, making the channel fully available again.
 
 After a **completeMigration** request is made for existing or new channels, you can still import more messages into the team by calling [channel: startMigration](channel-startmigration.md).
 
@@ -193,7 +195,7 @@ HTTP/1.1 400 Bad Request
 ## Related content
 
 - [channel: startMigration](channel-startmigration.md)
-- [Import message with older timestamp](channel-post-messages.md#example-2-import-messages).
+- [Import a message](channel-post-messages.md#example-2-import-a-message)
 - [Get channel migration status](channel-get.md#example-1-get-a-channel).
 - [chat: completeMigration](chat-completemigration.md)
 - [chat: startMigration](chat-startmigration.md)

api-reference/beta/api/channel-post-messages.md

@@ -16,7 +16,9 @@ Namespace: microsoft.graph
 
 Send a new [chatMessage](../resources/chatmessage.md) in the specified [channel](../resources/channel.md).
 
-> **Note**: It is a violation of the [terms of use](/legal/microsoft-apis/terms-of-use) to use Microsoft Teams as a log file. Only send messages that people will read.
+> **Notes**: 
+> - We don't recommend that you use this API for data migration via the standard create message flow. For data migration scenarios, use the [import messages](/graph/teams-import-messages) flow instead.
+> - It's a violation of the [terms of use](/legal/microsoft-apis/terms-of-use) to use Microsoft Teams as a log file. Only send messages that people will read.
 
 [!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
 
@@ -172,13 +174,17 @@ Content-type: application/json
 }
 ```
 
-### Example 2: Import messages
+### Example 2: Import a message
+The following example shows how to import a message. For more information, see [Import messages into Microsoft Teams chats and channels using Microsoft Graph](/graph/teams-import-messages).
 
-> **Note**: The permission scope `Teamwork.Migrate.All` is required for this scenario.
+> **Note**: The permission scope `Teamwork.Migrate.All` is required for this scenario. The target channel must be in migration mode. The **from** property attributes the message to a user in the same tenant as the authenticated application. The **createdDateTime** value must be later than the channel **createdDateTime** and must not be in the future.
+
+> [!IMPORTANT]
+> The **createdDateTime** must be unique down to the millisecond within the target channel. If a message with the same **createdDateTime** exists, the request fails with `409 Conflict`. Adjust the **createdDateTime** and retry. For more information, see [Import messages into Microsoft Teams chats and channels using Microsoft Graph](/graph/teams-import-messages).
 
 #### Request
 
-The following example shows how to import back-in-time messages using the `createDateTime` and `from` keys in the request body.
+The following example shows how to import back-in-time messages using the **createdDateTime** and **from** properties in the request body.
 
 
 # [HTTP](#tab/http)
@@ -283,7 +289,7 @@ HTTP/1.1 200 OK
 }
 ```
 
-### Example 3: Import messages with inline images
+### Example 3: Import a message with inline images
 
 > [!NOTE]
 > Currently, inline images are the only media type supported by the import message API schema.

api-reference/beta/api/channel-startmigration.md

@@ -18,6 +18,10 @@ Start the migration of external messages by enabling migration mode in an existi
 
 Users are also allowed to define a minimum timestamp for content to be migrated, allowing them to import messages from the past. The provided timestamp must be older than the current **createdDateTime** for a [channel](../resources/channel.md). The provided timestamp is used to replace the existing **createdDateTime** of the [channel](../resources/channel.md).
 
+> [!NOTE]
+> - The application that calls **startMigration** owns the migration session end to end. The same application must call [import message](channel-post-messages.md#example-2-import-a-message) and [completeMigration](channel-completemigration.md) for the same thread. No other application can invoke these APIs on the thread until the owning application completes the migration.
+> - Once a channel enters migration mode, a banner is displayed in the Teams client that indicates the conversation is in import mode. This banner remains visible until migration is completed by [completeMigration](channel-completemigration.md).
+
 [!INCLUDE [channel-support](../../includes/supported-channels-for-import.md)]
 
 [!INCLUDE [national-cloud-support](../../includes/global-only.md)]
@@ -191,7 +195,7 @@ HTTP/1.1 400 Bad Request
 ## Related content
 
 - [channel: completeMigration](channel-completemigration.md)
-- [Import message with older timestamp](channel-post-messages.md#example-2-import-messages).
+- [Import a message](channel-post-messages.md#example-2-import-a-message).
 - [Get channel migration status](channel-get.md#example-1-get-a-channel).
 - [chat: completeMigration](chat-completemigration.md)
 - [chat: startMigration](chat-startmigration.md)

api-reference/beta/api/chat-completemigration.md

@@ -18,6 +18,10 @@ Complete the migration of external messages by removing migration mode from a [c
 
 After a **completeMigration** request is made for an existing or new chat, you can start a migration session by calling [chat: startMigration](chat-startmigration.md).
 
+> [!NOTE]
+> - The application that calls **completeMigration** must be the same application that initiated the migration session by calling [startMigration](chat-startmigration.md) on the target chat. This is the same application that is allowed to call [import message](chat-post-messages.md#example-2-import-a-message) during the migration session.
+> - Calling **completeMigration** removes the import mode banner visible to Teams client users, making the chat fully available again.
+
 [!INCLUDE [chat-support](../../includes/supported-chats-for-import.md)]
 
 [!INCLUDE [national-cloud-support](../../includes/global-only.md)]
@@ -189,7 +193,7 @@ HTTP/1.1 400 Bad Request
 ## Related content
 
 - [chat: startMigration](chat-startmigration.md)
-- [Import message with older timestamp](channel-post-messages.md#example-2-import-messages)
+- [Import a message](chat-post-messages.md#example-2-import-a-message).
 - [Get message import status](chatmessage-get.md)
 - [channel: completeMigration](channel-completemigration.md)
 - [channel: startMigration](channel-startmigration.md)

api-reference/beta/api/chat-post-messages.md

@@ -16,9 +16,9 @@ Namespace: microsoft.graph
 
 Send a new [chatMessage](../resources/chatmessage.md) in the specified [chat](../resources/chat.md). This API cannot create a new chat; you must use the [list chats](chat-list.md) method to retrieve the ID of an existing chat before creating a chat message.
 
-> **Note**: We don't recommend that you use this API for data migration. It does not have the throughput necessary for a typical migration.
-
-> **Note**: It is a violation of the [terms of use](/legal/microsoft-apis/terms-of-use) to use Microsoft Teams as a log file. Only send messages that people will read.
+> **Notes**: 
+> - We don't recommend that you use this API for data migration via the standard create message flow. For data migration scenarios, use the [import messages](/graph/teams-import-messages) flow instead.
+> - It's a violation of the [terms of use](/legal/microsoft-apis/terms-of-use) to use Microsoft Teams as a log file. Only send messages that people will read.
 
 [!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
 
@@ -54,8 +54,8 @@ If successful, this method returns a `201 Created` response code and a new [chat
 ## Examples
 
 For a more comprehensive list of examples, see [Create chatMessage in a channel or a chat](chatmessage-post.md).
-
-### Request
+### Example 1: Create a chatMessage
+#### Request
 
 The following example shows a request.
 
@@ -107,7 +107,7 @@ Content-type: application/json
 
 ---
 
-### Response
+#### Response
 
 The following example shows the response.
 
@@ -162,6 +162,95 @@ Content-type: application/json
 }
 ```
 
+### Example 2: Import a message
+
+The following example shows how to import a message. For more information, see [Import messages into Microsoft Teams chats and channels using Microsoft Graph](/graph/teams-import-messages).
+
+> **Note**: The permission scope `Teamwork.Migrate.All` is required for this scenario. The target chat must be in migration mode.
+
+> [!IMPORTANT]
+> The **createdDateTime** must be unique down to the millisecond within the target chat. If a message with the same **createdDateTime** exists, the request fails with `409 Conflict`. Adjust the **createdDateTime** and retry. For more information, see [Import messages into Microsoft Teams chats and channels using Microsoft Graph](/graph/teams-import-messages).
+
+#### Request
+
+The following example shows how to import a message into a chat on behalf of a user using the **createdDateTime** and **from** properties in the request body.
+
+<!-- {
+  "blockType": "request",
+  "name": "import_chatmessage",
+  "sampleKeys": ["19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2"]
+}-->
+
+```http
+POST https://graph.microsoft.com/beta/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/messages
+
+{
+   "createdDateTime": "2019-02-04T19:58:15.511Z",
+   "from": {
+      "user": {
+         "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
+         "displayName": "Robin Kline",
+         "userIdentityType": "aadUser"
+      }
+   },
+   "body": {
+      "contentType": "html",
+      "content": "Hello World"
+   }
+}
+```
+
+#### Response
+
+The following example shows the response.
+
+<!-- {
+  "blockType": "response",
+  "truncated": true,
+  "@odata.type": "microsoft.graph.chatMessage"
+} -->
+
+```http
+HTTP/1.1 200 OK
+
+{
+    "@odata.context": "https://graph.microsoft.com/beta/$metadata#chats('19%3A4b6bed8d24574f6a9e436813cb2617d8%40thread.tacv2')/messages/$entity",
+    "id": "1616991463150",
+    "replyToId": null,
+    "etag": "1616991463150",
+    "messageType": "message",
+    "createdDateTime": "2019-02-04T19:58:15.511Z",
+    "lastModifiedDateTime": null,
+    "deletedDateTime": null,
+    "subject": null,
+    "summary": null,
+    "chatId": "19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2",
+    "importance": "normal",
+    "locale": "en-us",
+    "webUrl": null,
+    "channelIdentity": null,
+    "policyViolation": null,
+    "eventDetail": null,
+    "from": {
+        "application": null,
+        "device": null,
+        "conversation": null,
+        "user": {
+            "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
+            "displayName": "Robin Kline",
+            "userIdentityType": "aadUser"
+        }
+    },
+    "body": {
+        "contentType": "html",
+        "content": "Hello World"
+    },
+    "attachments": [],
+    "mentions": [],
+    "reactions": []
+}
+```
+
 <!-- uuid: 16cd6b66-4b1a-43a1-adaf-3a886856ed98
 2019-02-04 14:57:30 UTC -->
 <!-- {

api-reference/beta/api/chat-startmigration.md

@@ -21,6 +21,10 @@ You can define a minimum timestamp for content migration that enables the import
 - The **createdDateTime** can only be moved towards the past.
 - The **createdDateTime** can't be updated to a value newer than the current **createdDateTime**.
 
+> [!NOTE]
+> - The application that calls **startMigration** owns the migration session end to end. The same application must call [import message](chat-post-messages.md#example-2-import-a-message) and [completeMigration](chat-completemigration.md) for the same thread. No other application can invoke these APIs on the thread until the owning application completes the migration.
+> - Once a chat enters migration mode, a banner is displayed in the Teams client that indicates the conversation is in import mode. This banner remains visible until migration is completed by [completeMigration](chat-completemigration.md).
+
 [!INCLUDE [chat-support](../../includes/supported-chats-for-import.md)]
 
 [!INCLUDE [national-cloud-support](../../includes/global-only.md)]
@@ -51,7 +55,7 @@ In the request body, supply a JSON representation of the following parameters.
 
 | Parameter       | Type | Description |
 |:---------------|:--------|:--------|
-|conversationCreationDateTime|DateTimeOffset|The minimum timestamp for the messages to be migrated. The timestamp must be older than the current **createdDateTime** of the channel. If not provided, the current date and time is used. Optional.|
+|conversationCreationDateTime|DateTimeOffset|The minimum timestamp for the messages to be migrated. The timestamp must be older than the current **createdDateTime** of the chat. If not provided, the current date and time is used. Optional.|
 
 ## Response
 
@@ -197,7 +201,7 @@ HTTP/1.1 400 Bad Request
 ## Related content
 
 - [chat: completeMigration](chat-completemigration.md)
-- [Import message with older timestamp](channel-post-messages.md#example-2-import-messages)
+- [Import a message](chat-post-messages.md#example-2-import-a-message).
 - [Get message import status](chatmessage-get.md)
 - [channel: completeMigration](channel-completemigration.md)
 - [channel: startMigration](channel-startmigration.md)

api-reference/beta/api/chatmessage-post-replies.md

@@ -16,7 +16,9 @@ Namespace: microsoft.graph
 
 Send a new reply to a [chatMessage](../resources/chatmessage.md) in a specified [channel](../resources/channel.md).
 
-> **Note**: It is a violation of the [terms of use](/legal/microsoft-apis/terms-of-use) to use Microsoft Teams as a log file. Only send messages that people will read.
+> **Notes**:
+> - We don't recommend that you use this API for data migration via the standard create message flow. For data migration scenarios, use the [import messages](/graph/teams-import-messages) flow instead.
+> - It is a violation of the [terms of use](/legal/microsoft-apis/terms-of-use) to use Microsoft Teams as a log file. Only send messages that people will read.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD022 -->
 <!-- markdownlint-disable MD025 -->
@@ -168,8 +170,13 @@ Content-type: application/json
 
 ### Example 2: Import messages
 
+The following example shows how to import a message reply. For more information, see [Import messages into Microsoft Teams chats and channels using Microsoft Graph](/graph/teams-import-messages).
+
 > **Note**: The permission scope `Teamwork.Migrate.All` is required for this scenario.
 
+> [!IMPORTANT]
+> The **createdDateTime** must be unique down to the millisecond within the target channel. If a message with the same **createdDateTime** exists, the request fails with `409 Conflict`. Adjust the **createdDateTime** and retry. For more information, see [Import messages into Microsoft Teams chats and channels using Microsoft Graph](/graph/teams-import-messages).
+
 #### Request
 
 The following example shows how to import back-in-time messages using the `createDateTime` and `from` keys in the request body.