Case from the Field – Deploy Teams Backgrounds with Microsoft Intune

Last week a customer asked me if it is possible to provide custom Teams backgrounds to the entire organization so that they are available by default in Teams for their end-users when they get a new device.

This is something we can create by using a Win32 app containing the images and some Powershell scripts. Interested? Let’s go!

What do we need?

First I’ll give a brief overview of the things we need:

  • Microsoft Win32 Content Prep Tool: this tool I will use to create the Win32 app. You can download it here.
  • backgrounds: A folder containing all the background images (inc. a thumb version of the image)
  • uploadbackgrounds.ps1: A PowerShell script that will create the destination folder (if needed) and copy all the above images to the destination folder
  • removebackgrounds.ps1: A PowerShell script that will uninstall/remove those files if they are not needed anymore
  • detectupload.ps1: A Powershell script that will detect if all the folders/files are created afterward.

NOTE: If you aren't familiar with creating a Win32 app with the Microsoft W32 Content Prep Tool, make sure you read this article on Microsoft Learn.

Step 1: Collect the images

I’ve created a TeamsBackground folder in C:\MicrosoftIntuneApps with three folders App, Tool, and Detection. The folder App contains everything we need to create our Win32 app and here we will store our .intunewin file. The folder Tool is where I’ve downloaded the Prep Tool and the folder Detection is where I will save the detection script.

Create a subfolder named Backgrounds in the App folder and save/copy your background images into that folder. Make sure you have 2 versions of your background ready, one original (1920×1080 pixels) and one thumb version (280×155 pixels). So I have the two following images:

  • teams_background.jpg
  • teams_background_thumb.jpg

Now that we have our images in place, let’s get started with our PowerShell scripts.

Step 2: Create the PowerShell scripts

As I wrote at the beginning of this article, we will create two PowerShell scripts for installing/uninstalling the backgrounds, and one script for the detection after installing/uploading the backgrounds.

uploadbackgrounds.ps1

First I’ll give a summary of what this script will do. To use custom Teams Backgrounds, the following folder needs to exist %appdata%\Microsoft\Teams\Backgrounds\Uploads. By default this folder doesn’t exist, only if you manually uploaded a background from the Teams App.

So the first step is to check if the folder exists, if not the script will create the folder. The second part of the script will copy all the files in the Backgrounds folder to the Uploads folder. You can find the full script below and copy it into Visual Studio Code and save it to a .ps1 file into the Apps folder created in Step 1.

# This step will set a variable to the local folder where the custom Teams Backgrounds are stored
$BackgroundUploadFolder="$env:APPDATA\Microsoft\Teams\Backgrounds\Uploads"
 
# This will create the folder if not exists, this is only when the user never added a custom background manually
if(!(Test-Path -path $BackgroundUploadFolder)) 
{ 
 New-Item -ItemType directory -Path $BackgroundUploadFolder
 Write-Host "The Teams Background Upload Folder has been created successfully"
 }
else
{
Write-Host "The Teams Background Upload Folder already exists";
}
 
#This will copy all images files to the Teams Upload folder locally
Copy-Item -path '.\backgrounds' -Filter *.* -Destination $BackgroundUploadFolder -Recurse -Container:$false

Not let’s check the second script.

removebackgrounds.ps1

This second script will simply remove all the image files (.jpg) in the local Uploads folder. You can copy and paste the below script into Visual Studio Code and save it as a .ps1 file.

# This step will set a variable to the local folder where the custom Teams Backgrounds are stored
$BackgroundUploadFolder="$env:APPDATA\Microsoft\Teams\Backgrounds\Uploads"
# This will delete all JPG files in the Teams Uploads folder locally
Remove-Item -Path $BackgroundUploadFolder\*.jpg -Force

Now that we have our two first scripts, our preparation App folder will be something like in the screenshot below.

detectupload.ps1

So this script we need to have as a detection rule when we are adding the app in Microsoft Intune. This will just check if the upload script did the job. You can copy and paste the script below and save it as a .ps1 file in the detection folder.

# This script will be used to detect if the upload was succesfull
if (Test-Path "$env:APPDATA\Microsoft\Teams\Backgrounds\Uploads\*.jpg") {
    Write-Host "The Teams Background Files are detected"
}

Now that we have all our scripts, we can create our Win32 app (.intunwin).

Step 3: Create the .intunewin file

Now run (as an administrator) the Microsoft W32 Content Prep tool and choose the following steps:

  • Please specify the source folder: C:\MicrosoftIntuneApps\TeamsBackground\App
  • Please specify the setup file: uploadbackgrounds.ps1
  • Please specify the output folder: C:\MicrosoftIntuneApps\TeamsBackground\App
  • Do you want to specify catalog folder (Y/N)? N

This will create the .intunewin file we need upload when adding an W32 application in Microsoft Intune.

Step 3: Add a W32 app in Microsoft Intune

The last step we need to do is deploy the app with Microsoft Intune by adding a W32 app. Now go to Microsoft Intune admin center | Apps | Windows and choose + Add. Now pick Windows app (Win32) as app type and choose Select.

Choose Select app package and browse to the folder where we stored our .intunewin file and select OK.

Now fill in some App Information, see the screenshot below, and choose Next.
The custom logo is one I’ve created myself.

In the next step we will add our install and uninstall command and refer it to the two PowerShell scripts we’ve created and added in our W32 package file.

  • Install command: powershell.exe -executionpolicy Bypass .\uploadbackgrounds.ps1
  • Uninstall command: powershell.exe -executionpolicy Bypass .\removebackgrounds.ps1

Make sure you are installing the app in User Behavior instead of System. You can leave all other settings by default and choose Next.

In the next step you can add some requirements information and choose Next.

Now we are going to add our detection script to the app by choosing Use a custom detection script and choose our detectionupload.ps1 file we’ve created and choose Next.

We can skip Dependencies and Supersedence and go straight to the Assignments section. Now we need to assign this app to our users by adding the desired user group. Add the group to Required and choose Next.

The final step will show you an overview of the settings, now choose Create and the application will be added and starting to deploy to the assigned users.

Now that we’ve added to application, we need to wait until it’s deployed to our end users.

Result

After the app is deployed, you see that the Backgrounds are available on the users device and ready to be used in Microsoft Teams

So this was it, hope you found it interesting and useful. Feel free to visit my Github page where all these files and scripts are for grabs. See you all later!

Nicky De Westelinck

Nicky De Westelinck is a Modern Workplace Consultant for Wortell Belgium with several years of experience in Microsoft 365. His main focus is Microsoft EndPoint Manager and Microsoft 365 Administration. He is also a Microsoft Certified Trainer since 2021.

View all posts by Nicky De Westelinck →