Manage and Report Microsoft Teams Tag Members Using PowerShell

Microsoft Teams tags are a powerful tool for streamlining communication with the organization. By assigning tags to users based on skills, departments, or projects, you can easily reach specific groups without individually mentioning everyone. But, managing them is not a fruitful experience for admins. By default, team owners and members have the control to manage tags within their specific teams. This means a Teams admin, who might oversee many teams, can’t directly manage tag creation, or membership assignment unless they’re added as an owner to each team.

With Microsoft Graph PowerShell cmdlet Get-MgTeamTag, team owners can retrieve tags of their own team. But there’s no in-built way to get ahold of all tags across your entire tenant. So, we have developed a PowerShell script to manage tags in Microsoft Teams at ease. Using this script, admins can retrieve tags from standard channels of all teams and can also add & remove users from the team tags.

Let’s get started!

Download Script: ManageTeamsTagAndMembers.ps1

• Exports tags for all teams in your entire tenant.
• Helps you to add user(s) to a tag.
• Allows you remove user(s) from a tag.
• The script uses MS Graph PowerShell and installs MS Graph PowerShell SDK (if not installed already) upon your confirmation.
• The script is schedular-friendly.
• Exports report results as a CSV file.

The script exports all the tags of a team within the organization along with the following attributes:

• Team Name
• Team Member Count
• Team Description
• Team Visibility
• Tag Name
• Tag Member Count
• Tag Type
• List of Members in Tag
• Tag Members Teamwork Tag Id
• Non-tag Members Count
• List of Non-tag Members
• Team Id
• Tag Id

1. Download the script.
2. Start the Windows PowerShell.
3. Use certificate-based authentication (CBA) to run this script, which is schedular friendly.

Before employing certificate-based authentication, it is crucial to register an application in Azure AD. Once the application is registered, we need to grant the required API permissions:

App registrations 🡢 All applications 🡢 Select your application 🡢Manage 🡢 API permissions 🡢 Add a permission 🡢Microsoft Graph 🡢 Application permissions

Search for the following permissions and select them.

• Team.ReadBasic.All
• TeamMember.Read.All
• Teamwork.Tag.ReadWrite.All

To update existing consent records, navigate back to the “Configured permissions” window. From there, select “Grant admin consent for” to assign the required Azure AD Graph permissions for your app registration. Immediately, a fly-out page appears for your confirmation with a Yes button.

Note: Depending on your requirements, you can create a self-signed certificate.

4. Execute the script as below after granting the required API permissions.

Once you run this script, you will be prompted to choose the required management actions.

• Choosing 1st action will report the team tags for your entire tenant.
• Choosing 2nd action will allow you to add users to a team tag once you specify the respective team ID, tag ID, and user ID.
• Choosing 3rd action will help you remove users from a team tag after entering the respective team ID, tag ID, and tag member ID.

For detailed script execution, refer to the below!

With this script, you can perform the following three management actions which are also schedular-friendly.

1. Get Microsoft Teams tags and tag members report.
2. Add users to a team tag
3. Remove users from a team tag

You can either pass the action like -GetTeamTagReports, -AddUsertoTag, or -RemoveUserFromTag directly, or pick one from the main menu.

To generate a report of Microsoft Teams tags and members included in the tag, run the following.

Once you run the above code, the resulting report will list all tags and their members.

The screenshot will look like the below.

Note: Currently, it’s not possible to retrieve tags from private and shared channels.

Using the script, you can also add users to a team tag. For adding users, Team ID and Tag ID are crucial. You can retrieve both from the above generated report.

• Add single user to a team tag
• Add bulk users to a team tag

To add a user to a tag in Microsoft Teams, just provide their user ID.

Once the script is executed successfully, a log file will get generated. There you can check the status.

• If the member addition is successful, you will receive the log as ‘<Username> is added to the given TagId: <TagID> successfully’.
• If you are trying to add a member who is not present in that specific Team you mentioned, then you will get a log as ‘Given Userid <UserID> not present in given TeamId <TeamID>’.

To add multiple users to a tag in Microsoft Teams, you need to specify the CSV path of input file. The input file must contain the UserIDs of required users of the respective team.

The input file must follow the format below.

Once the script is executed successfully, a log file will get generated where you can check the status.

In addition to adding members, this script is also used to remove users from a team tag in Microsoft Teams.

• Remove single user from a team tag
• Remove bulk user from a team tag

For removing users, you need to obtain TeamWorkTagMemberID along with team ID and tag ID. TeamWorkTagMemberID is a special ID assigned whenever someone in the team gets linked to a tag. You can find this ID in the report we generated earlier.

Execute the following PowerShell script to remove a specific member from the designated team tag. Ensure you replace the placeholders with your actual values.

When the script is executed successfully, a log file will get generated. There you can check the status.

• When a member is successfully removed, you will get the log as ‘<TeamWorkTagMemberID> is removed from the given TagId: <TagID>’.
• When the member removal is not successful, you will receive the log as ‘<TeamWorkTagMemberID> is not removed from the given TagId: <TagID>. Error occurred: [BadRequest]: Invalid membership id provided: <TeamWorkTagMemberID>’.

To remove multiple users from a tag in Microsoft Teams, you will have to provide the CSV file path. The CSV should contain the TeamworkTagMemberId of users in the team tag.

The input file must follow the format below.

Once the script is executed successfully, a log file will get generated where you can check the status.

Managing tags in Microsoft Teams can be a hassle for admins, but with this PowerShell script, you can efficiently manage tags and their members across your entire tenant. If you have any questions, feel free to reach out in the comments section.