Webhook notification when Microsoft Teams presence changes using Graph API

Abhijeet Jadhav

Overview

There are multiple business scenarios when in an application you would need to display up to date presence information of a user from Microsoft Teams.

Microsoft had announced getPresence endpoint to get the user's presence, including their availability and user activity. However, this is a pull mechanism, your application had to make continous polling "get" call to know the current status and if the status is changed in the interim there was no way to know the latest status.

To address this issue, Microsoft has announced a presence subscription API, this API can be used to subscribe other users presence in Microsoft Teams.

Once you create a subscription for the presence for a user and register a HTTPS endpoint to receive a notification, Microsoft Graph will tell you when there are changes. Typically this subscription is good for up to 60 minutes but you can renew them using the "update subscription" endpoint.

In this article, we will see the step by step configuration to get the users presence status from Microsoft Teams automatically.

Prerequisites

App registered in Azure active directory(AAD) with Presence.Read and Presence.Read all delegated permissions.
Install ngrokTool (For Development)
HTTPS endpoint up and running (For PROD)

Create a web API to receive notifications :

Microsoft Graph will send notifications to a registered HTTPS endpoint. In this case, we will create a ASP.NET Core web API, to receive the notifications.

ngrok is a free tool for sharing projects online that are created in localhost. During development, you can use the ngrok tool to tunnel the requests via the internet.

1. Open the command prompt and navigate to the directory where you would like to create the project

2. Execute below commands to create ASP.net core Web API

dotnet new webapi -o PresenceReceiverAPI

3. Once the project is created, navigate to the project directory and execute below commands in the command prompt:

Pl note we are using Microsoft.Graph.Beta instead of Microsoft.Graph so that we can call the beta endpoint of Microsoft Graph API.

cd PresenceReceiverAPI
dotnet add package Microsoft.Identity.Client
dotnet add package Microsoft.Graph.Beta --version 0.20.0-preview
dotnet run

4.Once you excute above commands application will start and display following in the console:

info: Microsoft.Hosting.Lifetime[0]
Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[0]
Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
Content root path: [your file path]\PresenceReceiverAPI

5. Press Ctrl+C to stop the application and open your favorite IDE (I like Visual Studio Code..

) to add controllers that receive the notifications.

6. Add below function in the controller class to receive the notification.

[HttpGet]
public async Task<ActionResult<string>> Get()
{
var graphServiceClient = GetGraphClient();
var sub = new Microsoft.Graph.Subscription();
sub.ChangeType = "updated";
sub.NotificationUrl = config.Ngrok + "/api/notifications";
sub.Resource = "/users";
sub.ExpirationDateTime = DateTime.UtcNow.AddMinutes(5);
sub.ClientState = "SecretClientState";
var newSubscription = await graphServiceClient
.Subscriptions
.Request()
.AddAsync(sub);
Subscriptions[newSubscription.Id] = newSubscription;
if (subscriptionTimer == null)
{
subscriptionTimer = new Timer(CheckSubscriptions, null, 5000, 15000);
}
return $"Subscribed. Id: {newSubscription.Id}, Expiration: {newSubscription.ExpirationDateTime}";
}

7. Add below function in the controller class, to verify the validationToken and process the received notification.

public async Task<ActionResult<string>> Post([FromQuery]string validationToken = null)
{
// verify the validation token
if (!string.IsNullOrEmpty(validationToken))
{
Console.WriteLine($"Received Token: '{validationToken}'");
return Ok(validationToken);
}
// process the notifications and display on the console
using (StreamReader reader = new StreamReader(Request.Body))
{
string content = await reader.ReadToEndAsync();
Console.WriteLine(content);
var notifications = JsonConvert.DeserializeObject<Notifications>(content);
foreach (var notification in notifications.Items)
{
Console.WriteLine($"Received notification: '{notification.Resource}', {notification.ResourceData?.Id}");
}
}
await CheckForUpdates();
return Ok();
}

