CONFIGURAZIONE TOOL MICROSOFT TEAMS

Configurazione per l'invio di notifiche automatiche ai canali Microsoft Teams

PANORAMICA DEL TOOL

Funzionalità Principali
Il tool Microsoft Teams permette ad AI4CALL di inviare notifiche automatiche ai canali Teams della tua organizzazione, mantenendo il team sempre aggiornato sui eventi telefonici importanti.
Vantaggi dell'integrazione:
• Notifiche in tempo reale: Aggiornamenti immediati ai canali Teams
• Integrazione nativa: Messaggi direttamente nell'ambiente di lavoro
• Due modalità: Webhook semplice o Graph API avanzata
• Formattazione ricca: Supporto per card e formattazione avanzata
• Tracciamento eventi: Monitoraggio delle notifiche inviate
Due Metodi di Configurazione
Il tool supporta due diversi metodi di configurazione, ognuno con i propri vantaggi:

Metodo Webhook

Il modo più semplice per inviare messaggi a Teams. Configurazione rapida direttamente nel canale Teams.

  • Setup in 5 minuti
  • Nessuna app Azure richiesta
  • Ideale per uso base
  • Un webhook per canale

Metodo Graph API

Soluzione avanzata che richiede registrazione app Azure. Maggiore controllo e funzionalità estese.

  • Controllo avanzato
  • Gestione centralizzata
  • Autenticazione OAuth 2.0
  • Accesso a più canali

DATI RICHIESTI PER LA CONFIGURAZIONE

Nome Canale *
Nome descrittivo per identificare il canale Teams di destinazione nell'interfaccia AI4CALL.
Formato: Testo libero (esempio: "Notifiche Vendite", "Alert IT")
Funzione: Solo per identificazione interna nel sistema
Consiglio: Usa nomi chiari che identifichino il team/reparto
ID Canale *
Identificativo unico del canale Teams dove verranno inviate le notifiche. Questo ID è necessario sia per il metodo Webhook che per Graph API.
Formato: 19:xxxxxxxxxxxxxxxx@thread.tacv2 o similar
Dove trovarlo: Menu canale > "Ottieni collegamento al canale"
Esempio: 19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2
Webhook URL Canale (opzionale)
URL del webhook configurato nel canale Teams. Richiesto solo se si utilizza il metodo Webhook.
Solo per Metodo Webhook:
Formato: https://outlook.office.com/webhook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Come ottenerlo: Connettori > Incoming Webhook > Configura
Sicurezza: Mantieni questo URL riservato
Team ID (opzionale)
Identificativo del team Microsoft Teams. Necessario solo se si utilizza il metodo Graph API per accesso avanzato e gestione centralizzata.
Solo per Metodo Graph API:
Formato: GUID (esempio: fbe2bf47-16c8-47cf-b4a5-4b9b187c508b)
Dove trovarlo: Menu team > "Ottieni collegamento al team" > groupId
Nota: Corrisponde al Group ID del team in Azure AD

CONFIGURAZIONE METODO WEBHOOK

Quando usare il Metodo Webhook
Il metodo Webhook è la soluzione più semplice e veloce per inviare notifiche a Teams.
Ideale per:
• Configurazioni rapide e semplici
• Invio a un singolo canale specifico
• Organizzazioni senza complesse policy Azure
• Test e prototipi
• Setup che non richiedono autenticazione avanzata
Procedura di Configurazione Webhook
Segui questi semplici passaggi per configurare un Incoming Webhook:
Accedi al Canale Teams
Apri Microsoft Teams e naviga nel canale dove vuoi ricevere le notifiche. Assicurati di avere i permessi di gestione del canale.
Accedi alle Opzioni Canale
Clicca sui tre puntini (•••) a destra del nome del canale per aprire il menu delle opzioni. Se usi Teams nuovo, seleziona "Gestisci canale".
Trova i Connettori
Nel menu, cerca e seleziona "Connettori" (Teams classico) oppure "Modifica" > cerca "Incoming Webhook" (Teams nuovo).
Configura Incoming Webhook
Cerca "Incoming Webhook" nella lista e clicca "Aggiungi" o "Configura". Se già configurato, vedrai l'opzione "Configura".
Personalizza il Webhook
Fornisci un nome per il webhook (es. "AI4CALL Notifiche") e opzionalmente carica un'immagine personalizzata per identificare i messaggi.
Copia l'URL del Webhook
Dopo aver cliccato "Crea", copia l'URL unico del webhook che appare nel dialog. Questo URL è l'elemento chiave da inserire nella configurazione AI4CALL.
Salva e Testa
Clicca "Fine" per completare la configurazione. Ora puoi usare l'URL copiato nel campo "Webhook URL Canale" del tool AI4CALL.
Esempio di URL Webhook
L'URL del webhook avrà un formato simile a questo:
https://outlook.office.com/webhook/a1269812-6d10-44b1-abc5-b84f93580dee@9e7b80c7-d1eb-4b52-8582-76f921e416d9/IncomingWebhook/3fdd6767ace44bc6885fc76be1a0d8c0/

