Condividi tramite

Avvio rapido: 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

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

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 multitenant bot.
  • Per configurare un single-tenant bot o managed identity , vedere Informazioni sull'identità del bot.
  • Per un managed identity bot, 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 bot e pubblicarla in un'app Web

Per creare un bot, è possibile eseguire una delle operazioni seguenti:

  • Rivedere gli esempi di Bot Builder per lo scenario, creare un'app Web e quindi distribuirvi l'esempio di bot.
  • Usare Bot Builder SDK per creare e pubblicare un bot in un'app Web.

Per questa guida introduttiva si userà l'esempio Echo Bot degli esempi di Bot Builder.

Creare un'app Web per contenere l'app bot

Per creare l'app Web, 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 che mostra la creazione di una risorsa dell'app Web nel portale di Azure.

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

    Screenshot che mostra i dettagli da impostare per creare una distribuzione di app Web.

  3. Selezionare Rivedi e crea per convalidare la distribuzione ed esaminare i dettagli della distribuzione. Quindi, 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 che mostra come copiare l'URL dell'endpoint dell'app Web.

Creare un endpoint di messaggistica per il 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.

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 che mostra come creare un endpoint di messaggistica bot usando il nome host dell'app Web.

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:

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

    Usare quindi Visual Studio o VS Code 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 che mostra la pubblicazione dell'app Web da Visual Studio.

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

    Screenshot che mostra come selezionare Azure come destinazione in un nuovo profilo di pubblicazione.

    Per la destinazione specifica, selezionare app Azure Servizio:

    Screenshot che mostra come selezionare app Azure Servizio come destinazione specifica.

  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 che mostra l'impostazione della configurazione della distribuzione con il nome dell'app Web.

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 che mostra l'apertura del canale chat di Servizi di comunicazione.

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

    Screenshot che mostra come connettere una risorsa del servizio di comunicazione al bot.

  3. Nel riquadro Nuova connessione selezionare la risorsa chat di Servizi di comunicazione e quindi selezionare Applica.

    Screenshot che mostra come salvare la risorsa servizio di comunicazione selezionata per creare un nuovo ID utente di Servizi di comunicazione.

  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 che mostra il nuovo ID utente di Servizi di comunicazione assegnato al 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.

Seguire la guida introduttiva "Aggiungi chat alla tua app"

Per creare un'app di chat, seguire la procedura descritta nella guida introduttiva Aggiungere chat all'app .

  1. Sostituire <Resource_Endpoint> con l'endpoint di Servizi di comunicazione dal passaggio Ottenere una risorsa del servizio di comunicazione.
  2. Sostituire <Access_Token> con il token di accesso utente dal passaggio Ottenere una risorsa del servizio di comunicazione.
  3. Sostituire <Access_ID> con i bot ACS_ID dal passaggio Abilitare il canale chat di Servizi di comunicazione.

Eseguire l'applicazione chat C# in locale

Per eseguire l'applicazione chat in locale, usare il dotnet run comando :

dotnet run

Si dovrebbe ricevere un messaggio dal bot nella console che indica "Hello World".

Output di esempio:

1730405535010:Hello World

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.

Impegni

  • 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

Introduzione alle chat

Può essere utile vedere anche gli articoli seguenti: