Practical Microsoft Graph PowerShell for Microsoft Teams

Managing Microsoft Teams if you’re an IT Pro can often be a complicated process that requires multiple services to be combined. When provisioning a team, services such as Azure Active Directory (AAD), SharePoint Online, and Exchange Online connect to the core plumbing. It means that for you as an IT administrator, you need to connect to potentially all the connected services to manage a team in Microsoft Teams.

From a user interface perspective, this means using multiple administration consoles or multiple PowerShell modules that need installing, importing, and connecting independently.

Install-Module -Name AzureAD

Install-Module -Name Microsoft.Online.SharePoint.PowerShell

Install-Module -Name ExchangeOnlineManagement




Import-Module -Name AzureAD

Import-Module -Name Microsoft.Online.SharePoint.PowerShell

Import-Module -Name ExchangeOnlineManagement




Connect-AzureAD

Connect-SPOService

Connect-ExchangeOnline

Microsoft does, however, provide a Teams Administration portal that is now an easy place to manage most of the configuration and management tasks you need to complete within Microsoft Teams. However, as with most things within Microsoft 365, many configuration settings are either unavailable within Microsoft Teams, or only available within the Microsoft Graph or PowerShell.

How to install the Microsoft Teams PowerShell module

The good news is that Microsoft provides a specific PowerShell module for managing Microsoft Teams called “MicrosoftTeams.” You can easily install the Microsoft Teams PowerShell module using the following command:

Install-Module -Name MicrosoftTeams -Force -AllowClobber

Import-Module -Name MicrosoftTeams

Once installed, you can then manage specific configurations and settings for Microsoft Teams. A simple example would be creating a new team in Microsoft Teams with the following PowerShell command:

New-Team `

-DisplayName "My New Team" `

-Description "My New Team Description"

Most of the commands are prefixed with “Team” or “Teams,” denoting they are for Microsoft Teams; however, some of them use either “CsTeam” or “CsTeams” in the name, which are legacy commands ported over from the older Skype for Business PowerShell module.

Many of the PowerShell commands wrap existing Microsoft Graph API capabilities, which means that when Microsoft adjusts the APIs, the PowerShell commands also need updating. It often leads to the deprecation of commands, especially when resolving them would require significant effort or when a similar command is available within the Microsoft PowerShell Graph SDK.

How to leverage the Microsoft Graph PowerShell SDK

The Microsoft Graph PowerShell SDK serves as an API wrapper for the Microsoft Graph APIs, exposing the complete API set for use in PowerShell. It comprises multiple PowerShell modules that directly map to Microsoft Graph API commands.

The primary module is “Microsoft.Graph,” which contains all the core connection commands needed for using the Microsoft Graph. Additional modules target specific tasks such as managing users, mail, sites, compliance, and of course teams and groups. Each module contains the same name as the primary with the category appended. You can see this in the example list below:

Users: Microsoft.Graph.Users

Mail: Microsoft.Graph.Mail

Sites: Microsoft.Graph.Sites

Compliance: Microsoft.Graph.Compliance

Teams: Microsoft.Graph.Teams

All modules (approx. 35) automatically import when the primary module imports. To import the primary and additional modules, you use the following PowerShell command:

Install-Module Microsoft.Graph

Import-Module Microsoft.Graph

Once this is completed, executing the following command will display all the imported modules:

Get-InstalledModule Microsoft.Graph.*

You can view all the Microsoft Teams commands using the following command:

Get-Command -Module Microsoft.Graph.Teams

The first task is to connect using the Microsoft Graph PowerShell SDK, which requires you to set the scopes (permissions) required to manage any specific services. To view the available scopes (permissions), you can use the following command:

Find-MgGraphPermission teams -PermissionType Delegated

To connect to Microsoft Teams using the required permissions, you can use the following command:

Select-MgProfile -Name "beta"

$scopes = @(

"Group.ReadWrite.All",

"GroupMember.ReadWrite.All",

"TeamsApp.ReadWrite.All",

"TeamsAppInstallation.ReadWriteForTeam",

"TeamsAppInstallation.ReadWriteSelfForTeam",

"TeamSettings.ReadWrite.All",

"TeamsTab.ReadWrite.All",

"TeamMember.ReadWrite.All"

)

Connect-MgGraph -Scopes $scopes

Now that you have a connection to Microsoft Teams, you can start configuring and managing Microsoft Teams with get-MGteam and other commands. The most common commands to use are the following:

Add-MgChatMember

Add-MgTeamMember

Get-MgTeam

Get-MgTeamChannel

New-MgTeam

New-MgTeamChannel

Remove-MgTeam

Remove-MgTeamMember

Update-MgTeam

PowerShell is often the best approach to deploying any settings within Microsoft Teams. The current commands available within the Microsoft Graph PowerShell SDK provide a mix of functions from viewing policies and configuration to setting some of the more obscure values related to calling. Some of the most helpful management commands are below:

Before you can retrieve any details of a team, you need to know the ID of the one you are looking for. You can retrieve the list of Groups, then grab the ID of the “unified” group (team connected) you wish to use with the command below:

 Get-MgGroup | Format-List Id, DisplayName, Description, GroupTypes

Once you identify the team to work with from the list, you can populate a reuse variable:

$group = Get-MgGroup -Filter "DisplayName eq 'Sales Planning'"

Now you can reuse the “Group ID” command to work with the team:

