Guida introduttiva: Aggiungere un bot all'app di chat

  • Articolo

Informazioni su come creare esperienze di intelligenza artificiale conversazionale in un'applicazione di chat usando il canale di messaggistica chat Servizi di comunicazione di Azure disponibile in Azure servizio Bot. In questa guida introduttiva si crea un bot usando BotFramework SDK. Si integra quindi il bot in un'applicazione di chat creata usando Communication Services Chat SDK.

In questa guida introduttiva si apprende come:

Prerequisiti

  • Un account Azure e una sottoscrizione attiva. Creare un account gratuitamente.
  • Visual Studio 2019 o versione successiva.
  • Versione più recente di .NET Core. In questa guida introduttiva si usa .NET Core 3.1. Assicurarsi di installare la versione corrispondente all'istanza di Visual Studio, a 32 bit o a 64 bit.
  • Bot Framework SDK

Creare e distribuire un bot in Azure

Per usare Servizi di comunicazione di Azure chat come canale in Azure servizio Bot, distribuire prima un bot. Per distribuire un bot, seguire questa procedura:

  • Creare una risorsa di Azure servizio Bot
  • Ottenere l'ID e la password dell'app del bot
  • Creare un'app Web per contenere la logica del bot
  • Creare un endpoint di messaggistica per il bot

Creare una risorsa di Azure servizio Bot

Usare prima di tutto il portale di Azure per creare una risorsa di Azure servizio Bot. Il canale chat di Servizi di comunicazione supporta bot a tenant singolo, bot di identità gestiti e bot multi-tenant. Ai fini di questa guida introduttiva si userà un bot multi-tenant .

Per configurare un bot di identità a tenant singolo o gestito, vedere Informazioni sull'identità del bot.

Per un bot di identità gestita, potrebbe essere necessario aggiornare l'identità del servizio bot.

Ottenere l'ID app e la password dell'app del bot

Ottenere quindi l'ID e la password dell'app Microsoft assegnati al bot al momento della distribuzione. Questi valori vengono usati per le configurazioni successive.

Creare un'app Web per contenere la logica del bot

Per creare un'app Web per il bot, è possibile rivedere gli esempi di Bot Builder per lo scenario o usare Bot Builder SDK per creare un'app Web. Uno degli esempi più semplici è Echo Bot.

Azure servizio Bot in genere prevede che bot Application Web App Controller esponga un endpoint nel formato /api/messages. L'endpoint gestisce tutti i messaggi inviati al bot.

Per creare l'app bot, usare l'interfaccia della riga di comando di Azure per creare una risorsa del servizio app Azure o creare l'app nel portale di Azure.

Per creare un'app Web bot usando il portale di Azure:

  1. Nel portale selezionare Crea una risorsa. Nella casella di ricerca immettere l'app Web. Selezionare il riquadro App Web.

    Screenshot that shows creating a web app resource in the Azure portal.

  2. In Crea app Web selezionare o immettere i dettagli per l'app, inclusa l'area in cui si vuole distribuire l'app.

    Screenshot that shows details to set to create a web app deployment.

  3. Selezionare Rivedi e crea per convalidare la distribuzione ed esaminare i dettagli della distribuzione. Selezionare Crea.

  4. Quando viene creata la risorsa dell'app Web, copiare l'URL del nome host visualizzato nei dettagli della risorsa. L'URL fa parte dell'endpoint creato per l'app Web.

    Screenshot that shows how to copy the web app endpoint URL.

Creare un endpoint di messaggistica per il bot

Successivamente, nella risorsa bot creare un endpoint di messaggistica dell'app Web:

  1. Nella portale di Azure passare alla risorsa azure Bot. Nel menu della risorsa selezionare Configurazione.

  2. In Configurazione, per endpoint di messaggistica, incollare l'URL del nome host dell'app Web copiata nella sezione precedente. Aggiungere l'URL con /api/messages.

  3. Seleziona Salva.

Screenshot that shows how to create a bot messaging endpoint by using the web app hostname.

Distribuire l'app Web

Il passaggio finale per creare un bot consiste nel distribuire l'app Web. Per questa guida introduttiva, usare l'esempio Echo Bot. La funzionalità Echo Bot è limitata all'eco dell'input dell'utente. Ecco come distribuirlo nell'app Web in Azure:

  1. Usare Git per clonare questo repository GitHub:

    git clone https://github.com/Microsoft/BotBuilder-Samples.git