8. Once you add the code to fetch the access token, "controller" code should be as below:

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using msgraphapp.Models;
using Newtonsoft.Json;
using System.Net;
using System.Threading;
using Microsoft.Graph;
using Microsoft.Identity.Client;
using System.Net.Http.Headers;
namespace PresenceReceiverAPI.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class NotificationsController : ControllerBase
{
private readonly MyConfig config;
public NotificationsController(MyConfig config)
{
this.config = config;
}
[HttpGet]
[HttpGet]
public async Task<ActionResult<string>> Get()
{
var graphServiceClient = GetGraphClient();
var sub = new Microsoft.Graph.Subscription();
sub.ChangeType = "Updated";
sub.NotificationUrl = config.Ngrok + "/api/notifications";
sub.Resource = "/communications/presences/" + config.User;
sub.ExpirationDateTime = DateTime.UtcNow.AddMinutes(5);
sub.ClientState = "SecretClientState";
var newSubscription = await graphServiceClient
.Subscriptions
.Request()
.AddAsync(sub);
Subscriptions[newSubscription.Id] = newSubscription;
if (subscriptionTimer == null)
{
subscriptionTimer = new Timer(CheckSubscriptions, null, 5000, 15000);
}
return $"Id of the Subscription: {newSubscription.Id}, Subscription Expires on: {newSubscription.ExpirationDateTime}";
}
public async Task<ActionResult<string>> Post([FromQuery]string validationToken = null)
{
// handle validation
if(!string.IsNullOrEmpty(validationToken))
{
Console.WriteLine($"Received Token: '{validationToken}'");
return Ok(validationToken);
}
// handle notifications
using (StreamReader reader = new StreamReader(Request.Body))
{
string content = await reader.ReadToEndAsync();
Console.WriteLine(content);
var notifications = JsonConvert.DeserializeObject<Notifications>(content);
foreach(var notification in notifications.Items)
{
Console.WriteLine($"Received notification: '{notification.Resource}', {notification.ResourceData?.Id}");
}
}
return Ok();
}
private GraphServiceClient GetGraphClient()
{
var graphClient = new GraphServiceClient(new DelegateAuthenticationProvider((requestMessage) => {
// get an access token for Graph
var accessToken = GetAccessToken().Result;
requestMessage
.Headers
.Authorization = new AuthenticationHeaderValue("bearer", accessToken);
return Task.FromResult(0);
}));
return graphClient;
}
private async Task<string> GetAccessToken()
{
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(config.AppId)
.WithClientSecret(config.AppSecret)
.WithAuthority($"https://login.microsoftonline.com/{config.TenantId}")
.WithRedirectUri("https://daemon")
.Build();
string[] scopes = new string[] { "https://graph.microsoft.com/.default" };
var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();
return result.AccessToken;
}
}
}

Create Subscription

1) Create a change notification subscription by submitting an HTTP POST request to the subscriptions endpoint:

https://graph.microsoft.com/beta/subscriptions

Let's look at the parameters that are required :

changeType - when should the notification trigge. Presence subscription API only support "Updated" parameter.
notificationUrl - registered HTTPS Endpoint which is up and running. If the endpoint is down, subscription is not created.
resource - Presence parameter. There are two options to get the presence status : For single-user presence - /communications/presences/{id} For multiple user presence /communications/presences?$filter=id in ({id},{id}...)

expirationDateTime - subscription expiration time no more than 60 minutes from the time subscription is created.

Typical Post request will appear as below :

{
"changeType": "Updated",
"clientState": "SecretClientState",
"notificationUrl": "https://f44426ca147b.ngrok.io/api/notifications",
"resource": "/communications/presences/9974a8dc-d808-421e-8f31-76fbf74f7f1f",
"expirationDateTime": "2020-08-08T04:30:28.2257768+00:00"
}

Test the application:

1. Within Visual Studio Code, select Run > Start debugging to run the application.

2. Navigate to the following url: http://<URL created in ngrok>/api/notifications. This will register a new subscription.

3. Now change the status of the user for which subscription is created in Microsoft teams

4. As soon as you change the status, a notification will be triggered and visible in your console.

Below is a typical notification response your HTTPS endpoint will receive, once the status of a user is changed.

Two key properties are returned by API :

availability, or base presence information e.g: Available, Away, Busy
activity, or information that’s supplemental to the availability e.g: InAMeeting, InACall

{
"value": [
{
"subscriptionId": "1221b5ed-ec3f-4036-ac38-042838d55a6f",
"clientState": "SecretClientState",
"changeType": "updated",
"resource": "communications/presences({id})",
"subscriptionExpirationDateTime": "2020-08-07T21:39:48.2162893+00:00",
"resourceData": {
"@odata.type": "#Microsoft.Graph.presence",
"@odata.id": "communications/presences({id})",
"id": null,
"activity": "Busy",
"availability": "Busy"
},
"tenantId": "eafd6ad4-0e37-4c74-b8b4-93a6118d9e75"
}
]
}

View Live Demo here

Note :

Presence subscription API is currently in public preview in Microsoft Graph beta.
It only supports Delegated user permissions, which means deamon application cannot call this API (as of now).
Microsoft.Graph NuGet package points to the Microsoft Graph v1.0 version, so you cannot create a subscription using it.

6 Comments

Join the conversation! Your thoughts help the community grow.

Developer3y ago
If we would like to implement same in a custom Teams BOT, what would be the approach
Harri Kylliäinen5y ago
How would you add automatic subscription creation without navigating to http://.../api/notifications?
Martin Pfeifer6y ago
How do I get the id?Every time it appears as null
- Abhijeet Jadhav6y ago
  Do you mean User Guid? If yes, you can either use postman or graph explorer. If not, pl provide further details
- Martin Pfeifer6y ago
  It's actually about the return of the presence's webhook. in the scenarios of capturing the presence of only one user or several, it returns only the activity and availability and the id is always null on resourceData.
- Abhijeet Jadhav6y ago
  Yes, I have observed too. Resource Data Id is null. However, user presence Id is returned in this field : "resource": "communications/presences({id})", In my case that is important than resourceData Id. This API is in preview, I would expect fine tuning of these glitches.