CONFIGURAZIONE METODO GRAPH API

Quando usare il Metodo Graph API
Il metodo Graph API offre maggiore controllo e funzionalità avanzate, ma richiede una configurazione più complessa.
Ideale per:
• Gestione centralizzata di più canali
• Integrazione con sistemi aziendali esistenti
• Controllo avanzato delle autorizzazioni
• Organizzazioni con policy Azure strutturate
• Necessità di funzionalità avanzate Microsoft Graph
Prerequisiti per Graph API
Prima di iniziare la configurazione Graph API, verifica di avere:
Requisiti necessari:
• Sottoscrizione Microsoft 365 attiva
• Permessi di amministratore Azure AD
• Accesso al portale Azure (portal.azure.com)
• Team e canali Teams già creati
• Comprensione base di OAuth 2.0 e Azure AD
Procedura Registrazione App Azure
Per utilizzare Graph API è necessario registrare un'applicazione in Azure AD:
Accedi al Portale Azure
Vai su portal.azure.com e accedi con le credenziali amministratore dell'organizzazione.
Naviga in Azure Active Directory
Nel dashboard di Azure, seleziona "Azure Active Directory" dal menu principale o cercalo nella barra di ricerca.
Registra Nuova Applicazione
Vai in "Registrazioni app" > "Nuova registrazione". Inserisci nome (es. "AI4CALL Teams Integration") e seleziona "Account solo in questa directory".
Configura Permessi API
Nella app creata, vai in "Permessi API" > "Aggiungi autorizzazione" > "Microsoft Graph". Aggiungi i permessi necessari (vedi sezione permessi sotto).
Crea Client Secret
Vai in "Certificati e segreti" > "Nuovo segreto client". Scegli scadenza appropriata e copia il valore del segreto (visibile solo una volta).
Concedi Consenso Amministratore
Torna in "Permessi API" e clicca "Concedi consenso amministratore per [organizzazione]" per autorizzare l'app ad utilizzare i permessi richiesti.
Raccogli Informazioni App
Dalla pagina "Panoramica" dell'app, copia Application (client) ID e Directory (tenant) ID. Questi saranno necessari per la configurazione AI4CALL.
Permessi Microsoft Graph Necessari
Per inviare messaggi ai canali Teams tramite Graph API sono necessari questi permessi:
Permessi Application richiesti:
• ChannelMessage.Send: Invio messaggi ai canali
• TeamsActivity.Send: Invio notifiche Teams
• Channel.ReadBasic.All: Lettura informazioni base canali
• Team.ReadBasic.All: Lettura informazioni base team

Permessi opzionali aggiuntivi:
• ChannelMessage.ReadWrite.All: Controllo completo messaggi
• Group.Read.All: Lettura gruppi Microsoft 365

COME TROVARE TEAM ID E CHANNEL ID

Panoramica degli Identificativi
Teams utilizza identificativi unici per team e canali. Ecco come trovarli facilmente:
Tipi di ID necessari:
• Team ID (Group ID): Identifica il team Microsoft Teams
• Channel ID: Identifica lo specifico canale all'interno del team
• Tenant ID: Identifica l'organizzazione Azure AD (opzionale)
Trovare il Team ID
Procedura per ottenere l'identificativo del team:
Accedi a Microsoft Teams
Apri Teams (web o app desktop) e naviga nella sezione "Team" nel menu laterale sinistro.
Seleziona il Team
Trova il team di interesse e clicca sui tre puntini (•••) a destra del nome del team.
Ottieni Collegamento al Team
Nel menu a tendina, seleziona "Ottieni collegamento al team" e clicca "Copia" nel dialog che appare.
Estrai il Group ID
Incolla il link in un editor di testo. L'URL conterrà "groupId=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" - questo è il Team ID.
Esempio di URL team:
https://teams.microsoft.com/l/team/19:abc...@thread.skype/conversations?
groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b&
tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47
Trovare il Channel ID
Procedura per ottenere l'identificativo del canale:
Accedi al Canale Specifico
Nel team di interesse, naviga nel canale specifico dove vuoi inviare le notifiche.
Menu Opzioni Canale
Clicca sui tre puntini (•••) a destra del nome del canale per aprire il menu delle opzioni.
Ottieni Collegamento al Canale
Seleziona "Ottieni collegamento al canale" e copia l'URL generato nel dialog.
Estrai il Channel ID
Nel link copiato, il Channel ID si trova dopo "/channel/" e prima del prossimo "/" o parametro.
Esempio di URL canale:
https://teams.microsoft.com/l/channel/
19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2/
General?groupId=fbe2bf47-16c8-47cf-b4a5-4b9b187c508b
Note Importanti sugli ID
Considerazioni importanti quando lavori con gli identificativi Teams:
Attenzione:
• Il Channel ID del team link si riferisce sempre al canale "Generale"
• Per canali diversi da "Generale", usa sempre il link specifico del canale
• I canali privati potrebbero non mostrare l'opzione "Ottieni collegamento"
• Gli ID sono case-sensitive e devono essere copiati esattamente
• Il Group ID nel team link è lo stesso Team ID necessario per Graph API

