A long asked for API feature, the ability to pragmatically collect the PSTN call records and charges from Microsoft Teams, e.g. the phone bill. Up until now, you have only been able to get this by exporting it from the Teams Admin Center into Excel, but now, in beta, you can collect these records from Microsoft Graph.
It forms part of the call records API. The Microsoft docs for the API call: callRecord: getPstnCalls
You can expect to see lots of call reporting/bill generation products to use this API to collect this information for billing. Many large organisations cross charge their telephony costs by country or department.
This is something Modality Systems (who I work for) have been doing for some time in a somewhat bespoke way for large enterprises by automating the export of the the excel report from the Teams Admin Center (basically making automated website calls) into SQL then into Power BI. Still, the API will provide a much more robust and supportable method to export the data from Microsoft.
APIs under /beta
in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported, but hopefully, this will come out of beta too. I will update the blog when it is out of beta.
This will cover any PSTN call scenarios
- Microsoft PSTN Audio Conferencing
- Microsoft Calling Plans
- Microsoft Communications Credits
- Microsoft Call Queues and Auto Attendants (the PSTN legs)
- Direct Routing (though with no charges/costs since that information is not held by Microsoft)
Lee Ford at Symity was very fast in producing a PowerShell script to collect the call records from the API. You can check out his work here. Thanks Lee!
The API will give you the following for each record:
Property | Type | Description |
id | String | Unique call identifier. GUID. |
callId | String | Call identifier. Not guaranteed to be unique. |
userId | String | Calling user’s ID in Graph. GUID. This and other user info will be null/empty for bot
call types (ucap_in, ucap_out). |
userPrincipalName | String | UserPrincipalName (sign-in name) in Azure Active Directory. This is usually the same as the user’s SIP Address and can be same as the user’s e-mail address. |
userDisplayName | String | Display name of the user. |
startDateTime | DateTimeOffset | Call start time. |
endDateTime | DateTimeOffset | Call end time. |
duration | Int32 | How long the call was connected, in seconds. |
charge | Double | Amount of money or cost of the call that is charged to your account. |
callType | String | Whether the call was a PSTN outbound or inbound call and the type of call such as a
call placed by a user or an audio conference. |
currency | String | Type of currency used to calculate the cost of the call (ISO 4217). |
calleeNumber | String | The number dialed in E.164 format. |
usageCountryCode | String | Country code of the user, ISO 3166-1
alpha-2. |
tenantCountryCode | String | Country code of the tenant, ISO 3166-1
alpha-2. |
connectionCharge | Double | Connection fee price. |
callerNumber | String | Number that received the call for inbound calls or the number dialed for outbound
calls. E.164 format. |
destinationContext | String | Whether the call was domestic (within a country or region) or international (outside a
country or region) based on the user’s location. |
destinationName | String | Country or region dialed. |
conferenceId | String | ID of the audio conference. |
licenseCapability | String | The license used for the call. |
inventoryType | String | User’s phone number type, such as a service of toll-free number. |
[…] A long asked for API feature, the ability to pragmatically collect the PSTN call records and charges from Microsoft Teams, e.g. the phone bill. Up until now, you have only been able to get this by exporting it from the Teams Admin Center into Excel, but now, in beta, you can collect these records from… — Read on tomtalks.blog/2020/08/microsoft-teams-pstn-call-records-log-bill-from-microsoft-graph-api/ […]
[…] Yes, you now can Microsoft Teams PSTN Call Records Log / Bill from Microsoft Graph API […]
Excellent – Straight forward and accurate. Thanks Guys Tom and Lee.
I don’f find anything related to call queue or Automatic Attendant.
Hi Tom,
Do you happen to know if this is the only way to retrieve notification (indirect) of when a call (pstn) is received?
And how much lag time would there be from the time of a call being received to the time it would appear in this call log?
I’m looking to get as close to real-time as possible and this appears to be the only available method for identifying incoming pstn calls.
Thanks for your article and reply.
Ryan
Hello Tom,
Why the Id (Unique call identifier. GUID.) is not the mandatory parameter for the GET /communications/callRecords/{id}? How can I get the Call Queues records from this MS Graph API?