Disclaimer: This tool is provided ‘as-is’ without any warranty or support. Use of this tool is at your own risk and I accept no responsibility for any damage caused.
Backup Teams chat messages (not standard Team channel messages) for safe keeping - messages are saved in to a HTML report for easy viewing. Written in PowerShell Core and using Graph API, it can be used on Windows, Mac and Linux.
It can export chat messages for all users within a Teams tenant - including guests. This allows you to backup the following chat types:
- One on one (2 participants)
- Group (more than 2 participants but not in a Team)
- Meeting
- Private Team channel conversation
All of this is possible by using Microsoft Teams Protected APIs in Microsoft Graph API. By gaining access to Teams Protected APIs in Microsoft Graph you will have unrestricted access to all Team resources which may contain sensitive information in your organisation. Please ensure you have the relevant permission within your organisation to access this information before requesting access to the APIs
The Teams APIs that this script uses requires you to purchase license from Microsoft for extended use. Please see Licensing and payment requirements for the Microsoft Teams API.
Without providing a license model the script will use the "Evaluation" licensing model and be limited to 500 messages a month. After this, a message will appear that payment is required.
If you do license your application, you can then provide the licensing model ("A" or "B") to the script.
Note: If you do NOT license the application and provide the model anyway - it will still run, but return no messages.
As mentioned above, you will need to request access to the Teams Protected APIs. This is achieved by filling in this form with details of your Azure AD App registration and why you require access. It can take around a week to hear back.
You need to ensure you have PowerShell Core (7+) installed. This tool will NOT work with Windows PowerShell (5.1).
To connect to Microsoft Graph API, you will need to use an Azure AD App registration. Follow the below instructions to create one:
- Login to https://portal.azure.com (under the tenant you wish to use the tool) and under Azure Active Directory > App registrations create a New registration. Set the
Nameto something descriptive andSupported account typesto Single tenant (unless you wish to use the tool on multiple tenants). Click Register
- Take a note of the
Application (client) IDandDirectory (tenant) IDfor later on
- Under Certificates & secrets create a new Client secret. Set the
Descriptionand when itExpires(remember to renew) and click Add. Take a copy of theValuefor later.
- Under API Permissions, add the following Microsoft Graph permissions:
| Permission | Type | Description |
|---|---|---|
| Chat.Read.All | Application | Read all chat messages |
| Channel.ReadBasic.All | Application | Read the names and descriptions of Teams channels |
| Team.ReadBasic.All | Application | Read the names and descriptions of Teams |
| User.Read.All | Application | Read all users profiles |
- With the permissions added, you will need to Grant admin consent. It should look like the following:
- That is the App registration configured
Two modules are required to store secrets about your Azure AD App safely. Run the following:
Install-Module -Name Microsoft.PowerShell.SecretManagement
Install-Module -Name Microsoft.PowerShell.SecretStoreWith the Azure AD App registration created and the Teams Protected APIs granted to it, it is now possible to use the tool.
Firstly, download the latest release at https://github.com/leeford/Backup-TeamsChat/releases and extract it to a folder. Navigate to the folder.
If you are using Windows, you may need to un-block the Backup-TeamsChat.ps1 file if it is blocked
You can then run the Backup-TeamsChat.ps1 file from a PowerShell Core prompt. If it is the first time running it, it will create a secret vault called Backup-TeamsChat. Within this secret vault it will securely store your Azure AD App registration details (client ID, tenant ID and client secret):
Each time you run the tool, you will need to enter the password you used when creating the secret vault.
- Backup all chat messages for all users in tenant:
Backup-TeamsChat.ps1 -Path <directory to save backup>- Backup all change messages using licensing model "A":
Backup-TeamsChat.ps1 -Path <directory to save backup> -LicensingModel A- Backup chat messages for a specific user:
Backup-TeamsChat.ps1 -Path <directory to save backup> -User <UPN or ID>- Backup chat messages for all users in tenant for the last X days:
Backup-TeamsChat.ps1 -Path <directory to save backup> -Days 30Within the specified path there will be a new folder created and inside index.htm. Open this to navigate through users and their chats.
- List of users:
- List of chats:
- Chat thread:
