Permanently delete Microsoft Teams chat history using a retention policy

This guide will show you how to create a retention policy to permanently delete old Microsoft Teams chat messages

What you need to know about Teams retention policies

Users can delete their own messages from the Teams chat history but Office 365 admins might also want to delete old Teams chats to remove old or inappropriate content or for data privacy reasons.

The only way to remove old Teams messages at the organization level is using a retention policy.

by Author

• Teams retention policies can be applied to your entire organization or to specific users and teams
  
  
• You can create separate retention policies for private chats and channel messages
  
  
• The start of the retention period is based on when a message is created
  
  
• Retention policy changes can take several days to apply
  
  
• Teams retention policies are processed by the Exchange Managed Folder Assistant (MFA)
  
  
• Teams requires a separate retention policy, you can't include other Office 365 services e.g. Exchange email or OneDrive in the same policy
  
  
• Users may see this message when a retention policy has deleted chat messages
  "We've deleted older messages due to your org's retention policy"
  
  
• The retention policy name and other settings cannot be changed after the policy has been created
  
  
• Only these Teams retention policy settings can be changed after the policy has been created:
  Included and excluded Teams and users, retention time period

Example of some old Teams chat messages, when we're finished creating the retention policy these will get removed.

References:

Manage retention policies for Microsoft Teams
https://docs.microsoft.com/en-us/microsoftteams/retention-policies

Retention policy for Teams locations
https://docs.microsoft.com/en-us/microsoft-365/compliance/create-retention-policies?view=o365-worldwide#retention-policy-for-teams-locations

by Author

Create a Teams retention policy

Logon to the Compliance Admin Center
https://compliance.microsoft.com

Policies - Data - Retention

New retention policy

Teams retention policy settings

Name: Teams Chat Retention Policy

Description: Delete Teams chat messages after 6 months

Locations - select Teams channel messages and Teams chats

Retain items for a specific period - select custom

Retain items for a specific period - enter 6 months

At the end of the retention period - Delete items automatically

Review the settings then click submit

Check Teams retention policy status

Click on the retention policy - Status

When the retention policy has updated the status will change from Enabled (Pending) to Enabled (Success)

Find oldest Teams chat items using PowerShell

We can run the following PowerShell to find the date of the oldest Teams chats, after the retention policy has applied we should see the date of the oldest items change. Credit for the PowerShell goes to this article from petri.com

Proving that Teams Retention Policies Work
https://petri.com/proving-teams-retention-policies-work

Connect to Exchange Online PowerShell

Replace -Identity TeamName@yourdomain.com with the name of the Team you want to check

Get-MailboxFolderStatistics -Identity TeamName@yourdomain.com -FolderScope ConversationHistory -IncludeOldestAndNewestItems | ? {$_.FolderType -eq "TeamChat"} | ft name, Itemsinfolder, Newestitemreceiveddate, Oldestitemreceiveddate 

Start retention policy processing for a Team

Teams Retention Policies are processed by the Exchange Managed Folder Assistant (MFA). This is the same agent that is used to process Office 365 mailboxes and move messages to archive 

Start-ManagedFolderAssistant -Identity TeamName@yourdomain.com 

Check retention policy processing logs

Use the Export-MailboxDiagnosticLogs PowerShell command to check the Exchange Managed Folder Assistant logs for a Team

Export-MailboxDiagnosticLogs TeamName@yourdomain.com -ExtendedProperties > C:\temp\diagnostic-logs.txt 

Check the ELCLastSuccessTimestamp in the logs, this will tell you when the Managed Folder Assistant last ran

Now that the retention policy has applied all old Teams chat history has been deleted

In this case the message "We've deleted older messages due to your org's retention policy" did not show up