Funzionamento dei bot in Microsoft Teams

SI APPLICA A: SDK v4

Questo articolo si basa su quanto appreso in Come funzionano i bot e conversazioni guidate dagli eventi. Prima di continuare, è consigliabile acquisire familiarità con questi articoli.

La differenza principale nei bot sviluppati per Microsoft Teams è nel modo in cui vengono gestite le attività. Il gestore attività di Teams deriva dal gestore attività e elabora i tipi di attività specifici di Teams prima di elaborare tipi di attività più generali.

Nota

Gli SDK JavaScript, C# e Python di Bot Framework continueranno a essere supportati, ma Java SDK verrà ritirato con il supporto finale a lungo termine che termina a novembre 2023. Verranno eseguite solo correzioni di bug e sicurezza critiche all'interno di questo repository.

I bot esistenti creati con Java SDK continueranno a funzionare.

Per la creazione di nuovi bot, prendere in considerazione l'uso di Power Virtual Agents e leggere la scelta della soluzione chatbot appropriata.

Per altre informazioni, vedere Il futuro della compilazione di bot.

Gestore attività di Teams

Per creare un bot per Teams, derivare il bot dalla classe del gestore attività di Teams. Quando un bot riceve un'attività, instrada l'attività attraverso vari gestori di attività. Il gestore di base iniziale è il gestore dei turni e indirizza l'attività a un gestore in base al tipo di attività. Il gestore dei turni chiama il gestore progettato per gestire il tipo specifico di attività ricevuto. La classe del gestore attività di Teams deriva dalla classe del gestore attività . Oltre ai tipi di attività che il gestore attività può elaborare, la classe del gestore attività di Teams include gestori aggiuntivi per le attività specifiche di Teams.

Un bot che deriva dal gestore attività di Teams è simile a un bot che deriva direttamente dalla classe del gestore attività. Tuttavia, Teams include informazioni aggiuntive nelle conversationUpdate attività e invia attività specifiche invoke di event Teams.

C#

Quando il gestore attività di Teams-bot riceve un'attività di messaggio, il gestore dei turni instrada l'attività del messaggio in arrivo al OnMessageActivityAsync gestore, in modo analogo a come farebbe un bot basato su un gestore attività. Tuttavia, quando il bot di Teams riceve un'attività di aggiornamento della conversazione, la versione di Teams del OnConversationUpdateActivityAsync gestore elabora l'attività.

Non esiste alcuna implementazione di base per la maggior parte dei gestori di attività specifici di Teams. È necessario eseguire l'override di questi gestori e fornire la logica appropriata per il bot.

JavaScript

Quando il gestore attività di Teams-bot riceve un'attività di messaggio, il gestore dei turni instrada l'attività del messaggio in arrivo al onMessage gestore, in modo analogo a come farebbe un bot basato su un gestore attività. Tuttavia, quando il bot di Teams riceve un'attività di aggiornamento della conversazione, la versione di Teams del dispatchConversationUpdateActivity gestore elabora l'attività.

Non esiste alcuna implementazione di base per la maggior parte dei gestori di attività specifici di Teams. È necessario eseguire l'override di questi gestori e fornire la logica appropriata per il bot.

Quando si esegue l'override di questi gestori di attività specifici di Teams, definire la logica del bot, quindi assicurarsi di chiamare next() alla fine. next()Chiamando , assicurarsi che venga eseguito il gestore successivo.

Java

Quando il gestore attività di Teams-bot riceve un'attività di messaggio, il gestore dei turni instrada l'attività del messaggio in arrivo al onMessageActivity gestore, in modo analogo a come farebbe un bot basato su un gestore attività. Tuttavia, quando il bot di Teams riceve un'attività di aggiornamento della conversazione, la versione di Teams del onConversationUpdateActivity gestore elabora l'attività.

Non esiste alcuna implementazione di base per la maggior parte dei gestori di attività specifici di Teams. È necessario eseguire l'override di questi gestori e fornire la logica appropriata per il bot.

Python

