Search and purge chat messages in Teams (Preview)

You can use eDiscovery (Premium) and the Microsoft Graph Explorer to search for and delete chat messages in Microsoft Teams. This can help you find and remove sensitive information or inappropriate content. This search and purge workflow will also help you respond to a data spillage incident, when content containing confidential or malicious information is released through Teams chat messages.

Note

This article applies to Microsoft 365 Enterprise organizations. Support for the US Government cloud (including GCC, GCC High, and DoD) is coming soon.

Before you search and purge chat messages

• To create an eDiscovery (Premium) case and use collections to search for chat messages, you have to be a member of the eDiscovery Manager role group in the Microsoft Purview compliance portal. To delete chat messages, you have to be assigned the Search And Purge role. This role is assigned to the Data Investigator and Organization Management role groups by default. For more information, see Assign eDiscovery permissions.
• Search and purge is supported for conversations within your tenant. Support for Teams Connect Chat (External Access or Federation) conversations is enabled in the interface in some cases but is not working as intended.
• A maximum of 10 items per mailbox can be removed at one time. Because the capability to search for and remove chat messages is intended to be an incident-response tool, this limit helps ensure that chat messages are quickly removed.

Search and purge workflow

Here's the process to search for and purge Teams chat messages:

Step 1: Create a case in eDiscovery (Premium)

The first step is to create a case in eDiscovery (Premium) to manage the search and purge process. For information about creating a case, see Use the new case format.

Step 2: Create a draft collection

After you create a case, the next step is to create a draft collection to search for the Teams chat messages that you want to purge. The purge process you perform is Step 5 will purge all items that are found in the draft collection.

In eDiscovery (Premium), a collection is an eDiscovery search of the Teams content locations that contain the chat messages that you want to purge. Create the draft collection in the case that you created in the previous step. For more information, see Create a draft collection.

Data sources for chat messages

Use the following table to determine which data sources to search depending on the type of chat message you need to purge.

For this type of chat...	Search this data source...
Teams 1:1 chats	The mailbox of chat participants.
Teams group chats	The mailboxes of chat participants.
Teams channels (standard and shared)	The mailbox associated with the parent team.
Teams private channels	The mailbox of the private channel members.

Note

In Step 4, you also have to identify and remove any holds and retention policies assigned to the mailbox that contains the type of chat messages that you want to delete.

Tips for searching for chat messages

To help ensure the most comprehensive collection of Teams chat conversations (including 1:1 and group chats, and chats from standard, shared, and private chats) use the Type condition and select the Instant messages option when you build the search query for the draft collection. We also recommend including a date range or several keywords to narrow the scope of the collection to items relevant to your search a purge investigation.

Here's a screenshot of a sample query using the Type and Date options:

For more information, see Build search queries for collections.

Step 3: Review and verify chat messages to purge

As previously mentioned, the purge process in Step 5 will delete the items returned by the collection. So it's important that you review the draft collection results to ensure that the collection only returns the items that you want to purge. To review a sample of items in a draft collection, see the "Next steps after a draft collection is complete" section in Create a draft collection.

Additionally, you can use the collection statistics (specifically the Top Locations statistics) to generate a list of the data sources that contain items returned by the collection. Use this list in the next step to remove hold and retention policies from the data sources that contain search results. For more information, see Collection statistics and reports.

Step 4: Remove holds and retention policies from data sources

Before you can purge chat messages from a mailbox, you have to remove any hold or retention policy that is assigned to a target mailbox. If not, then the chat you're trying to delete will be retained.

Use the list of mailboxes that contain the chat messages that you want to delete and determine if there's a hold or retention policy assigned to those mailboxes, and then remove the hold or retention policy. Be sure to identify the hold or retention policy that you remove so that you can reassign to the mailboxes in Step 7.

For instructions about how to identify and remove holds and retention policies, see "Step 3: Remove all holds from the mailbox" in Delete items in the Recoverable Items folder of cloud-based mailboxes on hold.

Step 5: Purge chat messages from Teams

Now you're ready to actually purge chat messages from Teams. You'll use the Microsoft Graph Explorer to perform the following three tasks:

1. Get the Id of the eDiscovery (Premium) case that you created in Step 1. This is the case that contains the collection created in Step 2.

2. Get the Id of the collection that you created in Step 2 and verified the search results in Step 3. The search query in this collection returns the chat messages that will be purged.

3. Purge the chat messages returned by the collection.

For information about using Graph Explorer, see Use Graph Explorer to try Microsoft Graph APIs.

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.

Important

To perform these three tasks in Graph Explorer, you may have to consent to the eDiscovery.Read.All and eDiscovery.ReadWrite.All permissions. For more information, see the "Consent to permissions" section in Working with Graph Explorer.

Get the case Id

1. Go to https://developer.microsoft.com/graph/graph-explorer and sign in to the Graph Explorer with an account that's assigned the Search And Purge role in the Microsoft Purview compliance portal.

2. Run the following GET request to retrieve the Id for the eDiscovery (Premium) case. Use the value https://graph.microsoft.com/beta/compliance/ediscovery/cases in the address bar of the request query. Be sure to select v1.0 in the API version dropdown list.

   

   This request returns information about all cases in your organization on the Response preview tab.

3. Scroll through the response to locate the eDiscovery (Premium) case. Use the displayName property to identify the case.

   

4. Copy the corresponding Id (or copy and paste it to a text file). You'll use this Id in the next task to get the collection Id.

Tip

Instead of using the previous procedure to obtain the case Id, you can open the case in the Microsoft Purview compliance portal and copy the case Id from the URL.

Get the collection Id

1. In Graph Explorer, run the following GET request to retrieve the Id for the collection that you created in Step 2, and contains the items you want to purge. Use the value https://graph.microsoft.com/beta/compliance/ediscovery/cases('caseId')/sourceCollections in the address bar of the request query, where CaseId is the Id that you obtained in the previous procedure. Be sure to surround the case Id with parentheses and single quotation marks.

   

   This request returns information about all collections in the case on the Response preview tab.

2. Scroll through the response to locate the collection that contains the items that you want to purge. Use the displayName property to identify the collection that you created in Step 3.

   

   In the response, the search query from the collection is displayed in the contentQuery property. Items returned by this query will be purged in the next task.

3. Copy the corresponding Id (or copy and paste it to a text file). You'll use this Id in the next task to purge the chat messages.

Purge the chat messages

1. In Graph Explorer, run the following POST request to purge the items returned by the collection that you created in Step 2. Use the value https://graph.microsoft.com/beta/compliance/ediscovery/cases('caseId')/sourceCollections('collectionId')/purgeData in the address bar of the request query, where caseId and collectionId are the Ids that you obtained in the previous procedures. Be sure to surround the Id values with parentheses and single quotation marks.

   

   If the POST request is successful, an HTTP response code is displayed in a green banner stating that the request was accepted.

   

For more information on purgeData, see sourceCollection: purgeData.

Step 6: Verify chat messages are purged

After you run the POST request to purge chat messages, these messages are removed from the Teams client and replaced with an automatically generated stating that an admin has removed the message. For an example of this message, see the End-user experience section in this article.

Purged chat messages are moved to the SubstrateHolds folder, which is a hidden mailbox folder. Purged chat messages are stored there for at least 1 day, and then are permanently deleted the next time the timer job runs (typically between 1-7 days). For more information, see Learn about retention for Microsoft Teams.

Step 7: Reapply holds and retention policies to data sources

After you verify that chat messages are purged and removed from the Teams client, you can reapply the holds and retention policies that you removed in Step 4.

End-user experience

For deleted chat messages, users will see an automatically generated message stating "This message was deleted by an admin".

The message in the previous screenshot replaces the chat message that was deleted.

Note

If you're an end-user and a chat message was deleted, contact your admin for more information.