Setting up Graph API to export Microsoft Teams PSTN Usage Records with TeamsCloudCommunicationApi and Get-TeamsPSTNCallRecords PowerShell scripts

I’ve recently been involved in many Teams Direct Routing deployments and was asked by one of the clients to assist with automating the generation of PSTN usage reports so they can correctly bill each department long distance fees. Prior to this year, the only way to obtain these reports was to manually export them from the Analytics & reports > Usage reports section of the Teams admin center:

In 2020, Microsoft released the ability to programmatically retrieve Microsoft Teams PSTN Usage records using the Graph API and the following are a module and PowerShell script that Jeff Brown and Lee Ford created for the community:

Jeff Brown’s TeamsCloudCommunicationApi module
https://jeffbrown.tech/use-graph-api-to-export-microsoft-teams-pstn-usage-records/

Lee Ford’s Get-TeamsPSTNCallRecords script
https://github.com/leeford/Get-TeamsPSTNCallRecords

This was my first time using Graph API and was initially confused as to how to use the module or script so I thought I’d write a blog post outlining the exact steps required for each of the two solutions above. Note that the information is provided by both Jeff Brown, who provides a comprehensive guide for setting it up but it is in a separate post and requires a bit of scrolling and Lee Ford, who provides the information but not the comprehensive detail Jeff includes, so the purpose here is just to demonstrated what I went through to set them up. I will also include the links to Jeff’s posts for reference.

Prerequisites – Set up an Azure AD application for Graph API

The first thing you’ll need to do is create an App registration that will be used by the module or PowerShell script. This step is to create the necessary permissions for the module or script to run without requiring the person running it to log in.

Log into Azure admin portal then navigate to Azure Active Directory > App registrations and then click on New registration:

Give the application a name (this is a logical name that won’t be referenced in the module or script). For this example, I’ll be using: Graph-API-Teams-Logs with the rest of the configuration settings left as the defaults:

The configuration parameter we’ll need later is the Application (client) ID and Directory (tenant) ID so copy those into notepad:

Application (client) ID: 57c4b54b-2c88-485d-8a42-5ae62c628294
Directory (tenant) ID: 84f4470b-3f1e-4889-9f95-##############

Note that you can obtain the tenant ID in the Overview section of Azure Active Directory as well:

Next, navigate to Certificates & secrets > New client secret:

Provide a description for the secret (Graph-API-Teams-Logs), configure how long this secret will remain valid and then click add:

A client secret will be created. Copy the Value of the secret immediately as you can browse away and back to this page within a short period of time before the value becomes masked with ****:

With the client secret created, navigate to API permissions > Add a permission:

Select Microsoft Graph:

Select Application permissions:

Search for CallRecords.Read.All and add the permission:

Click on Grand admin consent for <organization name> to complete the permissions configuration:

You should now see the Status with a green check mark:

The following are the three configuration parameters that you should have after completing the steps above:

Application (client) ID: 57c4b54b-2c88-485d-8a42-5ae62c628294
Directory (tenant) ID: 84f4470b-3f1e-4889-9f95-##############
Value: Ydwo##################-aZS39Zqn

Using Lee Ford’s Get-TeamsPSTNCallRecords script

I’ll start with demonstrating how to use Lee Ford’s Get-TeamsPSTNCallRecords script because it is simpler but it did not provide me with a report I needed because the extension of the user and the number dialed was masked with a *. It also did not let me specify a date range.

Begin by downloading the PowerShell script from here: https://github.com/leeford/Get-TeamsPSTNCallRecords

Open the Get-TeamsPSTNCallRecords.ps1 script and navigate down to the following lines and fill in the appropriate values:

# Client (application) ID, tenant (directory) ID and secret
$clientId = "ddbc3c22-3a28-47c9-bfb3-3b857d97f1e0"
$tenantId = "84f4470b-3f1e-4889-9f95-###########"
$clientSecret = 'pGLJ####################hm5j_J'

Save the Get-TeamsPSTNCallRecords.ps1 and you should now be able to use the following cmdlet to export the logs:

.\Get-TeamsPSTNCallRecords.ps1 -SavePath C:\Temp -Days 50 -SaveFormat CSV

As mentioned earlier, the report appears to mask the caller and the callee’s number:

Using Jeff Brown’s TeamsCloudCommunicationApi module

Jeff Brown’s TeamsCloudCommunicationApi module provides more flexibility as you can specify the date range as well as have the caller and callee’s number displayed.

As specified in Jeff’s post (https://jeffbrown.tech/use-graph-api-to-export-microsoft-teams-pstn-usage-records/), the module can be downloaded directly from the PowerShell gallery with the command:

Install-Module -Name TeamsCloudCommunicationApi

Alternatively, the module can also be downloaded from GitHub: https://github.com/JeffBrownTech/TeamsCloudCommunicationApi

After downloading the files in this GitHub repository, the module can be imported by executing the following cmdlet:

Import-Module TeamsCloudCommunicationApi.psd1

The available commands can be displayed with the following cmdlet:

Get-Command -Module TeamsCloudCommunicationApi

Get-GraphApiAccessToken
Get-TeamsDirectRoutingCalls
Get-TeamsPstnCalls

With either the module installed or the module downloaded and imported, the next step is to generate an access token that will be used with the PowerShell cmdlet to retrieve the logs. The steps provided at GitHub: https://github.com/JeffBrownTech/TeamsCloudCommunicationApi did not work for me but the step in Jeff’s other post here did: https://jeffbrown.tech/creating-microsoft-teams-and-channels-with-graph-api-and-powershell/

The following are the lines to modify and execute to generate the access token (replace the text highlighted in red with the appropriate values):

$env:graphApiDemoAppId = "12345678-abcd-efgh-jklm-123456789abc" # Replace with your Azure AD app id

$env:graphApiDemoAppSecret = "1234567890asdfjk;l54321" # Replace with your Azure AD app secret

$env:tenantId = "12345678-abcd-efgh-ijkl-987654321wxyz" # Replace with your Azure AD tenant ID

$oauthUri = https://login.microsoftonline.com/$env:tenantId/oauth2/v2.0/token

# Create token request body

$tokenBody = @{

client_id = $env:graphApiDemoAppId

client_secret = $env:graphApiDemoAppSecret

scope = "https://graph.microsoft.com/.default"

grant_type = "client_credentials"

}

# Retrieve access token

$tokenRequest = Invoke-RestMethod -Uri $oauthUri -Method POST -ContentType "application/x-www-form-urlencoded" -Body $tokenBody –UseBasicParsing

# Save access token

$accessToken = ($tokenRequest).access_token

With the access token created, we can now use either the:

Get-TeamsDirectRoutingCalls

Get-TeamsPstnCalls

… to export the logs:

Hope this helps anyone who may not be familiar with setting up App registrations and using Graph API.

Huge thanks to Jeff Brown and Lee Ford for providing this to the community!