Find and delete Microsoft Teams chat messages in eDiscovery (preview)

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

Tip

Get started with Microsoft Copilot for Security to explore new ways to work smarter and faster using the power of AI. Learn more about Microsoft Copilot for Security in Microsoft Purview.

Before you search and delete chat messages

• To create an eDiscovery case and search for chat messages, you have to be a member of the eDiscovery Manager role group in the Microsoft Purview 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 are supported for most conversations within your organization. Search and purge for Teams Connect Chat (External Access or Federation) conversations isn't supported.

  Important

  Chats with yourself (or chats by users with themselves) aren't supported for search and delete.

• 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.

Step 1: Create a case in eDiscovery (preview)

The first step is to create a case in eDiscovery (preview) to manage the search and delete process.

Step 2: Create a search query

After you create a case, the next step is to search for the Teams chat messages that you want to delete. The delete process you perform is Step 5 deletes all items that are found in the search (within the 10 item per location limit).

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 delete.

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 identification 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. We also recommend including a date range or several keywords to narrow the scope of the search to items relevant to your investigation.

Step 3: Review and verify chat messages to delete

The deletion process in Step 5 deletes the items returned by the search. It's important that you review the search statistics to ensure that the search only returns the items that you want to delete. Additionally, you can use the search statistics (specifically the Top Locations statistics) to generate a list of the data sources that contain items returned by the search. Use this list in the next step to remove hold and retention policies from the data sources that contain search results.

Step 4: Remove all holds and retention policies from data sources

Before you can delete chat messages from a mailbox, you have to remove all organization-wide holds, site holds, or retention policy holds that are assigned to a target mailbox. If not, the chat you're trying to delete is 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: Delete chat messages from Teams

Note

Because Microsoft Graph Explorer is not available in some US Government clouds (GCC High and DOD), you must use PowerShell to accomplish these tasks. See Delete chat messages with PowerShell for details.

Now you're ready to actually delete chat messages from Teams. Use the Microsoft Graph Explorer to perform the following three tasks:

1. Get the ID of the eDiscovery case that you created in Step 1. This is the case that contains the search results created in Step 2.
2. Get the ID of the search that you created in Step 2 and verified the search results in Step 3. The search quer returns the chat messages that will be deleted.
3. Delete the chat messages returned by the search.

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

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 portal.

2. Run the following GET request to retrieve the ID for the eDiscovery case. Use the value https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases 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 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 search ID.

Tip

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

Get the eDiscoverySearchID

1. In Graph Explorer, run the following GET request to retrieve the ID for the search that you created in Step 2, and contains the items you want to delete. Use the value https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases/{ediscoveryCaseID}/searches in the address bar of the request query, where {ediscoveryCaseID} is the CaseID that you obtained in the previous procedure.

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

   In the response, the search query from the search is displayed in the contentQuery property. Items returned by this query is deleted 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 delete the chat messages.

Delete the chat messages

1. In Graph Explorer, run the following POST request to delete the items returned by the search that you created in Step 2. Use the value https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases/{ediscoveryCaseID}/searches/{ediscoverySearchID}/purgeData in the address bar of the request query, where {ediscoveryCaseID} and {ediscoverySearchID} are the IDs that you obtained in the previous procedures.

   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.

Delete chat messages with PowerShell

You can also delete chat messages using PowerShell. For example, to delete messages in the US Government cloud you could use a command similar to:

Connect-MgGraph -Scopes "ediscovery.ReadWrite.All" -Environment USGov

Invoke-MgGraphRequest -Method POST -Uri '/v1.0/security/cases/ediscoveryCases/<ediscoverySearchID>/searches/<search ID>/purgeData'

For more information on using PowerShell to delete chat messages, see ediscoverySearch: purgeData.

Step 6: Verify chat messages are deleted

After you run the POST request to delete 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.

If you need to confirm a chat message has been removed and don't have access to the end-user message in Teams, rerun the search and verify if any matching messages are found. If there aren't any results for the message, the message has been removed.

Deleted chat messages are moved to the SubstrateHolds folder, which is a hidden mailbox folder. Deleted 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.

Note

Because Microsoft Graph Explorer is not available in the US Government cloud (GCC, GCC High, and DOD), you must use PowerShell to accomplish these tasks.

Step 7: Reapply holds and retention policies to data sources

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

Deleting chat messages in federated environments

Admins can use the procedures in this article to search and delete Teams chat messages in federated environments. However, you must adhere to the following guidelines. These guidelines are based on the organizational ownership of the conversation thread that contains the messages you want to delete. An organization is the owner of a conversation thread that is started by a user in that organization. In other words, when a user starts a chat, the user's organization becomes the owner of the conversation thread.

• Admins can delete the compliance copy in conversation threads owned by their organization. That means compliance copies are deleted when the admin who deletes the chat messages in Step 5 is in the same organization as the user who initiated the conversation thread that contains the deleted messages. If a conversation thread has users in two organizations, compliance copies for the other organization are retained.
• If a conversation thread has users in two organizations, deleted chat messages are removed from the Teams client in both organizations.
• The only way to delete chat messages from user mailboxes in your organization for chat messages in conversation threads owned by another organization is to use retention policies for Teams. For more information, see Learn about retention for Microsoft Teams.

End-user experience

For deleted chat messages, users 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.