Quando il gestore attività di Teams-bot riceve un'attività di messaggio, il gestore dei turni instrada l'attività del messaggio in arrivo al on_message_activity gestore, in modo analogo a come farebbe un bot basato su un gestore attività. Tuttavia, quando il bot di Teams riceve un'attività di aggiornamento della conversazione, la versione di Teams del on_conversation_update_activity gestore elabora l'attività.

Non esiste alcuna implementazione di base per la maggior parte dei gestori di attività specifici di Teams. È necessario eseguire l'override di questi gestori e fornire la logica appropriata per il bot.

Tutti i gestori attività descritti nella sezione relativa alla gestione delle attività delle conversazioni guidate dagli eventi che usano un gestore attività continueranno a funzionare come fanno con un bot non Teams, ad eccezione della gestione dei membri aggiunti e rimossi, queste attività saranno diverse nel contesto di un team, in cui il nuovo membro viene aggiunto al team anziché a un thread di messaggio. Per altre informazioni, vedere Attività di aggiornamento delle conversazioni di Teams.

Per implementare la logica per questi gestori di attività specifici di Teams, è necessario eseguire l'override dei metodi nel bot.

Logica del bot di Teams

La logica del bot elabora le attività in ingresso da uno o più canali di bot e genera in risposta le attività in uscita. Questo comportamento è valido anche per il bot derivato dalla classe del gestore di attività di Teams, la quale verifica prima le attività di Teams e quindi passa tutte le altre attività al gestore di attività di Bot Framework.

Attività di aggiornamento dell'installazione di Teams

Aggiungere un gestore per l'evento di aggiornamento dell'installazione per consentire al bot:

• Inviare un messaggio introduttivo quando viene installato in un thread di conversazione.
• Pulire i dati utente e thread quando vengono disinstallati da un thread.

Per altre informazioni, vedere Evento di aggiornamento dell'installazione nella documentazione di Teams.

Attività di aggiornamento della conversazione in Teams

La tabella seguente elenca gli eventi di Teams che generano un'attività di aggiornamento della conversazione in un bot. L'articolo sugli eventi di aggiornamento della conversazione di Microsoft Teams descrive come usare ognuno di questi eventi.

C#

Di seguito è riportato un elenco di tutti i gestori attività di Teams chiamati dal OnConversationUpdateActivityAsync metodo del gestore attività di Teams .

EventType	Gestore	Condizione	Documentazione di Teams
channelCreated	OnTeamsChannelCreatedAsync	Inviato ogni volta che viene creato un nuovo canale in un team in cui viene installato il bot.	Canale creato.
channelDeleted	OnTeamsChannelDeletedAsync	Inviato ogni volta che un canale viene eliminato in un team in cui viene installato il bot.	Canale eliminato.
channelRenamed	OnTeamsChannelRenamedAsync	Inviato ogni volta che un canale viene rinominato in un team in cui viene installato il bot.	Canale rinominato.
channelRestored	OnTeamsChannelRestoredAsync	Inviato ogni volta che un canale eliminato in precedenza viene ripristinato in un team in cui è già installato il bot.	Canale ripristinato.
membersAdded	OnTeamsMembersAddedAsync	Per impostazione predefinita, chiama il ActivityHandler.OnMembersAddedAsync metodo . Inviato la prima volta che il bot viene aggiunto a una conversazione e ogni volta che un nuovo utente viene aggiunto a un team o a una chat di gruppo in cui è installato il bot.	Membri del team aggiunti.
membersRemoved	OnTeamsMembersRemovedAsync	Per impostazione predefinita, chiama il ActivityHandler.OnMembersRemovedAsync metodo . Inviato se il bot viene rimosso da un team e ogni volta che un utente viene rimosso da un team di cui il bot è membro.	Membri del team rimossi.
teamArchived	OnTeamsTeamArchivedAsync	Inviato quando il team in cui è installato il bot è archiviato.	Team archiviato.
teamDeleted	OnTeamsTeamDeletedAsync	Inviato quando il team in cui si trova il bot è stato eliminato.	Team eliminato.
teamRenamed	OnTeamsTeamRenamedAsync	Inviato quando il team in cui si trova il bot è stato rinominato.	Team rinominato.
teamRestored	OnTeamsTeamRestoredAsync	Inviato quando viene ripristinato un team eliminato in precedenza in cui si trova il bot.	Team ripristinato.
teamUnarchived	OnTeamsTeamUnarchivedAsync	Inviato quando il team in cui è installato il bot non è stato eseguito.	Team non crittografato.

