It’s been a while since I published something. This morning, one of the members on my Teams Phone Admin Group Discord Server posted a Microsoft Learn link to a new beta endpoint in Microsoft Graph.

The endpoint is called userConfigurations and will allow you to query certain properties of Teams users directly via Graph API rather than using the Teams PowerShell module. To me, the most interesting thing is to be able to retrieve users assigned phone numbers through this endpoint.

Add Scopes

To be able to make requests to this endpoint, you’ll first need to add the scope. I’m keeping it nice and easy today and I’m doing it through delegated authentication using the official Microsoft Graph Commandline Tools enterprise app.

1

Connect-MgGraph -Scopes "TeamsUserConfiguration.Read.All"

Get all Teams User Configurations

The docs only show an example for HTTP requests as of the time of writing. Therefore, I don’t believe that this has been added to the Graph Beta PowerShell modules yet. But that’s not a problem since we can just use Invoke-MgGraphRequest. I previously wrote about this here.

Invoke-MgGraphRequest does not have an -All switch so we need to make sure to fetch all users ourselves. Luckily, I also have a blog post handy for this part.

This bit will retrieve all user configurations and store it in $userConfigurations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# Get all user configurations in Microsoft Teams using the Graph API
$allPages = @()

$userConfigurations = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta//admin/teams/userConfigurations" -ContentType "application/json"
$allPages += $userConfigurations.value

if ($userConfigurations.'@odata.nextLink') {

    do {

        $userConfigurations = (Invoke-MgGraphRequest -Method Get -Uri $userConfigurations.'@odata.nextLink' -ContentType "application/json")
        $allPages += $userConfigurations.value

    } until (
        !$userConfigurations.'@odata.nextLink'
    )
        
}

$userConfigurations = ($allPages | ConvertTo-Json -Depth 99 | ConvertFrom-Json -Depth 99)

If you’re wondering, why I’m doing ($allPages | ConvertTo-Json -Depth 99 | ConvertFrom-Json -Depth 99) on the last line, this is because sometimes, the Graph API does not return proper PowerShell objects which makes accessing and processing returned data kind of hard. This is an easy workaround for that.

Filter for a User with a Specific Phone Number

Since figuring out the correct way to filter in Graph can sometimes be a bit tricky, I already constructed a working filter query that works with assigned phone numbers for you.

1
2

$phoneNumber = "+41123456789"
$filterByPhoneNumber = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta/admin/teams/userConfigurations?`$filter=telephoneNumbers/any(p:p/telephoneNumber eq '$($phoneNumber)')&`$count=true" -ContentType "application/json"

While this is quite similar to what I wrote here (Filtering Entra ID Users by phone number), it does add some additional complexity because telephoneNumbers is an array of objects and not just an array of strings. The key part is to filter on the p:p/telephoneNumber property.

Also note that you don’t get the typical tel: prefix we all know from Teams PowerShell.

Filter by Enterprise Voice Enabled

If you only want to list only users which are enterprise voice enabled, you can use this code.

1

$filterByEnterpriseVoiceEnabled = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/beta/admin/teams/userConfigurations?`$filter=isEnterpriseVoiceEnabled eq true&`$count=true" -ContentType "application/json"

Other Properties

Next to the phone number, we also get values for properties like assigned policies, feature types and enterprise voice enabled status of users.

Whats Next?

Please keep in mind that beta endpoints are subject to change and should never be used in production.

The Graph Permission Reference already hints at more endpoints coming our way. The TeamsTelephoneNumber.ReadWrite.All permissions suggests that we’ll soon be able to read and write telephone numbers of Teams users through the Graph API.

However, that endpoint is still in private preview. When I tried to hit it, I got an error message mentioning the private preview state of this endpoint. I’m definitely looking forward to seeing that (hopefully) becoming generally available soon though!