RISOLUZIONE PROBLEMI COMUNI

Errori di Webhook
Problemi comuni con il metodo Webhook e le loro soluzioni:
Possibili problemi:
• URL webhook non valido: Verifica di aver copiato l'URL completo
• Webhook scaduto: I webhook possono scadere, ricreane uno nuovo
• Formato messaggio errato: Verifica che il JSON sia ben formato
• Dimensione messaggio: Limite massimo di 28KB per messaggio
• Rate limiting: Massimo 4 richieste al secondo per webhook
Errori di Graph API
Problemi comuni con il metodo Graph API:
Soluzioni per errori comuni:
• Permessi insufficienti: Verifica che tutti i permessi siano stati concessi
• App non autorizzata: Controlla che il consenso amministratore sia stato dato
• Token scaduto: Implementa refresh automatico del token OAuth
• Team/Channel non trovato: Verifica che gli ID siano corretti e accessibili
• Licenze mancanti: Assicurati che l'organizzazione abbia licenze M365
Problemi di Autorizzazioni
Errori legati ai permessi e all'accesso:
Controlli da effettuare:
• Verificare che l'utente abbia accesso al canale Teams di destinazione
• Controllare che l'app Azure abbia tutti i permessi Graph necessari
• Assicurarsi che il consenso amministratore sia stato fornito
• Verificare che il tenant abbia una sottoscrizione Teams valida
• Controllare eventuali policy aziendali che bloccano app esterne

LIMITAZIONI E BEST PRACTICES

Limitazioni Tecniche
Limitazioni da considerare nell'implementazione:
Limiti di Microsoft Teams:
• Dimensione messaggio: Massimo 28KB per messaggio
• Rate limiting webhook: Massimo 4 richieste/secondo
• Rate limiting Graph API: Varia per endpoint, generalmente 10.000 richieste/10 min
• Lunghezza URL webhook: Nessun limite specifico documentato
• Scadenza webhook: I webhook possono essere disabilitati dagli utenti
Best Practices
Raccomandazioni per un'implementazione ottimale:
Raccomandazioni:
• Gestione errori: Implementa retry automatico con backoff esponenziale
• Monitoraggio: Tieni traccia del successo/fallimento delle notifiche
• Sicurezza webhook: Non condividere URL webhook pubblicamente
• Formattazione: Usa Adaptive Cards per messaggi più ricchi
• Test: Testa sempre in un canale di sviluppo prima della produzione
• Documentazione: Mantieni documentazione degli webhook configurati
Scelta del Metodo
Guida alla scelta tra Webhook e Graph API:
Scegli Webhook se:
• Hai bisogno di una configurazione rapida
• Invii notifiche a un singolo canale
• Non hai accesso amministrativo ad Azure AD
• L'organizzazione ha policy restrittive sulle app Azure

Scegli Graph API se:
• Gestisci più canali/team
• Hai bisogno di controllo avanzato
• L'integrazione fa parte di un sistema più ampio
• Vuoi funzionalità future come lettura messaggi o gestione team

RISORSE E DOCUMENTAZIONE UFFICIALE

Link Utili Microsoft
Documentazione e risorse ufficiali per approfondimenti:
Documentazione Teams:
• Incoming Webhooks - Microsoft Learn
• Microsoft Graph Teams API Overview
• Send message to channel - Graph API
• Portale Azure - App Registrations
• Microsoft Graph Permissions Reference
Strumenti di Sviluppo
Tool utili per test e sviluppo:
Strumenti consigliati:
• Microsoft Graph Explorer - Test API Graph online
• Adaptive Cards Designer - Creazione card personalizzate
• Microsoft Teams Web - Accesso Teams via browser
• Teams Connectors Reference - Documentazione connettori
Supporto Tecnico
Canali di supporto per assistenza tecnica:
Canali di supporto:
• Supporto AI4CALL: Assistenza diretta per l'integrazione
• Microsoft Support: Per problemi di Teams e Azure AD
• Microsoft Graph Community: Forum della community sviluppatori
• Stack Overflow: Tag "microsoft-teams" e "microsoft-graph"
• Microsoft Tech Community: Forum ufficiale Microsoft Teams
Supporto Tecnico Dedicato

Il team BEEVOIP è sempre disponibile per assistenza nella configurazione del tuo assistente AI.
Ogni configurazione predefinita è stata ottimizzata per garantire le migliori performance.

Configurazione Sicura Setup Rapido Personalizzabile