JavaScript

Gli sviluppatori possono gestire le attività di aggiornamento delle conversazioni inviate da Microsoft Teams tramite due metodi:

1. Per passare un callback, usare metodi che iniziano con e terminano con Eventon(ad esempio, il onTeamsMembersAddedEvent metodo ).
2. Quando si crea una classe derivata, eseguire l'override dei metodi che iniziano con on e non terminano con Event (ad esempio, il onTeamsMembersAdded metodo ).

Gli sviluppatori devono usare solo una di queste opzioni: 1 o 2 e non entrambe per la stessa attività. Ciò significa che gli sviluppatori devono passare un callback al onTeamsMembersAddedEvent metodo o eseguire l'override del onTeamsMembersAdded metodo in una classe derivata e non eseguire entrambe le operazioni.

Metodi per la registrazione di un callback

Di seguito è riportato un elenco di tutti gli emettitori di attività di Teams chiamati dal dispatchConversationUpdateActivity metodo del gestore attività di Teams .

EventType	Metodo di registrazione	Condizione	Documentazione di Teams
channelCreated	onTeamsChannelCreatedEvent	Inviato ogni volta che viene creato un nuovo canale in un team in cui viene installato il bot.	Canale creato.
channelDeleted	onTeamsChannelDeletedEvent	Inviato ogni volta che un canale viene eliminato in un team in cui viene installato il bot.	Canale eliminato.
channelRenamed	onTeamsChannelRenamedEvent	Inviato ogni volta che un canale viene rinominato in un team in cui viene installato il bot.	Canale rinominato.
channelRestored	onTeamsChannelRestoredEvent	Inviato ogni volta che un canale eliminato in precedenza viene ripristinato in un team in cui è già installato il bot.	Canale ripristinato.
membersAdded	onTeamsMembersAddedEvent	Inviato la prima volta che il bot viene aggiunto a una conversazione e ogni volta che un nuovo utente viene aggiunto a un team o a una chat di gruppo in cui è installato il bot.	Membri del team aggiunti.
membersRemoved	onTeamsMembersRemovedEvent	Inviato se il bot viene rimosso da un team e ogni volta che un utente viene rimosso da un team di cui il bot è membro.	Membri del team rimossi.
teamArchived	onTeamsTeamArchivedEvent	Inviato quando il team in cui è installato il bot è archiviato.	Team archiviato.
teamDeleted	onTeamsTeamDeletedEvent	Inviato quando il team in cui si trova il bot è stato eliminato.	Team eliminato.
teamRenamed	onTeamsTeamRenamedEvent	Inviato quando il team in cui si trova il bot è stato rinominato.	Team rinominato.
teamRestored	onTeamsTeamrestoredEvent	Inviato quando viene ripristinato un team eliminato in precedenza in cui si trova il bot.	Team ripristinato.
teamUnarchived	onTeamsTeamUnarchivedEvent	Inviato quando il team in cui è installato il bot non è stato eseguito.	Team non crittografato.

Metodi di override in una classe derivata

Di seguito è riportato un elenco di tutti i gestori attività di Teams che possono essere sottoposti a override per gestire le attività di aggiornamento delle conversazioni di Teams.

