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.

Import overview

At a high level, the import process consists of the following:

1. Create a team with a back-in-time timestamp.
2. Create a channel with a back-in-time timestamp.
3. Import external back-in-time dated messages.
4. Complete the team and channel migration process.
5. 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.
• Make sure that team members are in Microsoft Entra ID. For more information, see add a new user 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 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.

Permission

Request (create a team in migration state)

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
  "@microsoft.graph.teamCreationMode": "migration",
  "[email protected]": "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/1.1 202 Accepted
Location: /teams/{team-id}/operations/{operation-id}
Content-Location: /teams/{team-id}

Error message

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.

Step 2: Create a channel

Creating a channel for the imported messages is similar to the create team scenario:

Create a new channel 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 state)

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/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

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.

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.

Request (POST message that is text-only)

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/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

400 Bad Request

Request (POST a message with inline image)

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/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 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)

POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/completeMigration

Response

HTTP/1.1 204 NoContent

Request (end team migration mode)

POST https://graph.microsoft.com/v1.0/teams/team-id/completeMigration

Response

HTTP/1.1 204 NoContent

Action called on a team or channel that isn't in migrationMode.

Step five: Add team members

You can add a member to a team using the Teams UI or Microsoft Graph add member API:

Request (add member)

POST https://graph.microsoft.com/beta/teams/{team-id}/members
Content-type: application/json
Content-length: 30

{
   "@odata.type": "#microsoft.graph.aadUserConversationMember",
   "roles": [],
   "[email protected]": "https://graph.microsoft.com/beta/users/{user-id}"
}

Response

HTTP/1.1 204 No Content

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.

Import content scope

The following table provides the content scope:

See also

• Microsoft Graph and Teams integration
• Export content with the Microsoft Teams Export APIs
• Microsoft Teams service limits
• Licensing and payment requirements for the Microsoft Teams API