Edit

Share via

chat: startMigration

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Start the migration of external messages by enabling migration mode in an existing chat. Import operations were limited to newly created standard channels that were in an empty state. For more information, see Import third-party platform messages to Teams using Microsoft Graph.

You can define a minimum timestamp for content migration that enables the import of messages from the past. The specified timestamp must be earlier than the current createdDateTime of the chat. Imported content is always limited by the createdDateTime of the target thread. An optional createdDateTime property in the payload allows you to update this value, but with strict rules:

  • The createdDateTime can only be moved towards the past.
  • The createdDateTime can't be updated to a value newer than the current createdDateTime.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet
✅ ✅ ✅ ✅

This API supportes the following channel types.

Entities Sub type Migration mode support Notes
Chats Group, 1:1 New and existing Meeting chats aren't supported. External members are supported.

Notes:

  • Chat types aren't allowed in initial imports.
  • Federated chats are supported, but users can't create federated resources. For example, they can't import messages on behalf of a federated user, and the target chat must belong to the tenant of the initiator app. Users can import content only into the tenant to which they are authenticated.

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Not supported. Not supported.
Delegated (personal Microsoft account) Not supported. Not supported.
Application Teamwork.Migrate.All Not available.

HTTP request

POST /chats/{chat-id}/startMigration

Request headers

Header Value
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Optional

Request body

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.

Response

If successful, this method returns a 204 No Content response code. It doesn't return anything in the response body.

Examples

Example 1: Start the migration in a chat

The following example shows how to start the migration in a chat.

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration

Response

The following example shows the response.

HTTP/1.1 204 No Content

Example 2: Start the migration when a chat is already in migration mode

The following example shows how to start the migration when a chat is already in migration mode. This request fails with a 400 Bad Request response.

Request

The following example shows a request.

POST https://graph.microsoft.com/beta/chats/19:4b6bed8d24574f6a9e436813cb2617d8@thread.tacv2/startMigration

Response

The following example shows the response.

HTTP/1.1 400 Bad Request

Related content

  • Last updated on