EventType	Gestore	Condizione	Documentazione di Teams
channelCreated	onTeamsChannelCreated	Inviato ogni volta che viene creato un nuovo canale in un team in cui viene installato il bot.	Canale creato.
channelDeleted	onTeamsChannelDeleted	Inviato ogni volta che un canale viene eliminato in un team in cui viene installato il bot.	Canale eliminato.
channelRenamed	onTeamsChannelRenamed	Inviato ogni volta che un canale viene rinominato in un team in cui viene installato il bot.	Canale rinominato.
channelRestored	onTeamsChannelRestored	Inviato ogni volta che un canale eliminato in precedenza viene ripristinato in un team in cui è già installato il bot.	Canale ripristinato.
membersAdded	onTeamsMembersAdded	Per impostazione predefinita, chiama il ActivityHandler.onMembersAdded metodo . Inviato la prima volta che il bot viene aggiunto a una conversazione e ogni volta che un nuovo utente viene aggiunto a un team o a una chat di gruppo in cui è installato il bot.	Membri del team aggiunti.
membersRemoved	onTeamsMembersRemoved	Per impostazione predefinita, chiama il ActivityHandler.onMembersRemoved metodo . Inviato se il bot viene rimosso da un team e ogni volta che un utente viene rimosso da un team di cui il bot è membro.	Membri del team rimossi.
teamArchived	onTeamsTeamArchived	Inviato quando il team in cui è installato il bot è archiviato.	Team archiviato.
teamDeleted	onTeamsTeamDeleted	Inviato quando il team in cui si trova il bot è stato eliminato.	Team eliminato.
teamRenamed	onTeamsTeamRenamed	Inviato quando il team in cui si trova il bot è stato rinominato.	Team rinominato.
teamRestored	onTeamsTeamRestored	Inviato quando viene ripristinato un team eliminato in precedenza in cui si trova il bot.	Team ripristinato.
teamUnarchived	onTeamsTeamUnarchived	Inviato quando il team in cui è installato il bot non è stato eseguito.	Team non crittografato.

Java

Di seguito è riportato un elenco di tutti i gestori attività di Teams chiamati dal onConversationUpdateActivity metodo del gestore attività di Teams .

EventType	Gestore	Condizione	Documentazione di Teams
channelCreated	onTeamsChannelCreated	Inviato ogni volta che viene creato un nuovo canale in un team in cui viene installato il bot.	Canale creato.
channelDeleted	onTeamsChannelDeleted	Inviato ogni volta che un canale viene eliminato in un team in cui viene installato il bot.	Canale eliminato.
channelRenamed	onTeamsChannelRenamed	Inviato ogni volta che un canale viene rinominato in un team in cui viene installato il bot.	Canale rinominato.
channelRestored	onTeamsChannelRestored	Inviato ogni volta che un canale eliminato in precedenza viene ripristinato in un team in cui è già installato il bot.	Canale ripristinato.
membersAdded	onTeamsMembersAdded	Per impostazione predefinita, chiama il ActivityHandler.onMembersAdded metodo . Inviato la prima volta che il bot viene aggiunto a una conversazione e ogni volta che un nuovo utente viene aggiunto a un team o a una chat di gruppo in cui è installato il bot.	Membri del team aggiunti.
membersRemoved	onTeamsMembersRemoved	Per impostazione predefinita, chiama il ActivityHandler.onMembersRemoved metodo . Inviato se il bot viene rimosso da un team e ogni volta che un utente viene rimosso da un team di cui il bot è membro.	Membri del team rimossi.
teamArchived	onTeamsTeamArchived	Inviato quando il team in cui è installato il bot è archiviato.	Team archiviato.
teamDeleted	onTeamsTeamDeleted	Inviato quando il team in cui si trova il bot è stato eliminato.	Team eliminato.
teamRenamed	onTeamsTeamRenamed	Inviato quando il team in cui si trova il bot è stato rinominato.	Team rinominato.
teamRestored	onTeamsTeamRestored	Inviato quando viene ripristinato un team eliminato in precedenza in cui si trova il bot.	Team ripristinato.
teamUnarchived	onTeamsTeamUnarchived	Inviato quando il team in cui è installato il bot non è stato eseguito.	Team non crittografato.

Python

Di seguito è riportato un elenco di tutti i gestori attività di Teams chiamati dal on_conversation_update_activity metodo del gestore attività di Teams .

