Add Members to Teams Using Add-MgTeamMember in Graph PowerShell

This guide demonstrates how to use the Add-MgTeamMember cmdlet in Microsoft Graph PowerShell to add members to Microsoft Teams. Learn how to manage team membership, add owners or members, and handle bulk operations efficiently.

The Add-MgTeamMember cmdlet allows you to add members to a Microsoft Team by providing a team ID and details about the users being added, defined through the -BodyParameter. This cmdlet is highly versatile and can be used for adding individual users, multiple users, or performing bulk user additions via a CSV file. This article provides detailed examples for each scenario and addresses potential errors administrators may encounter while using this cmdlet.

Note New-MgTeamMember is the alternative to Add-MgTeamMember cmdlet. You can also use Invoke-MgGraphRequest to Add Microsoft Team Member

Cmdlet Syntax

Add-MgTeamMember -TeamId <String> -BodyParameter <Hashtable>

• TeamId: The ID of the Microsoft Team where the member(s) will be added.
• BodyParameter: This parameter is passed as a hashtable and contains the user(s) and roles to be added to the team.

Usage Examples

Example 1: Adding a Single User to a Team

$teamId = "your-team-id"
$params = @{
    values = @(
        @{
            "@odata.type" = "#microsoft.graph.aadUserConversationMember"
            roles = @()  # No specific role assigned (member by default)
            "user@odata.bind" = "https://graph.microsoft.com/v1.0/users('user-id')"
        }
    )
}

Add-MgTeamMember -TeamId $teamId -BodyParameter $params

Note: You might get an error message, but the team member will get added to the team.

Example 2: Adding Multiple Users to a Team

$teamId = "your-team-id"
$params = @{
    values = @(
        @{
            "@odata.type" = "#microsoft.graph.aadUserConversationMember"
            roles = @("owner")  # Assigning user as an owner
            "user@odata.bind" = "https://graph.microsoft.com/v1.0/users('owner-user-id')"
        }
        @{
            "@odata.type" = "#microsoft.graph.aadUserConversationMember"
            roles = @()  # Assigning another user as a member
            "user@odata.bind" = "https://graph.microsoft.com/v1.0/users('member-user-id')"
        }
    )
}

Add-MgTeamMember -TeamId $teamId -BodyParameter $params

Note: You might get an error message, but the team member will get added to the team.

Example 3: Bulk Addition of Users from a CSV File

If you need to add many users to a team, you can automate the process by reading from a CSV file. The CSV file should contain user IDs and their roles.

UserId,Role
user1-id,owner
user2-id,member
user3-id,member

PowerShell Script to Add Users in Bulk:

$teamId = "your-team-id"
$csv = Import-Csv -Path "C:\Path\To\TeamMembers.csv"
$values = @()

foreach ($row in $csv) {
    $role = if ($row.Role -eq 'owner') { @("owner") } else { @() }
    $values += @{
        "@odata.type" = "#microsoft.graph.aadUserConversationMember"
        roles = $role
        "user@odata.bind" = "https://graph.microsoft.com/v1.0/users('$($row.UserId)')"
    }
}

$params = @{ values = $values }

Add-MgTeamMember -TeamId $teamId -BodyParameter $params

Cmdlet Tips

• Ensure Proper Permissions: The user running this cmdlet must have sufficient permissions to add members or owners to the specified team. Make sure the account has appropriate Microsoft Teams and Graph API permissions.
• Correct Formatting for User Binding: The user@odata.bind property must contain the URL format for the user. Incorrect formatting will result in errors.
• Empty Roles Assign Default Member Status: If no roles are provided, the user will be added as a member by default.

Use Cases

1. Automating Onboarding of New Employees: When onboarding new employees, especially in large organizations, adding them to relevant Microsoft Teams is a crucial step. The Add-MgTeamMember cmdlet allows for seamless automation, adding employees to project-specific teams with predefined roles.
2. Adding External Guests to Collaboration Teams: This cmdlet can be used to streamline the process of adding external partners or guest users to specific teams. By leveraging a CSV import, large numbers of guests can be added effortlessly.
3. Reassigning Roles in Teams: In the case of organizational changes or team restructuring, this cmdlet can be used to update roles and ownership across multiple teams in bulk, ensuring smooth transitions.

Possible Errors & Solutions

Error	Cause	Solution
ResourceNotFound	The provided team ID does not exist or is incorrect.	Double-check the team ID by running Get-MgTeam to ensure the team exists and is accessible.
Request_ResourceNotFound	The user specified in the user@odata.bind URL does not exist or is incorrect.	Verify that the user exists by running Get-MgUser. Ensure the user ID in the URL is correct and properly formatted.
Forbidden	The account executing the command lacks the necessary permissions.	Ensure that the executing user has sufficient Microsoft Teams administrator or member addition permissions. You may need to assign more Graph API permissions to the account.
InvalidRequest	The BodyParameter hashtable is improperly formatted.	Ensure that the format of the @odata.type and user@odata.bind properties follows the exact structure specified in the Microsoft documentation.

Frequently Asked Questions

What is Add-MgTeamMember used for?

Add-MgTeamMember is a Microsoft Graph PowerShell cmdlet used to add users as members or owners to a Microsoft Team. It supports assigning roles and managing team membership.

How can I add a single user to a team as a member?

Use the following script to add a user as a team member.

$Body = @{
    "@odata.type" = "microsoft.graph.aadUserConversationMember"
    roles = @()
    "user@odata.bind" = "https://graph.microsoft.com/v1.0/users('<UserObjectId>')"
}
Add-MgTeamMember -TeamId "<TeamId>" -BodyParameter $Body
                            

How can I add multiple users to a team using a CSV file?

Prepare a CSV file with the following format:

TeamId,UserObjectId,Role
<YourTeamId1>,<UserObjectId1>,member
<YourTeamId1>,<UserObjectId2>,owner
                                

Use this script to process the CSV and add users to teams:

$Data = Import-Csv -Path "C:\Path\To\File.csv"
foreach ($Row in $Data) {
    $Body = @{
        "@odata.type" = "microsoft.graph.aadUserConversationMember"
        roles = if ($Row.Role -eq "owner") { @("owner") } else { @() }
        "user@odata.bind" = "https://graph.microsoft.com/v1.0/users('$($Row.UserObjectId)')"
    }
    Add-MgTeamMember -TeamId $Row.TeamId -BodyParameter $Body
}
                                    

What permissions are required to add members to a team?

You need the TeamMember.ReadWrite.All permission in Microsoft Graph PowerShell. Ensure delegated or application permissions are consented before running the cmdlet.

Conclusion

The Add-MgTeamMember cmdlet is a powerful tool for automating member management in Microsoft Teams. Whether you need to add a single user, multiple users, or perform bulk additions via a CSV file, this cmdlet simplifies the process. By carefully formatting the BodyParameter and ensuring correct permissions, you can avoid common errors and achieve efficient team member management.

By integrating this cmdlet into your automation workflows, you can significantly reduce manual effort and streamline Microsoft Teams management in your organization.

Suggested Reading

• Using New-MgTeamMember to add Team Members
• Using Get-MgTeamMember to fetch Team Members
• Using Remove-MgTeamMember to remove Team Members