# Retrieve Teams by ID

$team = Get-MgTeam -TeamId $group.Id

Write-Host $team.DisplayName




# View All Properties About Selected Team

$team = Get-MgTeam -TeamId $group.Id

$team | Select-Object *




# View All Members of a Team

$team = Get-MgTeam -TeamId $group.Id

$members = Get-MgTeamMember -TeamId $team.Id

$members | Select-Object DisplayName




# Create a New Group Then Convert to a Team

$group = New-MgGroup `

-DisplayName "New Group" `

-MailEnabled:$False `

-MailNickName "newgroup" `

-GroupTypes "Unified" `

-SecurityEnabled




Using Namespace Microsoft.Graph.PowerShell.Models

[MicrosoftGraphTeam1]@{

Template = [MicrosoftGraphTeamsTemplate]@{

Id = 'com.microsoft.teams.template.OrganizeHelpDesk'

}

Group = $group

} | New-MgTeam




$team = Get-MgTeam -TeamId $group.Id




# Create a New Team

Using Namespace Microsoft.Graph.PowerShell.Models

[MicrosoftGraphTeam1]@{

Template = [MicrosoftGraphTeamsTemplate]@{

Id = 'com.microsoft.teams.template.OrganizeHelpDesk'

}

DisplayName = "New Team"

Description = "New Team Description"

} | New-MgTeam




$group = Get-MgGroup -Filter "DisplayName eq 'New Team'"

$team = Get-MgTeam -TeamId $group.Id




# Add a Team Owner

$group = Get-MgGroup -Filter "DisplayName eq 'New Team'"

$team = Get-MgTeam -TeamId $group.Id




$user = Get-MgUser -UserId "[email protected]"

$properties = @{

"@odata.type" = "#microsoft.graph.aadUserConversationMember";

"[email protected]" = "https://graph.microsoft.com/beta/users/" + $user.Id

}

$role = "owner"




New-MgTeamMember `

-TeamId $team.Id `

-Roles $role `

-AdditionalProperties $properties



# Add a Private Teams Channel Then Add a Member

$channel = New-MgTeamChannel `

-TeamId $team.Id `

-DisplayName "New Team Channel 2" `

-Description "New Team Channel Description 2" `

-MembershipType "Private"




$user = Get-MgUser -UserId "[email protected]"

$properties = @{

"@odata.type" = "#microsoft.graph.aadUserConversationMember";

"[email protected]" = "https://graph.microsoft.com/beta/users/" + $user.Id

}




New-MgTeamChannelMember `

-ChannelId $channel.Id `

-Team $team.Id `

-Id $user.Id `

-Roles "Member" `

-AdditionalProperties $properties

Just remember that changing actions may require further permissions than the original connection. When necessary, you can do this by reissuing the connection command with the appended permissions. For writing messages and sending them, you will need the “ChannelMessage.Send“, “Chat.ReadWrite“, and “ChatMessage.Send” commands:

# Post a Message to a Channel
$message = "New Sample Message"
New-MgTeamChannelMessage `
-ChannelID $channel.Id `
-TeamId $team.Id `
-Body @{ Content = $message }

# Post a New Message and Then a Reply

$message = New-MgTeamChannelMessage `

-ChannelID $channel.Id `

-TeamId $team.Id `

-Body @{ Content = "My New Message" }




$reply = New-MgTeamChannelMessageReply `

-ChannelID $channel.Id `

-TeamId $team.Id `

-ChatMessageId $message.Id `

-Body @{ Content = "Great Comment" }

As you can see, using the Microsoft Graph PowerShell SDK provides excellent capabilities from the highest level of creating and managing teams to posting messages with commands like get-MGteam. To enhance this even further, a command called “Invoke-MgGraphRequest” allows you to pass an actual Microsoft Graph request instead of using a specific command. For example, you could use the following URL and particular properties to add a new message:

https://graph.microsoft.com/v1.0/teams/$($team.Id)/channels/$($channel.Id)/messages

The command is powerful and allows you to use a more developer-centric approach to executing PowerShell. To learn more about the Microsoft PowerShell Graph SDK in general and teams, you can use the following support pages from Microsoft: Microsoft Graph PowerShell overview and Microsoft Graph PowerShell Cmdlets.

FAQs

How can I use get-MGteam to find archived teams in Microsoft Teams?

Using get-MGteam with specific filters and parameters, you can identify archived teams by querying their status. Combine get-MGteam with additional properties like ‘-ArchiveStatus’ to retrieve a list of all archived teams in your organization.

Can get-MGteam help me identify teams without owners?

Yes, get-MGteam can be used in combination with ownership queries to identify teams that lack proper ownership. This helps maintain security and governance by ensuring all teams have designated owners.

What’s the maximum number of teams I can retrieve using get-MGteam in a single query?

The get-MGteam cmdlet can retrieve up to 999 teams per request. For organizations with more teams, you’ll need to implement pagination or use additional parameters to manage larger datasets effectively.

How can I use get-MGteam to monitor team creation dates and last activity?

Get-MGteam provides timestamp information about team creation and recent activity. By adding specific properties to your get-MGteam query, you can track when teams were created and their latest interaction dates.

Is it possible to use get-MGteam to find teams with specific naming patterns?

Get-MGteam supports wildcard searches and pattern matching, allowing you to find teams that match specific naming conventions or patterns. This is particularly useful for maintaining naming standards across your organization.