cd BotBuilder-Samples

  2. In Visual Studio aprire il progetto Echo Bot.

  3. Nel progetto di Visual Studio aprire il file Appsettings.json . Incollare l'ID app Microsoft e la password dell'app copiati in precedenza:

       {
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>"
   }

    Usare quindi Visual Studio per i bot C# per distribuire il bot.

    È anche possibile usare una finestra del prompt dei comandi per distribuire un bot di Azure.

  4. In Visual Studio, in Esplora soluzioni, fare clic con il pulsante destro del mouse sul progetto EchoBot e scegliere Pubblica:

    Screenshot that shows publishing your web app from Visual Studio.

  5. Selezionare Nuovo per creare un nuovo profilo di pubblicazione. Per Destinazione selezionare Azure:

    Screenshot that shows how to select Azure as target in a new publishing profile.

    Per la destinazione specifica, selezionare app Azure Servizio:

    Screenshot that shows how to select Azure App Service as the specific target.

  6. Nella configurazione della distribuzione selezionare l'app Web nei risultati visualizzati dopo l'accesso all'account Azure. Per completare il profilo, selezionare Fine e quindi selezionare Pubblica per avviare la distribuzione.

    Screenshot that shows setting the deployment configuration with the web app name.

Ottenere una risorsa di Servizi di comunicazione

Dopo aver creato e distribuito il bot, creare una risorsa di Servizi di comunicazione da usare per configurare un canale di Servizi di comunicazione:

  1. Completare i passaggi per creare una risorsa di Servizi di comunicazione.

  2. Creare un utente di Servizi di comunicazione e rilasciare un token di accesso utente. Assicurarsi di impostare l'ambito per la chat. Copiare la stringa del token e la stringa ID utente.

Abilitare il canale Chat di Servizi di comunicazione

Quando si dispone di una risorsa di Servizi di comunicazione, è possibile configurare un canale di Servizi di comunicazione nella risorsa bot. In questo processo viene generato un ID utente per il bot.

  1. Nella portale di Azure passare alla risorsa azure Bot. Nel menu della risorsa selezionare Canali. Nell'elenco dei canali disponibili selezionare Servizi di comunicazione di Azure - Chat.

    Screenshot that shows opening the Communication Services Chat channel.

  2. Selezionare Connessione per visualizzare un elenco delle risorse di Servizi di comunicazione disponibili nella sottoscrizione.

    Screenshot that shows how to connect a Communication Service resource to the bot.

  3. Nel riquadro Nuovo Connessione ion selezionare la risorsa chat di Servizi di comunicazione e quindi selezionare Applica.

    Screenshot that shows how to save the selected Communication Service resource to create a new Communication Services user ID.

  4. Quando vengono verificati i dettagli della risorsa, nella colonna Bot Servizi di comunicazione di Azure ID viene visualizzato un ID bot. È possibile usare l'ID bot per rappresentare il bot in un thread di chat usando l'API AddParticipant di Chat di Servizi di comunicazione. Dopo aver aggiunto il bot a una chat come partecipante, il bot inizia a ricevere attività correlate alla chat e può rispondere nel thread di chat.

    Screenshot that shows the new Communication Services user ID assigned to the bot.

Creare un'app di chat e aggiungere il bot come partecipante

Ora che si ha l'ID servizi di comunicazione del bot, è possibile creare un thread di chat con il bot come partecipante.

Creare una nuova applicazione C#

  1. Eseguire il comando seguente per creare un'applicazione C#:

    dotnet new console -o ChatQuickstart

  2. Passare alla nuova cartella dell'app e usare il comando per compilare l'applicazione dotnet build :

    cd ChatQuickstart
dotnet build

Installare il pacchetto

Installare Communication Services Chat SDK per .NET:

dotnet add package Azure.Communication.Chat

Creare un client di chat

Per creare un client di chat, usare l'endpoint di Servizi di comunicazione e il token di accesso utente generato in precedenza. Usare la CommunicationIdentityClient classe di Identity SDK per creare un utente ed emettere un token da passare al client di chat. I token di accesso possono essere generati nel portale seguendo le istruzioni seguenti.

Copiare il codice seguente e incollarlo nel file di origine Program.cs :

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Communication Services endpoint
            Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

Avviare un thread di chat con il bot

Usare il createChatThread metodo su chatClient per creare un thread di chat. Sostituire l'ID con l'ID servizi di comunicazione del bot.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
    DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Ottenere un client di thread di chat

Il GetChatThreadClient metodo restituisce un client thread per un thread già esistente:

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Inviare un messaggio a un thread di chat

Per usare SendMessage per inviare un messaggio a un thread:

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Ricevere messaggi di chat da un thread di chat

È possibile ottenere messaggi di chat eseguendo il polling del GetMessages metodo nel client thread di chat a intervalli impostati:

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Controllare l'elenco dei messaggi per la risposta echo del bot a "Hello World".

È possibile usare JavaScript o gli SDK per dispositivi mobili di Azure per sottoscrivere le notifiche dei messaggi in arrivo:

// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Your code here
});

