Registrare il bot Teams su Microsoft Azure
Questa pagina descrive la procedura, presso Microsoft Azure, necessaria per predisporre il bot che collega Microsoft Teams ad Askme Chat. Il percorso si svolge sul portale Azure (portal.azure.com) e sul client Teams dell'organizzazione, e va completato prima di configurare il canale in Askme Chat. Al termine, i dati raccolti vengono comunicati al team Askme, che collega il bot all'integratore Teams.
Il team Askme può affiancare il cliente nell'intero processo di registrazione su Azure, dalla creazione dell'applicazione fino alla pubblicazione dell'app in Teams. Per richiedere supporto è sufficiente scrivere a [email protected].
A chi si rivolge e cosa serve prima di iniziare
La procedura si rivolge a chi amministra il tenant Microsoft dell'organizzazione: tipicamente un referente IT con accesso ad Azure e al centro di amministrazione di Teams. Non sono richieste competenze di sviluppo: la configurazione tecnica verso Askme Chat resta a carico del team Askme.
Prima di iniziare è opportuno disporre di:
- un account con permesso di creare registrazioni applicazione in Microsoft Entra ID;
- una sottoscrizione Azure attiva su cui creare la risorsa bot, con ruolo Contributor su un gruppo di risorse;
- i permessi per caricare app personalizzate in Teams (centro di amministrazione Teams o permesso di caricamento diretto);
- l'indirizzo del messaging endpoint comunicato dal team Askme, cioè l'indirizzo pubblico dell'integratore a cui il Bot Framework consegna i messaggi.
Nel corso della procedura ricorrono tre oggetti distinti: la registrazione applicazione (app registration, l'identità del bot in Entra ID, con il suo application ID e il client secret), la risorsa Azure Bot (la registrazione presso il Bot Service, che dichiara il messaging endpoint e i canali abilitati) e il pacchetto app Teams (il file zip con manifest e icone che rende il bot visibile agli utenti in Teams). Tutti e tre fanno riferimento allo stesso application ID.
Passo 1 — Registrazione applicazione in Entra ID
- Dal portale Azure aprire Microsoft Entra ID › Registrazioni app e creare una nuova registrazione.
- Assegnare un nome riconoscibile (ad esempio il nome del servizio di assistenza) e selezionare come tipo di account supportato solo l'organizzazione corrente (single-tenant).
- Al termine, annotare dalla pagina di panoramica l'ID applicazione (client) e l'ID della directory (tenant).
- In Certificati e segreti, creare un nuovo client secret indicando una scadenza (ad esempio 24 mesi) e copiarne subito il valore: non sarà più visualizzabile in seguito.
Alla scadenza del client secret il canale smette di funzionare in entrambe le direzioni. Registrare la data di scadenza e pianificarne il rinnovo, comunicando il nuovo valore al team Askme prima della scadenza.
Passo 2 — Risorsa Azure Bot
- Dal portale Azure creare una risorsa di tipo Azure Bot nel gruppo di risorse scelto.
- Come tipo di applicazione selezionare Single Tenant, quindi scegliere usare una registrazione app esistente e indicare l'ID applicazione del Passo 1 con il relativo tenant. La creazione di bot multi-tenant non è più consentita da Azure.
- Il piano tariffario gratuito (F0) è sufficiente: il canale Teams non prevede costi per messaggio.
- Dopo la creazione, in Impostazioni › Configurazione impostare il Messaging endpoint con l'indirizzo comunicato dal team Askme.
- Facoltativamente, impostare il display name della risorsa con il nome che si desidera far comparire nelle conversazioni: è il nome mostrato quando il bot viene contattato direttamente, al di fuori dell'app Teams.
Passo 3 — Abilitare il canale Microsoft Teams
- Nella risorsa bot aprire Canali (Channels).
- Aggiungere Microsoft Teams, accettare le condizioni d'uso e selezionare l'ambiente Microsoft Teams Commercial.
- Confermare: lo stato del canale deve risultare attivo.
Il canale Web Chat, presente per impostazione predefinita, è utile in seguito per le verifiche: il collegamento Test in Web Chat della risorsa invia messaggi allo stesso messaging endpoint del canale Teams.
Se il canale Teams viene rimosso e riaggiunto, le conversazioni esistenti smettono di funzionare in modo permanente: gli identificativi di conversazione emessi prima della rimozione non sono più validi e i messaggi delle vecchie chat non vengono più consegnati, senza errori visibili all'utente. Dopo una ricreazione del canale è necessario aprire nuove conversazioni.
Passo 4 — Pacchetto app Teams
Il pacchetto app è un file zip contenente il manifest e due icone, e determina nome, descrizione e icona con cui il bot compare in Teams. Il pacchetto viene preparato dal team Askme a partire dall'ID applicazione del Passo 1 e consegnato pronto per il caricamento; in alternativa può essere predisposto dal cliente con lo strumento Developer Portal di Teams.
Per il caricamento nell'organizzazione:
- Dal centro di amministrazione di Teams (Teams apps › Manage apps › Upload new app) caricare il pacchetto zip: l'app diventa disponibile nel catalogo aziendale, con la possibilità di governarne la visibilità tramite le policy di autorizzazione.
- In alternativa, per le prove, un utente abilitato può caricare il pacchetto direttamente dal client Teams (App › Gestisci le tue app › Carica un'app).
Gli utenti trovano quindi l'app per nome nel catalogo, la installano e avviano la conversazione con il bot.
Passo 5 — Collegamento con Askme Chat
Completati i passi precedenti, il bot è pronto per essere collegato. Il collegamento tecnico all'integratore è eseguito dal team Askme: al cliente è richiesto di comunicare i dati necessari.
- Raccogliere i tre valori: ID applicazione (client), ID della directory (tenant) e client secret.
- Trasmetterli al team Askme attraverso il canale sicuro concordato, insieme alla conferma che canale Teams e app risultano attivi.
- Il team Askme registra il bot sull'integratore e conferma quando il canale è operativo.
- Procedere quindi alla configurazione lato modulo descritta in Canale Microsoft Teams: integrazione del tenant o collegamento del chatbot, messaggi di benvenuto e chiusura, categorie.
Il client secret va condiviso solo attraverso il canale concordato con il team Askme e non inserito in documenti, email non protette o repository. La gestione tecnica dei segreti sull'integratore è a carico del team Askme.
Requisiti di rete del messaging endpoint
Questa sezione riguarda le installazioni in cui l'integratore è esposto su infrastruttura del cliente; per il servizio gestito da Askme i requisiti sono già soddisfatti.
- Il messaging endpoint deve essere pubblicamente raggiungibile in HTTPS con un certificato valido per il nome usato: il Bot Framework non consegna a endpoint con certificato non corrispondente.
- Le consegne arrivano dagli indirizzi dei datacenter Microsoft con user agent
Microsoft-SkypeBotApi. Eventuali protezioni anti-bot sul perimetro (ad esempio le challenge dei servizi CDN/WAF) intercettano queste richieste come traffico automatizzato e le scartano senza alcun errore visibile: l'utente vede il messaggio inviato, ma il bot non lo riceve mai. Il percorso del messaging endpoint va esentato da tali protezioni, o la protezione disattivata per il nome usato dall'endpoint. - I messaggi respinti vengono ritentati dal Bot Framework solo per alcuni minuti: superata la finestra di retry, i messaggi persi durante un blocco non vengono recuperati.
Verifica dell'attivazione
- Dalla risorsa bot, usare Test in Web Chat e inviare un messaggio: verifica che il messaging endpoint sia raggiungibile e risponda. In questa modalità il messaggio viene rifiutato dall'integratore perché privo del tenant Teams: è il comportamento atteso, e conferma comunque la catena di consegna.
- Da Teams, aprire l'app installata e inviare un messaggio: deve arrivare la risposta configurata in Askme Chat (messaggio di benvenuto o flusso del chatbot).
- In caso di anomalie, la pagina Canali › Microsoft Teams › Health della risorsa bot riporta gli errori di consegna registrati dal Bot Service.
Problemi comuni
| Problema | Causa probabile | Come procedere |
|---|---|---|
| Test in Web Chat funziona ma i messaggi da Teams non arrivano, senza errori | Protezione anti-bot sul perimetro che scarta le richieste dei datacenter Microsoft, oppure canale Teams non attivo sulla risorsa | Verificare lo stato del canale nella risorsa bot; far esentare il messaging endpoint dalle protezioni anti-bot del perimetro |
| I messaggi di una conversazione esistente non arrivano più | Canale Teams rimosso e ricreato: gli identificativi di conversazione precedenti non sono più validi | Aprire una nuova conversazione con il bot |
| Il bot non risponde e il Health del canale riporta errori di autenticazione | ID applicazione, tenant o client secret comunicati non coincidono con la registrazione, oppure segreto scaduto | Verificare i tre valori e la scadenza del segreto; comunicare al team Askme gli eventuali valori aggiornati |
| Nelle conversazioni compare un nome diverso da quello dell'app | Conversazione aperta contattando il bot direttamente: viene mostrato il display name della risorsa bot | Impostare il display name della risorsa, oppure avviare la conversazione dall'app Teams installata |
| Il caricamento del pacchetto app viene rifiutato | Policy dell'organizzazione che non consente app personalizzate | Abilitare le app personalizzate nel centro di amministrazione di Teams o far caricare l'app da un amministratore |
Assistenza
Per qualsiasi difficoltà nella procedura su Azure, o per delegarla in tutto o in parte, è possibile rivolgersi al team Askme scrivendo a [email protected].
La documentazione ufficiale Microsoft resta il riferimento aggiornato per i dettagli operativi: