I bots di Teams sono una funzionalità di Azure utilizzata per permettere agli utenti di interagire con delle chat automatizzate tramite App di Teams.
Essi possono accedere tramite Graph API alle risorse di Azure, come ad esempio l’Entra e lo SharePoint.
Opzionalmente un bot può essere in grado di gestire le chiamate, ad esempio potrebbe essere impiegato per ricevere le chiamate dei clienti ed instradarle verso l’interno corretto.

PREREQUISTI

Una workstation con installato Visual Studio, un server Windows, un server Linux con HAProxy e un tenant su Azure.

ARCHITETTURA SERVIZIO

Il funzionamento di un bot di Teams prevede l’impiego sia di risorse sul cloud che on-premise.
Il servizio è composto da tre componenti principali:

• Bot Service su Azure con relativa Azure App (se in modalità Single Tenant o Multi Tenant) o Managed Identity (se in modalità User-Assigned Managed Identity)
• Webapp sviluppata con Bot Framework (SDK) esposta su internet da un server on-premise
• App di Teams (facoltativa)

In seguito uno schema che raffigura l’architettura generica del servizio:

INTRODUZIONE AI BOT SERVICES

Bot Services di Azure è una piattaforma dedicata alla creazione e al mantenimento di chat bots.
I chat bots vengono aggiunti ad un Resource Group e vengono associati ad un piano di fatturazione, quello standard permette l’invio di un migliaio di messaggi gratuitamente.
La modalità di autenticazione del bot utilizzata è Multi Tenant, poiché è la modalità compatibile con gli esempi disponibili in rete di calling bots.
Le modalità Single Tenant e Multi Tenant prevedono l’utilizzo di un’Azure App per l’interazione con le API di Graph.

INTRODUZIONE ALL’APP DI TEAMS

È possibile interagire con il bot in tre modi:

• Bot Framework Emulator (solo dev)
• Tramite la funzionalità Test in Web Chat sul portale Azure (solo dev)
• App di Teams

Il Bot Framework Emulator non funziona dopo che il bot viene registrato su Azure, perciò è utile solo nelle fasi iniziali dello sviluppo del software.
La funzionalità Test in Web Chat non mostra correttamente gli elementi grafici nella chat, perciò è difficilmente utilizzabile.
L’app di Teams è sicuramente l’opzione migliore per effettuare il testing per il bot.
Nel caso di questa implementazione, in cui il bot deve solo effettuare chiamate, non è necessario il deploy dell’app di Teams per gli utenti finali, tuttavia si consiglia l’utilizzo di quest’ultima in fase di sviluppo.
Per effettuare il deploy manuale dell’app potrebbe essere necessaria la modifica delle policies di Teams.

La seguente policy può essere abilitata tramite Teams Admin Center per gli utenti che necessitano l’installazione di app custom:

INTRODUZIONE ALLA WEBAPP