Pulire il thread di chat

Al termine dell'uso del thread di chat, eliminare il thread:

chatClient.DeleteChatThread(threadId);

Distribuire l'applicazione chat C#

Per distribuire l'applicazione chat:

  1. In Visual Studio aprire il progetto di chat.

  2. Fare clic con il pulsante destro del mouse sul progetto ChatQuickstart e scegliere Pubblica:

    Screenshot that shows deploying the chat application to Azure from Visual Studio.

  3. Dopo aver pubblicato la soluzione, eseguirla e verificare se Echobot restituisce il messaggio dell'utente al prompt dei comandi. Ora che è disponibile la soluzione, è possibile procedere con le varie attività necessarie per gli scenari aziendali che è necessario risolvere.

Altre operazioni che è possibile eseguire con un bot

Un bot può ricevere più di un messaggio di testo normale da un utente in un canale chat di Servizi comunicazioni. Alcune delle attività che un bot può ricevere da un utente includono:

  • Aggiornamento della conversazione
  • Aggiornamento dei messaggi
  • Eliminazione del messaggio
  • Indicatore di digitazione
  • Attività evento
  • Vari allegati, incluse le schede adattive
  • Dati del canale bot

Le sezioni successive illustrano alcuni esempi per illustrare queste funzionalità.

Inviare un messaggio di benvenuto quando un nuovo utente viene aggiunto al thread

La logica echo bot corrente accetta l'input dell'utente e la ripete. Se si vuole aggiungere più logica, ad esempio rispondere a un evento di Servizi di comunicazione aggiunto al partecipante, copiare il codice seguente e incollarlo nel file di origine EchoBot.cs :

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples.Bots
{
    public class EchoBot : ActivityHandler
    {
        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        {
            if (turnContext.Activity.Type == ActivityTypes.Message)
            {
                var replyText = $"Echo: {turnContext.Activity.Text}";
                await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
            }
            else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
            {
                if (turnContext.Activity.MembersAdded != null)
                {
                    foreach (var member in turnContext.Activity.MembersAdded)
                    {
                        if (member.Id != turnContext.Activity.Recipient.Id)
                        {
                            await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
                        }
                    }
                }
            }
        }
    }
}

Inviare una scheda adattiva

Nota

Le schede adattive sono supportate solo all'interno di Servizi di comunicazione di Azure casi d'uso in cui tutti i partecipanti alla chat sono Servizi di comunicazione di Azure utenti e non per i casi d'uso di interoperabilità di Teams.

È possibile inviare una scheda adattiva al thread di chat per aumentare l'engagement e l'efficienza. Una scheda adattiva consente anche di comunicare con gli utenti in vari modi. È possibile inviare una scheda adattiva da un bot aggiungendo la scheda come allegato di attività del bot.

Ecco un esempio di come inviare una scheda adattiva:

var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
    ContentType = "application/vnd.microsoft.card.adaptive",
    Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);   
await turnContext.SendActivityAsync(reply, cancellationToken);

Ottenere payload di esempio per le schede adattive in Esempi e modelli.

Per un utente di chat, il canale chat di Servizi di comunicazione aggiunge un campo ai metadati del messaggio che indica che il messaggio ha un allegato. Nei metadati la microsoft.azure.communication.chat.bot.contenttype proprietà è impostata su azurebotservice.adaptivecard.

Di seguito è riportato un esempio di messaggio di chat con una scheda adattiva collegata:

{
    "content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
    "senderDisplayName": "BotDisplayName",
    "metadata": {
    "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
    },
 "messageType": "Text"
}

Inviare un messaggio dall'utente al bot

È possibile inviare un sms di base da un utente al bot nello stesso modo in cui si invia un sms a un altro utente.

Tuttavia, quando si invia un messaggio con un allegato da un utente a un bot, aggiungere questo flag ai metadati di Chat di Servizi di comunicazione:

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"

Per inviare un'attività evento da un utente a un bot, aggiungere questo flag ai metadati della chat di Servizi di comunicazione:

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"

Le sezioni seguenti illustrano i formati di esempio per i messaggi di chat da un utente a un bot.

Messaggio di testo semplice

{
    "content":"Simple text message",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{
        "text":"random text",
        "key1":"value1",
        "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n
        "}, 
    "messageType": "Text"
}

Messaggio con allegato

{
    "content": "{
                        \"text\":\"sample text\", 
                        \"attachments\": [{
                            \"contentType\":\"application/vnd.microsoft.card.adaptive\",
                            \"content\": { \"*adaptive card payload*\" }
                        }]
        }",
    "senderDisplayName": "Acs-Dev-Bot",
    "metadata": {
        "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
        "text": "random text",
        "key1": "value1",
        "key2": "{\r\n  \"subkey1\": \"subValue1\"\r\n}"
    },
        "messageType": "Text"
}