EventType	Gestore	Condizione	Documentazione di Teams
channelCreated	on_teams_channel_created	Inviato ogni volta che viene creato un nuovo canale in un team in cui viene installato il bot.	Canale creato.
channelDeleted	on_teams_channel_deleted	Inviato ogni volta che un canale viene eliminato in un team in cui viene installato il bot.	Canale eliminato.
channelRenamed	on_teams_channel_renamed	Inviato ogni volta che un canale viene rinominato in un team in cui viene installato il bot.	Canale rinominato.
channelRestored	on_teams_channel_restored	Inviato ogni volta che un canale eliminato in precedenza viene ripristinato in un team in cui è già installato il bot.	Canale ripristinato.
membersAdded	on_teams_members_added	Per impostazione predefinita, chiama il metodo della classe on_members_added_activity base. Inviato la prima volta che il bot viene aggiunto a una conversazione e ogni volta che un nuovo utente viene aggiunto a un team o a una chat di gruppo in cui è installato il bot.	Membri del team aggiunti.
membersRemoved	on_teams_members_removed	Per impostazione predefinita, chiama il metodo della classe on_members_removed_activity base. Inviato se il bot viene rimosso da un team e ogni volta che un utente viene rimosso da un team di cui il bot è membro.	Membri del team rimossi.
teamArchived	on_teams_team_archived	Inviato quando il team in cui è installato il bot è archiviato.	Team archiviato.
teamDeleted	on_teams_team_deleted	Inviato quando il team in cui si trova il bot è stato eliminato.	Team eliminato.
teamRenamed	on_teams_team_renamed	Inviato quando il team in cui si trova il bot è stato rinominato.	Team rinominato.
teamRestored	on_teams_team_restored	Inviato quando viene ripristinato un team eliminato in precedenza in cui si trova il bot.	Team ripristinato.
teamUnarchived	on_teams_team_unarchived	Inviato quando il team in cui è installato il bot non è stato eseguito.	Team non crittografato.

Attività degli eventi di Teams

La tabella seguente elenca le attività di evento specifiche di Teams inviate da Teams a un bot. Le attività degli eventi elencate sono per i bot di conversazione in Teams.

C#

Si tratta dei gestori di attività dell'evento specifici di Teams chiamati dal OnEventActivityAsyncgestore attività di Teams .

Tipi di evento	Gestore	Descrizione
application/vnd.microsoft.meetingEnd	OnTeamsMeetingEndAsync	Il bot è associato a una riunione appena terminata.
application/vnd.microsoft.meetingStart	OnTeamsMeetingStartAsync	Il bot è associato a una riunione appena avviata.

JavaScript

Si tratta dei gestori di attività dell'evento specifici di Teams chiamati dal onEventActivitygestore attività di Teams .

Tipi di evento	Gestore	Descrizione
application/vnd.microsoft.meetingEnd	onTeamsMeetingEnd	Il bot è associato a una riunione appena terminata.
application/vnd.microsoft.meetingStart	onTeamsMeetingStart	Il bot è associato a una riunione appena avviata.

Java

Si tratta dei gestori di attività dell'evento specifici di Teams chiamati dal onEventActivitygestore attività di Teams .

Tipi di evento	Gestore	Descrizione
application/vnd.microsoft.meetingEnd	onTeamsMeetingEnd	Il bot è associato a una riunione appena terminata.
application/vnd.microsoft.meetingStart	onTeamsMeetingStart	Il bot è associato a una riunione appena avviata.

Python

Si tratta dei gestori di attività dell'evento specifici di Teams chiamati dal on_event_activitygestore attività di Teams .

Tipi di evento	Gestore	Descrizione
application/vnd.microsoft.meetingEnd	on_teams_meeting_end_event	Il bot è associato a una riunione appena terminata.
application/vnd.microsoft.meetingStart	on_teams_meeting_start_event	Il bot è associato a una riunione appena avviata.

Attività di richiamo di Teams

La tabella seguente elenca le attività invoke specifiche di Teams inviate da Teams a un bot. Le attività invoke elencate sono per i bot di conversazione in Teams. Bot Framework SDK supporta anche attività di richiamo specifiche per le estensioni di messaggistica. Per altre informazioni, vedere l'articolo Informazioni sulle estensioni per la messaggistica.

Nota

La documentazione della piattaforma Microsoft Teams e la libreria client JavaScript di Teams (TeamsJS) fanno riferimento ai moduli attività come dialoghi modali. Per altre informazioni, vedere Finestre di dialogo.

C#

Ecco un elenco di tutti i gestori attività di Teams chiamati dal OnInvokeActivityAsyncgestore attività di Teams :