I messaggi e le chiamate effettuate con il bot avvengono tramite richieste HTTP verso una webapp su un server on-premise.
Per sviluppare il bot è necessario utilizzare il Bot Framework (SDK) che è disponibile per diversi linguaggi di programmazione (Python, JavaScript, C#…).
Su GitHub sono disponibili degli esempi in più linguaggi di programmazione, ma poiché l’unico esempio disponibile per un calling bot è in C#, è stato utilizzato questo linguaggio per questa implementazione.
Tipicamente le webapp .NET in C# vengono sviluppate su Visual Studio e viene impiegato IIS come web server in produzione.
Nel caso in cui la webapp sia offline e si richiedesse tramite API di creare una chiamata di Teams, essa farebbe comunque squillare i clients dei partecipanti, però il bot non emetterebbe suoni (si comporterebbe come se fosse mutato anche se non lo è).

UTILIZZO DI UN REVERSE PROXY

In produzione per effettuare SSL offloading della webapp necessaria per il bot si consiglia di utilizzare HAProxy.
Potenzialmente sarebbe possibile configurare IIS per utilizzare il TLS per le connessioni, però l’utilizzo di un reverse proxy esterno è un approccio più efficiente e sicuro.
In fase di sviluppo è necessario utilizzare software come “ngrok” per permettere ad Azure di poter contattare la webapp sul proprio PC.
Ngrok è gratuito e permette la registrazione di un dominio statico con relativo certificato SSL senza costi aggiuntivi.

CREAZIONE DEL RESOURCE GROUP DI AZURE

Per creare un Azure Bot Service è necessario avere a disposizione un Resource Group in cui aggiungerlo.
Recarsi su Portal Azure e loggarsi con un’utenza con privilegi a sufficienza (non basta essere Global Admin, sono anche necessari i permessi relativi alle Subscriptions).
Nella sezione Resource Groups è possibile verificare se è già presente il gruppo di risorse, oppure è possibile crearne uno.
Per creare un nuovo gruppo cliccare su Create:

Compilare i dettagli richiesti e proseguire con la creazione del gruppo:

CREAZIONE DEL AZURE BOT

Dopo aver selezionato quale gruppo di risorse si vuole utilizzare, è necessario tornare sulla homepage di Portal Azure e cliccare su Create a resource:

Cercare Azure Bot e selezionarlo tra le opzioni del Marketplace:

Cliccare su Create per proseguire:

Assegnare un nome al Bot ed il resource group:

Scorrere al fondo della pagina, assicurarsi che il tipo di App sia configurato come Multi Tenant, selezionare Create new Microsoft App ID ed infine cliccare su Review + Create per proseguire:

Infine cliccare su Create per completare la creazione del bot.

CONFIGURAZIONE DELL’AZURE APP DI AZURE

Navigare nella sezione App registrations di Portal Azure:

Selezionare il menù All applications e cliccare sul’app relativa al bot appena creato (sono omonimi).
Nella sezione API permissions è possibile assegnare i permessi necessari:

Cliccare su Add a permission, successivamente su Microsoft Graph e su Application permissions e selezionare i seguenti permessi:

Se si volesse utilizzare l’app anche per interrogare Teams per ottenere i turni (Shift) ad esempio per implementare un bot per la reperibilità notturna, è necessario assegnare anche il seguente permesso:

Infine per rendere effettivi i permessi è necessario cliccare su Grant admin consent for… e acconsentire con un Global Admin le modifiche.
Nella sezione Certificates & secrets è possibile creare il secret (password) utilizzato dalla webapp per l’autenticazione su Azure:

È possibile utilizzare un certificato per l’autenticazione, tuttavia il metodo consigliato è tramite secret.
Recarsi nella sezione Client secrets e cliccare New client secret per aggiungere un nuovo segreto:

Si consiglia di fornire una descrizione chiara e di configurare la scadenza semestrale.
Annotarsi subito il segreto appena generato, perché non sarà possibile effettuarlo in un secondo momento.
Nella sezione Overview è possibile leggere i dettagli dell’app, come l’Application ed il Tenant ID:

I dati richiesti per continuare le configurazioni sono i seguenti:

• Application ID
• Tenant ID
• Secret (dallo step precedente)

Dopo essersi annotati i precedenti dettagli, è possibile proseguire con la configurazione del Bot.

CONFIGURAZIONE DEL AZURE BOT SERVICE

Tornare sulla homepage di Portal Azure e selezionare Bot Services:

Cliccare sul bot che si vuole configurare.
Nella sezione Bot Profile è possibile personalizzare il bot, modificando il nome (DisplayName) e l’icona:

Accedere alla sezione Configuration e configurare il Messaging endpoint:

Il Messaging endpoint è composto dallo schema (https), da un FQDN e tipicamente termina con /api/messages.
L’FQDN può essere il nome DNS della webapp esposta su internet, oppure in fase di sviluppo il nome DNS fornito da Ngrok o software analoghi.
È possibile modificare il Messaging endpoint in ogni momento e se non si è ancora a conoscenza del FQDN che si vuole utilizzare, è possibile rimandare questo step.
Dato che gli utenti accedono al bot tramite Teams app e non hanno la necessità di conoscere l’URL di quest’ultimo, si consiglia l’utilizzo di un nome DNS complesso, in modo da evitare che il servizio sia facilmente raggiungibile da utenti mal intenzionati.

Accedere alla sezione Channels per configurare i canali:

È possibile utilizzare il servizio Azure Bot per implementare bots su altre piattaforme oltre che Teams, ma per lo scopo di questo documento, verrà mostrata solamente la configurazione dei canali Microsoft Teams e Microsoft 365.
Tutti i canali disponibili sono elencati nella sezione Available Channels:

Selezionare Microsoft 365:

Confermare cliccando su Apply:

Per proseguire la configurazione del canale Microsoft Teams è necessario aver configurato il Messaging endpoint, se non si ha ancora a disposizione il nome DNS che si vuole utilizzare, è possibile rimandare questo step.
Tornare nella sezione Available Channels e selezionare Microsoft Teams:

Accettare i termini e condizioni per proseguire.
Assicurarsi che nella sezione Messaging sia selezionato Microsoft Teams Commercial e navigare nella sezione Calling per configurare il Webhook URL:

Il Webhook URL è composto dallo schema (https), da un FQDN e tipicamente termina con /callback.
L’FQDN utilizzato è lo stesso utilizzato per il Messaging endpoint.
È possibile modificare il Webhook URL in ogni momento e se non si è ancora a conoscenza del FQDN che si vuole utilizzare, è possibile rimandare questo step lasciando disabilitata l’opzione Enable calling.
Concludere la configurazione del canale Microsoft Teams cliccando su Apply.

AVVIARE LA WEBAPP LOCALMENTE

Lo sviluppo della webapp necessita l’utilizzo di Teams SDK, che è disponibile in diversi linguaggi, tra cui JavaScript, Python e C#.
Su GitHub sono presenti diversi esempi di bot sviluppati con Teams SDK, in particolare lo sviluppo della webapp utilizzata in questa implementazione è partita dal seguente esempio:

https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-calling-meeting/csharp

Per proseguire con i seguenti step, è necessario aver installato Git sulla macchina che si sta utilizzando per lo sviluppo.

Clonare il repository localmente:

Copiare la seguente directory della repository in una posizione a piacere sul filesystem: samples/bot-calling-meeting/csharp

Per aprire la soluzione è necessario l’utilizzo di Visual Studio, navigare nella directory Source e aprire il file CallingBotSample.sln.
Tramite la funzionalità Find and Replace di Visual Studio, è possibile rinominare CallingBotSample in tutte le classi della soluzione.
Prima di poter avviare il bot è necessario modificare il file appsettings.json, compilando i dettagli ottenuti negli step precedenti:

• AppId (o ClientId o MicrosoftAppId)
• AppSecret (o ClientSecret o MicrosoftAppPassword)
• TenantId
• BotBaseUrl

Avviare il bot premendo il tasto play:

Avviare il tunnel tramite Ngrok:

Se si ha a disposizione un’URL statico, è possibile specificarlo tramite il flag url:

Se tutte le configurazioni sono state effettuate correttamente, tramite la funzionalità Test in Web Chat su Portal Azure, oppure tramite app di Teams (vedi prossimi capitoli), è possibile comunicare con il bot.

AGGIORNARE LE DIPENDENZE DELLA WEBAPP

L’esempio utilizzato ha diverse dipendenze non aggiornate, deprecate e vulnerabili.
Tramite il package manager NuGet è possibile aggiornare le dipendenze, però prima di poter rimuovere una libreria deprecata è necessario il refactoring del codice.
Per aggiornare le dipendenze, effettuare il click con il tasto destro del mouse in prossimità di “Dependencies” e cliccare su Manage NuGet Packages…:

Navigare nella sezione Updates ed aggiornare tutte le dipendenze all’ultima versione disponibile, meno che i seguenti pacchetti:

• Microsoft.Graph (max version 4.54.0)
• MicrosoftGraph.Comunications.Calls (max version 1.2.0.7270)
• Microsoft.Graph.Comunications.Core (max version 1.2.0.7270)

Affinché sia possibile aggiornare a versione successive i precedenti pacchetti, è necessario effettuare un ulteriore refactoring del codice, che al momento della stesura di questa guida non ho ancora effettuato.

Per far sì che il codice venga aggiornato e compilato correttamente, potrebbe essere necessario installare le seguenti librerie (di cui una deprecata, che verrà mostrato come rimuoverla nel prossimo capitolo):

RIMOZIONE DELLA LIBRERIA DEPRECATA Microsoft.IdentityModel.Clients.ActiveDirectory

La libreria deprecata Microsoft.IdentityModel.Clients.ActiveDirectory, è stata sostituita dalla seguente libreria (di cui è necessaria l’installazione):

Il refactoring avviene per il file Authentication/AuthenticationProvider.cs.

Innanzitutto è necessario sostituire l’importazione della libreria deprecata:

@@ -11,7 +11,7 @@ using System.Threading.Tasks;
using Microsoft.Graph.Communications.Client.Authentication;
using Microsoft.Graph.Communications.Common;
using Microsoft.Graph.Communications.Common.Telemetry;
– using Microsoft.IdentityModel.Clients.ActiveDirectory;
+ using Microsoft.Identity.Client;

Successivamente nella funzione AuthenticateOutboundRequestAsync sarà necessario rimpiazzare la modalità legacy di autenticazione ed opzionalmente modificare il commento:

@@ -51,7 +51,7 @@ namespace CallingBot.Authentication
/// <summary>
/// Authenticates the specified request message.
/// This method will be called any time there is an outbound request.
–      /// In this case we are using the Microsoft.IdentityModel.Clients.ActiveDirectory library
+     /// In this case we are using the Microsoft.Identity.Client library
/// to stamp the outbound http request with the OAuth 2.0 token using an AAD application id
/// and application secret. Alternatively, this method can support certificate validation.
/// </summary>
@@ -73,13 +73,15 @@ namespace CallingBot.Authentication
var tokenLink = oauthV2TokenLink.Replace(replaceString, tenant);
this.GraphLogger.Info(“AuthenticationProvider: Generating OAuth token.”);
–         var context = new AuthenticationContext(tokenLink);
–         var creds = new ClientCredential(this.appId, this.appSecret);
+        var context = ConfidentialClientApplicationBuilder.Create(this.appId)
+                .WithClientSecret(this.appSecret)
+                .WithAuthority(tokenLink)
+                .Build();

Infine, sarà necessario modificare la funzione AcquireTokenWithRetryAsync per renderla compatibile con la libreria aggiornata:

@@ -188,7 +190,7 @@ namespace CallingBot.Authentication
/// <returns>
/// The <see cref=”AuthenticationResult” />.
/// </returns>
–        private async Task<AuthenticationResult> AcquireTokenWithRetryAsync(AuthenticationContext context, string resource, ClientCredential creds, int attempts)
+       private async Task<AuthenticationResult> AcquireTokenWithRetryAsync(IConfidentialClientApplication context, string resource, int attempts)
{
while (true)
{
@@ -196,7 +198,7 @@ namespace CallingBot.Authentication
try
{
–              return await context.AcquireTokenAsync(resource, creds).ConfigureAwait(false);
+             return await context.AcquireTokenForClient([$”{resource}/.default”]).ExecuteAsync().ConfigureAwait(false);
}
catch (Exception)
{

Dopo aver completato il refactoring del codice sarà possibile procedere con la disinstallazione della libreria Microsoft.IdentityModel.Clients.ActiveDirectory.

CONFIGURAZIONE DELL’APP DI TEAMS

La struttura del codice dell’app è molto semplice, ed è composta da tre files:

• manifest.json
• color.png
• outline.png

È disponibile un esempio nella directory “AppManifest” nella soluzione del calling bot di esempio.

Il file “manifest.json” contiene tutte le configurazioni dell’app.
Il file contiene multipli valori che bisogna compilare con l’ID del Azure Bot Service:

• Id
• webApplicationInfo.id
• bots[0].botId

È possibile modificare le informazioni dello sviluppatore modificando l’oggetto developer:

“developer”: {
“name”: “Marco Valle”,
“websiteUrl”: “https://www.raffaelechiatto.com”,
“privacyUrl”: “https://teams.microsoft.com”,
“termsOfUseUrl”: “https://teams.microsoft.com”
},

Per rinominare i files dei loghi è necessario modificare l’oggetto icons:

“icons”: {
“color”: “color.png”,
“outline”: “outline.png”
},

Gli oggetti name e descriptions contengono le informazioni relative al bot:
“name”: {
“short”: “Calling bot”,
“full”: “Calling bot”
},
“description”: {
“short”: “Calling bot”,
“full”: “Custom calling bot”
},

L’array “validDomains” contiene tutti i domini validi per l’interazione con Azure Bot Service, aggiungere il dominio configurato precedentemente su Azure:

“validDomains”: [
“example.pizza.com”
],

CREAZIONE DEI LOGHI PER L’APP DI TEAMS

I loghi utilizzati dall’app di Teams sono salvati in due files:

• color.png
• outline.png

Il primo file contiene il logo colorato con dimensioni 96×96 pixels inserito un’immagine con sfondo monocromatico (o vuoto) di 192×192 pixels:

Il secondo file contiene l’outline del logo con dimensioni 32×32 pixels:

Si consiglia di utilizzare Adobe Illustrator per creare l’outline del logo.
Nella maggior parte dei casi viene utilizzata l’icona colorata; l’outline, ad esempio, viene mostrata nella barra delle app di Teams:

INSTALLAZIONE DELL’APP SU TEAMS

Creare un file ZIP contenente i tre files (non inserirli in una directory):

• manifest.json
• color.png
• outline.png

Aprire l’app di Teams e navigare sull’icona con tre punti e selezionare Scarica altre applicazioni:

Cliccare su Gestisci le tue app:

Selezionare Carica un’app:

Selezionare Carica un’app personalizzata (se l’opzione non fosse disponibile verificare le policy dell’organizzazione su Teams Admin Center):

Effettuare l’upload del file ZIP e verificare che il bot venga mostrato tra le proprie app.

INSTALLAZIONE DI IIS SUL WEB SERVER

Aprire il Server Manager, selezionare Add Roles and Feature nel menù Manage:

Proseguire selezionando Next:

Proseguire selezionando Next:

Selezionare il server e proseguire selezionando Next:

Spuntare Web Server (IIS) tra i Server Roles disponibili:

Nella finestra che viene aperta selezionare Add Features:

Proseguire selezionando Next:

Selezionare nuovamente Next per proseguire:

Rimuovere la spunta ai Role Services Default Document e Directory Browsing, proseguire selezionando Next:

Concludere l’installazione cliccando su Install:

Quando l’installazione è terminata, è possibile chiudere la finestra selezionando Close:

INSTALLAZIONE DI ASP.NET CORE RUNTIME SUL WEB SERVER

La versione .NET supportata dal calling bot è la 6; al momento della stesura di questo articolo l’ultima versione di .NET 6 è la 6.0.36.
Navigare sul sito ufficiale Microsoft per effettuare il download dell’installer:

https://dotnet.microsoft.com/en-us/download/dotnet/6.0

Effettuare il download dell’installer ASP.NET Core Runtime denominato Hosting Bundle:

Avviare l’installer, accettare la licenza e proseguire con l’installazione selezionando Installa:

CONFIGURAZIONE DELL’HEADER X-FORWARDED-FOR SUL WEB SERVER

Facendo uso di un reverse proxy di fronte ad IIS, i logs mostreranno come IP sorgente delle richieste l’IP del proxy.
Aggiungere ai logs il valore dell’header X-Forwarded-For è una strategia per la preservazione dell’IP sorgente nei logs.
Per aggiungere l’header ai logs, aprire la console di gestione di IIS:

Selezionare Logging:

Selezionare Select Fields…:

Selezionare Add Field…:

Compilare il nome del campo e il nome dell’header (in questo caso entrambi X-Forwarded-For) ed assicurarsi che il Source Type sia Request Header:

Concludere la modifica selezionando Ok ed applicarla cliccando su Apply nel menù Logging:

CONFIGURAZIONE DEL SITE SU IIS

Il Site di IIS è l’equivalente del VHOST di Apache2.
Per creare la struttura di directories necessaria per l’applicazione eseguire i seguenti comandi in una PowerShell amministrativa sul web server (sostituire MyAspApp con il nome del bot):

La directory publish verrà utilizzata per la pubblicazione dell’app, invece la directory logs verrà utilizzata per salvare i logs.
Prima di proseguire alla creazione del Site è preferibile creare un Application Pool, per farlo selezionare Application Pools e cliccare su Add Application Pool…:

Assegnare un nome al pool, selezionare No Managed Code e confermare cliccando su OK:

Dopo aver creato l’Application Pool è possibile proseguire con la creazione del Site, selezionare Sites e cliccare su Add Website…:

Assegnare un nome al sito, selezionare l’Application Pool creato durante gli step precedenti, selezionare la directory publish creata precedentemente, compilare il nome DNS (lo stesso configurato su Azure) e confermare cliccando su OK:

Selezionare il sito appena creato e cliccare su Logging:

Modificare la directory da utilizzare per i logs, inserendo a quella creata precedentemente, infine applicare la modica cliccando su Apply:

DEPLOY DELLA WEBAPP SU IIS

Il deploy dell’app su IIS può avvenire in diversi modi, in questa guida verrà descritta la metodologia di deploy manuale.

Aprire la soluzione su Visual Studio, selezionare Build e poi Publish NomeApp:

Selezionare il target Folder:

Opzionalmente modificare il path della directory in cui si vuole salvare l’app compilata e proseguire selezionando Finish:

Concludere selezionando Close:

Le volte successive che si vorrà pubblicare l’app sarà sufficiente selezionare Publish per aggiornare la directory con l’app compilata:

Dopo aver effettuato la compilazione dell’app tramite Visual Studio, navigare nella directory bin\Release\net6.0\publish all’interno della directory della soluzione.
Modificare il file appsettings.json con i valori da utilizzare per la produzione e zippare il contenuto della directory.
Copiare il file zippato sul web server ed estrarre il suo contenuto nella directory publish creata in fase di configurazione di IIS (eg. C:\MyAspApp\publish).
Se si vuole effettuare un aggiornamento della web app, è consigliato fermare il sito su IIS, rimuovere il contenuto della directory, copiare il contenuto del file ZIP al suo interno e avviare nuovamente il sito su IIS.
Se il sito non è ancora stato pubblicato su internet tramite reverse proxy, aggiungere al file hosts il nome DNS che punti all’IP del web server ed infine provare ad accedervi tramite browser.

CONFIGURAZIONE DEL FRONTEND DI HAPROXY

Aggiungere nel frontend desiderato l’ACL (sostituire l’FQDN con il nome desiderato):

Sempre nel frontend, aggiungere la regola per il routing della richiesta:

 

CONFIGURAZIONE DEL BACKEND DI HAPROXY

Aggiungere un backend dedicato al servizio del bot:

Le seguenti opzioni sono state abilitate per acconsentire l’utilizzo dei web sockets:

La seguente direttiva è stata aggiunta per sovrascrivere l’header Server che IIS invia di default:

 

RICHIEDERE UN BEARER TOKEN TRAMITE GRAPH API

Il Bearer Token viene utilizzato nelle chiamate API per l’autenticazione e l’autorizzazione delle richieste.
Tendenzialmente il token ha una durata di mezz’ora, successivamente è necessario richiedere un nuovo token.
Per richiedere un token sono necessarie le credenziali di un’app (AppId, AppSecret e TenantId).

POST https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token

Headers:

Key	Value
Content-Type	application/x-www-form-urlencoded

Body (x-www-form-urlencoded):

Key	Value
client_id	$APP_ID
client_secre	$APP_SECRET
scope	https://graph.microsoft.com/.default
grant_type	client_credentials

 

EFFETTUARE UNA CHIAMATA SU TEAMS TRAMITE GRAPH API

Per effettuare una chiamata su Teams tramite Graph API sono necessari il Bearer Token per l’autenticazione, l’ID del bot che si vuole utilizzare, il relativo callbackUri e TenantId e l’ObjectId degli utenti che si vuole chiamare.

POST https://graph.microsoft.com/v1.0/communications/calls

Headers:

Key	Value
Content-Type	application/json
Authorization	Bearer $AUTH_TOKEN

Body (raw/json):

{
“direction”: “outgoing”,
“subject”: “Create a group call with application hosted media”,
“callbackUri”: “$CALLBACK_URI“,
“source”: {
“identity”: {
“application”: {
“displayName”: “CallingBot”,
“id”: “$APP_ID“,
“@odata.type”: “#microsoft.graph.identity”
},
“@odata.type”: “#microsoft.graph.identitySet”
},
“@odata.type”: “#microsoft.graph.participantInfo”
},
“targets”: [
{
“identity”: {
“user”: {
“displayName”: “Partecipante”,
“id”: “$USER_ID“,
“@odata.type”: “#microsoft.graph.identity”
},
“@odata.type”: “#microsoft.graph.identitySet”
},
“@odata.type”: “#microsoft.graph.invitationParticipantInfo”
}
],
“requestedModalities”: [
“audio”
],
“tenantId”: “$TENANT_ID“,
“mediaConfig”: {
“removeFromDefaultAudioGroup”: false,
“@odata.type”: “#microsoft.graph.serviceHostedMediaConfig”
},
“@odata.type”: “#microsoft.graph.call”
}

Se si volesse effettuare una chiamata di gruppo sarebbe necessario aggiungere degli oggetti identity (i partecipanti) all’array targets (fino a 5 partecipanti massimo).

Esempio:

“targets”: [
{
“identity”: {
“user”: {
“displayName”: “Partecipante 1”,
“id”: “$USER01_ID“,
“@odata.type”: “#microsoft.graph.identity”
},
“@odata.type”: “#microsoft.graph.identitySet”
},
“@odata.type”: “#microsoft.graph.invitationParticipantInfo”
},
{
“identity”: {
“user”: {
“displayName”: “Partecipante 2”,
“id”: “$USER02_ID“,
“@odata.type”: “#microsoft.graph.identity”
},
“@odata.type”: “#microsoft.graph.identitySet”
},
“@odata.type”: “#microsoft.graph.invitationParticipantInfo”
}
],

Poiché non è possibile leggere l’attributo Subject dalla webapp, è possible utilizzare i parametri GET del CallbackUri per modificare le opzioni della chiamata (richiede di essere programmato sulla webapp).

VERIFICARE LO STATO DELLA CHIAMATA DI TEAMS TRAMITE GRAPH API

Per verificare lo stato una chiamata su Teams tramite Graph API sono necessari il Bearer Token per l’autenticazione e l’ID della chiamata (contenuto nel body della risposta del server alla richiesta POST per la creazione della chiamata).
Lo stato può essere establishing quando la chiamata non è ancora stata risposta, oppure established quando almeno un utente ha risposto.
Se la chiamata non viene risposta o viene chiusa la risposta del server sarà un errore 404.
Se la chiamata viene inoltrata alla segreteria, verrà considerata risposta, perciò per implementare automatismi relativi alla non risposta di una chiamata, è necessario disabilitare la segreteria telefonica dell’utente che deve venir chiamato.

GET https://graph.microsoft.com/v1.0/communications/calls/$CALL_ID

Headers:

Key	Value
Authorization	Bearer $AUTH_TOKEN

Nel body della risposta del server l’attributo state contiene lo stato della chiamata.

RICHIEDERE I TURNI DI TEAMS TRAMITE GRAPH API

Per richiedere i turni di Teams (Shifts) tramite Graph API sono necessari il Bearer Token per l’autenticazione, l’ObjectId del team a cui appartiene il turno e l’ObjectId di un’utente appartenente al team, affinché egli possa essere impersonato durate la chiama API.

GET https://graph.microsoft.com/v1.0/teams/$TEAM_ID/schedule/shifts

Headers:

Key	Value
MS-APP-ACTS-AS	$USER_ID
Authorization	Bearer $AUTH_TOKEN

 

Opzionalmente è possibile utilizzare dei filtri sul periodo tramite il parametro GET “$filter”, in seguito un esempio:

GET https://graph.microsoft.com/v1.0/teams/$TEAM_ID/schedule/shifts?$filter=sharedShift/startDateTime ge 2024-12-14T17:00:00.000Z and sharedShift/endDateTime le 2024-12-15T08:00:00.000Z

Non è possibile filtrare tramite API su ShiftGroup, perciò i risultati vanno filtrati localmente.

RICHIEDERE GLI SHIFT GROUPS DI TEAMS TRAMITE GRAPH API

Per richiedere i turni di Teams (Shifts) tramite Graph API sono necessari il Bearer Token per l’autenticazione, l’ObjectId del team a cui appartiene il turno e l’ObjectId di un’utente appartenente al team, affinché egli possa essere impersonato durate la chiama API.

GET https://graph.microsoft.com/v1.0/teams/$TEAM_ID/schedule/shifts/schedulingGroups/$SCHEDULING_GROUP_ID

Headers:

Key	Value
MS-APP-ACTS-AS	$USER_ID
Authorization	Bearer $AUTH_TOKEN