Microsoft Graph PowerShell SDK (alpha) out – including new Get-UserPresence and Update-UserPresence commands!

In the latest Microsoft Graph Community Call, Darrel Miller gave an introduction to the new Microsoft Graph PowerShell SDK – a new PowerShell module designed to provide an abstraction over core functionality in Microsoft Graph.

The module is so new it’s not even in the PowerShell gallery yet, but you can add it by referencing their nuget feed:

Register-PSRepository `
-Name GraphPowerShell `
-SourceLocation https://graphpowershellrepository.azurewebsites.net/nuget

# Installing the Graph PowerShell module for the Beta API 
Install-module Microsoft.Graph.Beta -Repository GraphPowerShell

There are also a full set of samples in their GitHub repo showing how to use it.

Getting and Updating Presence

One very surprising addition to the PowerShell module is the ability to get and set the Microsoft Teams presence of users. It’s surprising because, although it’s been talked about for a long time, this functionality is very new.

There are 2 new permissions needed to query presence: Presence.Read and Presence.Read.All.

There currently aren’t any published permissions for updating presence – skip to the next section to understand why, and read the concluding section for more on this.

Getting user presence via PowerShell

Once you’ve connected using Connect-Graph and made sure that you have the appropriate permissions, you can use the following command to get presence:

PS C:\Users\tom.morgan> Get-UserPresence -UserId 7b3ec448-4c70-43dc-89e1-9e764eaea4f6 

Activity Availability Id
-------- ------------ -- 
Away Away 7b3ec448-4c70-43dc-89e1-9e764eaea4f6

According to the documentation, the Availability field is the base presence, and the Activity field is any supplementary behavoir.

Possible values for Availability are: Available, AvailableIdle, Away, BeRightBack, Busy, BusyIdle, DoNotDisturb, Offline, PresenceUnknown

Possible values for Activity are: Available, Away, BeRightBack,Busy, DoNotDisturb, InACall, InAConferenceCall, Inactive,
InAMeeting, Offline, OffWork,OutOfOffice, PresenceUnknown,
Presenting, UrgentInterruptionsOnly.

Updating user presence via PowerShell

Interestingly, although there is a Update-UserPresence command, right now it doesn’t seem to work:

PS C:\Users\tom.morgan> Update-UserPresence -UserId 7b3ec448-4c70-43dc-89e1-9e764eaea4f6 -Availability "Busy"

Update-UserPresence : [NotFound] :
At line:1 char:1
+ Update-UserPresence -UserId 7b3ec448-4c70-43dc-89e1-9e764eaea4f6 -Ava ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: ({ UserId = 7b3e...GraphPresence }:<>f__AnonymousTyp     e8`2) [Update-UserPresence_UpdateExpanded], Exception
    + FullyQualifiedErrorId : NotFound,Microsoft.Graph.PowerShell.Cmdlets.UpdateUserPresence_UpdateE     xpanded

There is no documentation at all for this command, so I’m not sure if I’m correctly passing the Availability, but it looks like the error is more to do with the underlying Graph call not being present. This would line up with there also being no documentation publish about updating presence using Graph yet.

What about just using Graph?

It was something of a surprise finding this functionality in the PowerShell, which is a wrapper around Graph functionality, but it’s also something you can do in Graph (as previously talked about at Microsoft Ignite 2019 and blogged by Matt Landis). Up until a few days ago (2 days before this blog post!) there wasn’t even any documentation about it, but now there is so we can see how to also get presence directly in Graph:

The new documentation page contains all the details about the new call and the permissions needed:

You can get your own presence with: GET https://graph.microsoft.com/beta/me/presence or someone else’s presence by knowing their ID and using GET https://graph.microsoft.com/beta/users/{ID}/presence

The response object contains the same information exposed in PowerShell:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1574

{  
	"id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
	"availability": "Available",
	"activity": "Available"
}

Getting Presence of Multiple Users

In addition, there is a separate command (documented here) designed to get the presence of multiple users in one operation. It’s a POST operation, which is odd but let’s you pass the IDs in an array in the body:

POST https://graph.microsoft.com/beta/communications/getPresencesByUserId
Content-Type: application/json

{
"ids": ["fa8bf3dc-eca7-46b7-bad1-db199b62afc3", "66825e03-7ef5-42da-9069-724602c31f6b"]
}

You need to make sure you have Presence.Read.All permission for this command.

Conclusion

In conclusion, it’s great to see the ability to query presence of Microsoft Teams users in Graph – it’s a been a top User Voice ask for a while. In addition, seeing that the PowerShell SDK team have built in a presence update command in, gives me hope that fairly soon we should see this functionality light up and be able to also update presence in Graph.

A big thanks to the Microsoft Teams team, the Graph Team, the PowerShell Team, the AD Permissions Team, and however many other teams had to come together to enable this to happen: it’s a great early Christmas present for Teams developers everywhere, and I’m really excited to see what people will do with this new functionality.

Written by Tom Morgan

Tom is a Microsoft Teams Platform developer and Microsoft MVP who has been blogging for over a decade. Find out more.

---

Buy the book: Building and Developing Apps & Bots for Microsoft Teams. Now available to purchase online with free updates.

Related posts:

Using the Microsoft Teams BETA Graph API calls? They may be about to break on you… 3 API calls going away soon Accessing Microsoft Teams Usage Data in code with Microsoft Graph Coming Soon: Graph API to include capabilities for Shifts Weekly Update 26 April 2019: Breaking change for Skype for Business Phones, Bot Framework Emulator, Value of Teams, Teams PowerShell Module Microsoft Teams to get PowerShell Commands to Manage Teams