Tipi di richiamo	Gestore	Descrizione
actionableMessage/executeAction	OnTeamsO365ConnectorCardActionAsync	Azione scheda del connettore O365 di Teams.
CardAction.Invoke	OnTeamsCardActionInvokeAsync	Richiamo per azione scheda di Teams.
fileConsent/invoke	OnTeamsFileConsentAcceptAsync	Accettazione del consenso file di Teams.
fileConsent/invoke	OnTeamsFileConsentAsync	Consenso file di Teams.
fileConsent/invoke	OnTeamsFileConsentDeclineAsync	Consenso file di Teams.
signin/verifyState	OnTeamsSigninVerifyStateAsync	Verifica dello stato di accesso di Teams.
task/fetch	OnTeamsTaskModuleFetchAsync	Recupero del modulo attività di Teams.
task/submit	OnTeamsTaskModuleSubmitAsync	Invio del modulo attività di Teams.

JavaScript

Ecco un elenco di tutti i gestori attività di Teams chiamati dal onInvokeActivitygestore attività di Teams :

Tipi di richiamo	Gestore	Descrizione
actionableMessage/executeAction	handleTeamsO365ConnectorCardAction	Azione scheda del connettore O365 di Teams.
CardAction.Invoke	handleTeamsCardActionInvoke	Richiamo per azione scheda di Teams.
fileConsent/invoke	handleTeamsFileConsentAccept	Accettazione del consenso file di Teams.
fileConsent/invoke	handleTeamsFileConsent	Consenso file di Teams.
fileConsent/invoke	handleTeamsFileConsentDecline	Consenso file di Teams.
signin/verifyState	handleTeamsSigninVerifyState	Verifica dello stato di accesso di Teams.
task/fetch	handleTeamsTaskModuleFetch	Recupero del modulo attività di Teams (finestra di dialogo modale).
task/submit	handleTeamsTaskModuleSubmit	Invio del modulo attività di Teams (finestra di dialogo modale).

Java

Ecco un elenco di tutti i gestori attività di Teams chiamati dal onInvokeActivitygestore attività di Teams :

Tipi di richiamo	Gestore	Descrizione
fileConsent/invoke	onTeamsFileConsent	Consenso file di Teams.
actionableMessage/executeAction	onTeamsO365ConnectorCardAction	Azione scheda del connettore O365 di Teams.
task/fetch	onTeamsTaskModuleFetch	Recupero del modulo attività di Teams.
task/submit	onTeamsTaskModuleSubmit	Invio del modulo attività di Teams.
tabulazioni/recupero	onTeamsTabFetch	Recupero scheda Teams.
scheda/invio	onTeamsTabSubmit	Scheda Teams Invia.
CardAction.Invoke	onTeamsCardActionInvoke	Richiamo per azione scheda di Teams.
fileConsent/invoke	onTeamsFileConsentAccept	Accettazione del consenso file di Teams.
fileConsent/invoke	onTeamsFileConsentDecline	Consenso file di Teams.
signin/verifyState	onTeamsSigninVerifyState	Verifica dello stato di accesso di Teams.

Python

Ecco un elenco di tutti i gestori attività di Teams chiamati dal on_invoke_activitygestore attività di Teams :

Tipi di richiamo	Gestore	Descrizione
actionableMessage/executeAction	on_teams_o365_connector_card_action	Azione scheda del connettore O365 di Teams.
CardAction.Invoke	on_teams_card_action_invoke	Richiamo per azione scheda di Teams.
fileConsent/invoke	on_teams_file_consent_accept	Accettazione del consenso file di Teams.
fileConsent/invoke	on_teams_file_consent	Consenso file di Teams.
fileConsent/invoke	on_teams_file_consent_decline	Rifiuto del consenso file di Teams.
signin/verifyState	on_teams_signin_verify_state	Verifica dello stato di accesso di Teams.
task/fetch	on_teams_task_module_fetch	Recupero del modulo attività di Teams.
task/submit	on_teams_task_module_submit	Invio del modulo attività di Teams.

Passaggi successivi

Per la creazione di bot per Teams, fare riferimento alla documentazione per gli sviluppatori di Microsoft Teams.