Messaggio con un'attività di evento

Un payload dell'evento include tutti i campi JSON nel contenuto del messaggio, ad eccezione di Name. Il Name campo contiene il nome dell'evento.

Nell'esempio seguente il nome endOfConversation dell'evento con il payload "{field1":"value1", "field2": { "nestedField":"nestedValue" }} viene inviato al bot:

{
    "content":"{
                   \"name\":\"endOfConversation\",
                   \"field1\":\"value1\",
                   \"field2\": {  
                       \"nestedField\":\"nestedValue\"
                    }
               }",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{  
                   "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
                   "text":"random text",
                   "key1":"value1",
                   "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n}"
               },
    "messageType": "Text"
}

Il campo microsoft.azure.communication.chat.bot.contenttype dei metadati è obbligatorio solo in un messaggio inviato da un utente a un bot.

Campi di attività del bot supportati

Le sezioni seguenti descrivono i campi di attività del bot supportati per i flussi da bot a utente e flussi da utente a bot.

Flusso da bot a utente

I campi di attività bot seguenti sono supportati per i flussi da bot a utente.

Attività

  • Message
  • Digitazione

Campi attività messaggio

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (convertito in Servizi SenderDisplayNamedi comunicazione).
  • ChannelData (convertito in Servizi Chat Metadatadi comunicazione . Se i ChannelData valori di mapping sono oggetti, vengono serializzati in formato JSON e inviati come stringa.

Flusso da utente a bot

Questi campi di attività bot sono supportati per i flussi da utente a bot.

Attività e campi

  • Message

    • Id (ID messaggio chat di Servizi di comunicazione)
    • TimeStamp
    • Text
    • Attachments

  • Aggiornamento della conversazione

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Aggiornamento dei messaggi

    • Id (ID messaggio chat di Servizi di comunicazione aggiornato)
    • Text
    • Attachments

  • Eliminazione del messaggio

    • Id (ID messaggio di chat di Servizi di comunicazione eliminato)

  • Event

    • Name
    • Value

  • Digitazione

Altri campi comuni

  • Recipient.Id e Recipient.Name (ID utente chat di Servizi di comunicazione e nome visualizzato)
  • From.Id e From.Name (ID utente chat di Servizi di comunicazione e nome visualizzato)
  • Conversation.Id (ID thread chat di Servizi di comunicazione)
  • ChannelId (Chat di Servizi di comunicazione se vuoto)
  • ChannelData (metadati dei messaggi chat di Servizi di comunicazione)

Modelli di handoff del bot

In alcuni casi, un bot non comprende una domanda o non può rispondere a una domanda. Un cliente potrebbe chiedere nella chat di essere connesso a un agente umano. In questi scenari, il thread di chat deve essere passato dal bot a un agente umano. È possibile progettare l'applicazione per eseguire la transizione di una conversazione da un bot a un essere umano.

Gestione delle comunicazioni da bot a bot

In alcuni casi d'uso, due bot devono essere aggiunti allo stesso thread di chat per fornire servizi diversi. In questo scenario potrebbe essere necessario assicurarsi che un bot non invii risposte automatiche ai messaggi di un altro bot. Se non viene gestito correttamente, l'interazione automatizzata tra i bot potrebbe comportare un ciclo infinito di messaggi.

È possibile verificare l'identità utente di Servizi di comunicazione di un mittente del messaggio nella proprietà dell'attività From.Id . Verificare se appartiene a un altro bot. Eseguire quindi l'azione necessaria per impedire un flusso di comunicazione da bot a bot. Se questo tipo di scenario comporta volumi di chiamate elevati, il canale chat di Servizi di comunicazione limita le richieste e un bot non può inviare e ricevere messaggi.

Altre informazioni sui limiti di limitazione.

Risoluzione dei problemi

Le sezioni seguenti descrivono i modi per risolvere gli scenari comuni.

Non è possibile aggiungere il canale chat

Nel portale per sviluppatori di Microsoft Bot Framework passare a Configuration Bot Messaging (Messaggistica bot di configurazione>) per verificare che l'endpoint sia stato impostato correttamente.

Il bot ottiene un'eccezione non consentita durante la risposta a un messaggio

Verificare che l'ID e la password dell'app Microsoft del bot vengano salvati correttamente nel file di configurazione del bot caricato nell'app Web.

Il bot non può essere aggiunto come partecipante

Verificare che l'ID servizi di comunicazione del bot venga usato correttamente quando viene inviata una richiesta per aggiungere un bot a un thread di chat.

Passaggi successivi

Provare l'app demo del chatbot per una chat 1:1 tra un utente di chat e un bot tramite il componente botFramework WebChat UI.