Almanac
Microsoft/teamsMicrosoft 365

Consultant-focused KB for Microsoft Teams: implementation notes, gotchas and configuration decisions beyond the official docs — across chat and collaboration, meetings, webinars and town halls, Teams Phone, PSTN connectivity (Direct Routing, Operator Connect, Calling Plans, Teams Phone Mobile), auto attendants, call queues and contact centre integration, Teams Rooms and devices, apps and extensibility, Copilot in Teams, administration and governance, security and compliance, network and call quality, and licensing — plus cross-cutting decision guides.

teams/10-security-and-compliance/feature-security-teams-retention-policies.md
feature-security-teams-retention-policies.mdv1 · history
CurrentApplies to Teams Enterprise, Microsoft 365 E5Updated 3 weeks agoSource Microsoft Learn ↗

What it does

Microsoft Purview retention policies that keep, delete, or keep-then-delete Teams messages. The policy acts on the compliance copies Teams writes into hidden folders in Exchange Online mailboxes, not on the chat service itself, which is why what users see in the client and what's actually retained can disagree for days.

Key facts

  • Teams has its own retention locations: Teams chats (user mailboxes, including MailUser for on-premises users), Teams channel messages (group mailboxes), Teams private channel messages, and Teams call logs (CDRs and call metadata).
  • Shared channel messages live in a SubstrateGroup mailbox and inherit the retention settings of the parent team.
  • Private channel messages have been moving from members' user mailboxes to the team's group mailbox. Before migration they need the separate private channel location; after it, the Teams channel messages location covers them.
  • Three policy shapes: retain-and-delete, retain-only, delete-only.
  • Covered: message text, Facilitator interactions in meetings, video clips, embedded images, tables, hyperlinks, links to other messages and files, card content.
  • Not covered: code snippets, voice memos from Teams mobile, thumbnails, announcement images, emoji reactions. Files and emails need their own policies; meeting recordings and transcripts sit in OneDrive/SharePoint and are governed there.
  • Deletion is a timer-job process: expired items move to the hidden SubstrateHolds folder (typically 1–7 days), stay there at least 1 day, then get permanently deleted on a later run (typically 1–7 days). Expect 2–14 days end to end, and up to 16 for a 1-day delete-only policy.
  • Messages a user deletes sit for 21 days before moving to SubstrateHolds.
  • A litigation hold, delay hold, eDiscovery hold or another Teams retention policy on the same location suspends permanent deletion. Messages vanish from the client but stay discoverable.
  • Guest accounts in your tenant get compliance copies, but retention policies aren't supported for those shadow mailboxes. Messages from users in other Microsoft 365 organisations are in their tenant; you can only delete your own users' copies.
  • When a user leaves, the mailbox goes inactive and existing retention still applies to their chat messages.

When to use / skip

If the client has any regulatory obligation, records policy or legal team, you need Teams retention. Without it, Teams chat is kept forever by default, which legal departments tend to like even less than deletion once they work out what's sitting in there. Most of the conversations I have are about deletion, not retention: "we want 1:1 chat gone after a year" is the usual brief.

Skip it only if the client genuinely has no lifecycle requirement and is happy with indefinite retention. Even then, set a deliberate retain-only policy so the decision is documented rather than accidental. Regulated voice is a different problem: if they need calls recorded, that's compliance recording, not this.

Configuration decisions

  • Chats versus channels: almost everyone wants different periods. Channel posts are team records; 1:1 chat is closer to a phone call.
  • Retain-and-delete versus delete-only. Delete-only is tempting for "clean up chat" projects but leaves no safety net if litigation lands next month.
  • Org-wide versus adaptive or static scopes. Adaptive scopes keyed on department or country are worth the effort in multinationals with different local rules.
  • How private channels are handled during and after the group-mailbox migration, especially if they need a different period from the parent team.
  • Whether call logs are in scope.
  • What separate policies cover the OneDrive and SharePoint locations holding files, recordings and transcripts, and whether their periods line up with the chat policy.
  • Retention labels and records management sit alongside this, but Teams messages themselves are governed by policy, not by labels a user applies.

Gotchas

  • "I set a 30-day delete policy and the messages are still there on day 33." That's the timer job, not a fault. Explain the 2–14 day window before go-live, not after the first complaint.
  • Retention always wins over deletion. One forgotten retain-forever policy or an old eDiscovery hold and your delete policy does nothing visible in compliance searches.
  • Reactions aren't retained. If a client's legal team thinks a thumbs-up is evidence, they need to know that now.
  • Meeting recordings aren't a Teams retention location. People configure the Teams locations, call it done, and the recordings sit in OneDrive under whatever policy that location has, or none.
  • The Teams client isn't a reliable way to check retention is working. Use eDiscovery to confirm what's actually held or gone.
  • Cross-tenant chats only honour your policy for your copies. The other side keeps theirs.

Consultant notes

  • Get the period decisions signed off by legal or records management in writing. IT shouldn't be choosing how long chat lives.
  • Pilot a delete policy on a small static scope first and verify with a content search before and after. Budget two to three weeks for the cycle.
  • Inventory existing holds and policies before adding new ones; inherited M365 tenants often have forgotten litigation holds on leavers.
  • Document the private channel position explicitly in the design, including whether migration has completed for the tenant.
  • Pair this with the eDiscovery design. The two are the same data viewed from opposite ends.

Revisit once the private channel move to group mailboxes is confirmed complete for the tenant, and whenever Microsoft adds or drops a Teams retention location

Was this accurate?
Related
Data loss prevention for Teams chat and channel messages10-security-and-complianceFiles in Teams — where they actually live in SharePoint and OneDrive01-chat-and-collaborationPrivate channels in Teams — separate membership, separate SharePoint site01-chat-and-collaborationMeeting Recording and Transcript Storage, Permissions and Expiration02-meetings-webinars-and-eventseDiscovery for Teams chats, channels and meetings10-security-and-complianceTeam Creation Governance: Who Can Create, Naming Policy and Expiration09-administration-and-governance