Snabbstart: Lägga till en robot i chattappen

  • Artikel

Lär dig hur du skapar konversations-AI-upplevelser i ett chattprogram med hjälp av den Azure Communication Services Chat-meddelandekanal som är tillgänglig i Azure Bot Service. I den här snabbstarten skapar du en robot med hjälp av BotFramework SDK. Sedan integrerar du roboten i ett chattprogram som du skapar med hjälp av Communication Services Chat SDK.

I den här snabbstarten lär du dig att:

Förutsättningar

Skapa och distribuera en robot i Azure

Om du vill använda Azure Communication Services-chatt som en kanal i Azure Bot Service distribuerar du först en robot. Om du vill distribuera en robot slutför du följande steg:

  • Skapa en Azure Bot Service-resurs
  • Hämta robotens app-ID och lösenord
  • Skapa en webbapp för att lagra robotlogik
  • Skapa en meddelandeslutpunkt för roboten

Skapa en Azure Bot Service-resurs

Börja med att använda Azure-portalen för att skapa en Azure Bot Service-resurs. Chatkanalen Communication Services stöder chattrobotar med en enda klientorganisation, hanterade identitetsrobotar och robotar med flera klientorganisationer. I den här snabbstarten använder vi en robot för flera klientorganisationer .

Om du vill konfigurera en robot för en enskild klientorganisation eller hanterad identitet läser du botidentitetsinformation.

För en hanterad identitetsrobot kan du behöva uppdatera robottjänstidentiteten.

Hämta robotens app-ID och applösenord

Hämta sedan microsofts app-ID och lösenord som har tilldelats din robot när den distribueras. Du använder dessa värden för senare konfigurationer.

Skapa en webbapp för att lagra robotlogik

Om du vill skapa en webbapp för din robot kan du ändra Bot Builder-exempel för ditt scenario eller använda Bot Builder SDK för att skapa en webbapp. Ett av de enklaste exemplen är Echo Bot.

Azure Bot Service förväntar sig vanligtvis att Bot Application Web App Controller exponerar en slutpunkt i formuläret /api/messages. Slutpunkten hanterar alla meddelanden som skickas till roboten.

Om du vill skapa robotappen använder du antingen Azure CLI för att skapa en Azure App Service-resurs eller skapa appen i Azure-portalen.

Så här skapar du en robotwebbapp med hjälp av Azure-portalen:

  1. I portalen väljer du Skapa en resurs. I sökrutan anger du webbapp. Välj panelen Webbapp .

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

  2. I Skapa webbapp väljer eller anger du information för appen, inklusive den region där du vill distribuera appen.

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

  3. Välj Granska + Skapa för att verifiera distributionen och granska distributionsinformationen. Välj sedan Skapa.

  4. När webbappresursen skapas kopierar du den värdnamns-URL som visas i resursinformationen. URL:en är en del av slutpunkten som du skapar för webbappen.

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

Skapa en meddelandeslutpunkt för roboten

I robotresursen skapar du sedan en slutpunkt för webbappmeddelanden:

  1. I Azure-portalen går du till din Azure Bot-resurs. I resursmenyn väljer du Konfiguration.

  2. I Konfiguration för Meddelandeslutpunkt klistrar du in värdnamns-URL:en för webbappen som du kopierade i föregående avsnitt. Lägg till URL:en med /api/messages.

  3. Välj Spara.

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

Distribuera webbappen

Det sista steget för att skapa en robot är att distribuera webbappen. I den här snabbstarten använder du exempel på Ekorobot. Echo Bot-funktionen är begränsad till att upprepa användarens indata. Så här distribuerar du den till din webbapp i Azure:

  1. Använd Git för att klona den här GitHub-lagringsplatsen:

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

  2. Öppna Echo Bot-projektet i Visual Studio.

  3. Öppna filen Appsettings.json i Visual Studio-projektet. Klistra in Microsoft-app-ID:t och applösenordet som du kopierade tidigare:

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

    Använd sedan Visual Studio för C#-robotar för att distribuera roboten.

    Du kan också använda kommandotolken för att distribuera en Azure-robot.

  4. Högerklicka på EchoBot-projektet i Solution Explorer i Visual Studio och välj Publicera:

    Screenshot that shows publishing your web app from Visual Studio.

  5. Välj Ny för att skapa en ny publiceringsprofil. Som Mål väljer du Azure:

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

    För det specifika målet väljer du Azure App Service:

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

  6. I distributionskonfigurationen väljer du webbappen i de resultat som visas när du har loggat in på ditt Azure-konto. Slutför profilen genom att välja Slutför och sedan Publicera för att starta distributionen.

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

Hämta en Communication Services-resurs

Nu när roboten har skapats och distribuerats skapar du en Communication Services-resurs som ska användas för att konfigurera en Communication Services-kanal:

  1. Slutför stegen för att skapa en Communication Services-resurs.

  2. Skapa en Communication Services-användare och utfärda en användaråtkomsttoken. Se till att ange omfånget till chatt. Kopiera tokensträngen och användar-ID-strängen.

Aktivera kommunikationstjänstens chattkanal

När du har en Communication Services-resurs kan du konfigurera en Communication Services-kanal i robotresursen. I den här processen genereras ett användar-ID för roboten.

  1. I Azure-portalen går du till din Azure Bot-resurs. I resursmenyn väljer du Kanaler. I listan över tillgängliga kanaler väljer du Azure Communications Services – Chat.

    Screenshot that shows opening the Communication Services Chat channel.

  2. Välj Anslut om du vill se en lista över kommunikationstjänster som är tillgängliga i din prenumeration.

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

  3. I fönstret Ny Anslut ion väljer du kommunikationstjänstens chattresurs och väljer sedan Använd.

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

  4. När resursinformationen verifieras visas ett robot-ID i kolumnen Bot Azure Communication Services ID . Du kan använda robot-ID:t för att representera roboten i en chatttråd med hjälp av Communication Services Chat AddParticipant API. När du har lagt till roboten i en chatt som deltagare börjar roboten ta emot chattrelaterade aktiviteter och den kan svara i chatttråden.

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

Skapa en chattapp och lägg till roboten som deltagare

Nu när du har robotens Communication Services-ID kan du skapa en chatttråd med roboten som deltagare.

Skapa ett nytt C#-program

  1. Kör följande kommando för att skapa ett C#-program:

    dotnet new console -o ChatQuickstart

  2. Ändra katalogen till den nya appmappen dotnet build och använd kommandot för att kompilera ditt program:

    cd ChatQuickstart
dotnet build

Installera -paketet

Installera Communication Services Chat SDK för .NET:

dotnet add package Azure.Communication.Chat

Skapa en chattklient

Om du vill skapa en chattklient använder du din Communication Services-slutpunkt och den användaråtkomsttoken som du genererade tidigare. CommunicationIdentityClient Använd klassen från Identity SDK för att skapa en användare och utfärda en token för att skicka till chattklienten. Åtkomsttoken kan genereras i portalen med hjälp av följande instruktioner.

Kopiera följande kod och klistra in den i program.cs-källfilen :

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);
        }
    }
}

Starta en chatttråd med roboten

createChatThread Använd metoden på chatClient för att skapa en chatttråd. Ersätt ID:t med robotens Communication Services-ID.

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;

Hämta en chatttrådsklient

Metoden GetChatThreadClient returnerar en trådklient för en tråd som redan finns:

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

Skicka ett meddelande till en chatttråd

Så här skickar SendMessage du ett meddelande till en tråd:

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

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Ta emot chattmeddelanden från en chatttråd

Du kan hämta chattmeddelanden genom att avsöka GetMessages metoden på chatttrådsklienten med angivna intervall:

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

Kontrollera listan med meddelanden för robotens ekosvar på "Hello World".

Du kan använda JavaScript eller Azure Mobile SDK:er för att prenumerera på inkommande meddelandemeddelanden:

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

Rensa chatttråden

När du är klar med chatttråden tar du bort tråden:

chatClient.DeleteChatThread(threadId);

Distribuera C#-chattprogrammet

Så här distribuerar du chattprogrammet:

  1. Öppna chattprojektet i Visual Studio.

  2. Högerklicka på ChatQuickstart-projektet och välj Publicera:

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

  3. När du har publicerat lösningen kör du den och kontrollerar om Echobot ekar användarmeddelandet i kommandotolken. Nu när du har lösningen kan du fortsätta att spela med de olika aktiviteter som behövs för de affärsscenarier som du behöver lösa för.

Fler saker du kan göra med en robot

En robot kan ta emot mer än ett oformaterad textmeddelande från en användare i en kommunikationstjänstchattkanal. Några av de aktiviteter som en robot kan ta emot från en användare är:

  • Konversationsuppdatering
  • Meddelandeuppdatering
  • Ta bort meddelande
  • Typindikator
  • Händelseaktivitet
  • Olika bifogade filer, inklusive adaptiva kort
  • Robotkanaldata

I nästa avsnitt visas några exempel för att illustrera dessa funktioner.

Skicka ett välkomstmeddelande när en ny användare läggs till i tråden

Den aktuella Echo Bot-logiken accepterar indata från användaren och ekar tillbaka den. Om du vill lägga till mer logik, till exempel svara på en kommunikationstjänsthändelse som lagts till av deltagare, kopierar du följande kod och klistrar in den i källfilen 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);
                        }
                    }
                }
            }
        }
    }
}

Skicka ett adaptivt kort

Kommentar

Anpassningsbara kort stöds endast i Azure Communication Services-användningsfall där alla chattdeltagare är Azure Communication Services-användare och inte för Användningsfall för Teams-interoprability.

Du kan skicka ett adaptivt kort till chatttråden för att öka engagemanget och effektiviteten. Ett adaptivt kort hjälper dig också att kommunicera med användare på olika sätt. Du kan skicka ett adaptivt kort från en robot genom att lägga till kortet som en bifogad robotaktivitet.

Här är ett exempel på hur du skickar ett adaptivt kort:

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);

Hämta exempelnyttolaster för adaptiva kort i Exempel och mallar.

För en chattanvändare lägger kommunikationstjänstens chattkanal till ett fält i meddelandemetadata som anger att meddelandet har en bifogad fil. I metadata är egenskapen inställd på microsoft.azure.communication.chat.bot.contenttypeazurebotservice.adaptivecard.

Här är ett exempel på ett chattmeddelande som har ett adaptivt kort kopplat:

{
    "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"
}

Skicka ett meddelande från användare till robot

Du kan skicka ett grundläggande textmeddelande från en användare till roboten på samma sätt som du skickar ett sms till en annan användare.

Men när du skickar ett meddelande som har en bifogad fil från en användare till en robot lägger du till den här flaggan i Communication Services Chat-metadata:

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

Om du vill skicka en händelseaktivitet från en användare till en robot lägger du till den här flaggan i chatmetadata för Communication Services:

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

I följande avsnitt visas exempelformat för chattmeddelanden från en användare till en robot.

Enkelt textmeddelande

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

Meddelande med en bifogad fil

{
    "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"
}

Meddelande med en händelseaktivitet

En händelsenyttolast innehåller alla JSON-fält i meddelandeinnehållet utom Name. Fältet Name innehåller namnet på händelsen.

I följande exempel skickas händelsenamnet endOfConversation med nyttolasten "{field1":"value1", "field2": { "nestedField":"nestedValue" }} till roboten:

{
    "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"
}

Metadatafältet microsoft.azure.communication.chat.bot.contenttype krävs endast i ett meddelande som skickas från en användare till en robot.

Robotaktivitetsfält som stöds

I följande avsnitt beskrivs fält för robotaktivitet som stöds för robot-till-användare-flöden och användar-till-robot-flöden.

Bot-to-user-flöde

Följande robotaktivitetsfält stöds för robot-till-användare-flöden.

Aktiviteter

  • Meddelande
  • Typing

Fält för meddelandeaktivitet

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (Konverterad till Communication Services SenderDisplayName.)
  • ChannelData (Konverterad till Communication Services Chat Metadata. Om några ChannelData mappningsvärden är objekt serialiseras de i JSON-format och skickas som en sträng.)

Användar-till-robot-flöde

Dessa robotaktivitetsfält stöds för användar-till-robot-flöden.

Aktiviteter och fält

  • Meddelande

    • Id (Meddelande-ID för Communication Services-chatt)
    • TimeStamp
    • Text
    • Attachments

  • Konversationsuppdatering

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Meddelandeuppdatering

    • Id (Uppdaterat meddelande-ID för Communication Services-chatt)
    • Text
    • Attachments

  • Ta bort meddelande

    • Id (Meddelande-ID för borttagna kommunikationstjänster)

  • Event

    • Name
    • Value

  • Typing

Andra vanliga fält

  • Recipient.Id och Recipient.Name (Kommunikationstjänster Chattanvändar-ID och visningsnamn)
  • From.Id och From.Name (Kommunikationstjänster Chattanvändar-ID och visningsnamn)
  • Conversation.Id (Kommunikationstjänster, chatttråds-ID)
  • ChannelId (Communication Services Chat om det är tomt)
  • ChannelData (Meddelandemetadata för Communication Services-chatt)

Mönster för överlämning av robot

Ibland kan en robot inte förstå en fråga, eller så kan den inte svara på en fråga. En kund kan be i chatten att vara ansluten till en mänsklig agent. I dessa scenarier måste chatttråden överlämnas från roboten till en mänsklig agent. Du kan utforma ditt program för att överföra en konversation från en robot till en människa.

Hantera robot-till-robot-kommunikation

I vissa användningsfall måste två robotar läggas till i samma chatttråd för att tillhandahålla olika tjänster. I det här scenariot kan du behöva se till att en robot inte skickar automatiska svar till en annan robots meddelanden. Om den inte hanteras korrekt kan robotarnas automatiserade interaktion mellan dem resultera i en oändlig loop med meddelanden.

Du kan verifiera kommunikationstjänsternas användaridentitet för en meddelandesändare i aktivitetens From.Id egenskap. Kontrollera om den tillhör en annan robot. Vidta sedan den nödvändiga åtgärden för att förhindra ett kommunikationsflöde från robot till robot. Om den här typen av scenario resulterar i höga samtalsvolymer begränsar Kommunikationstjänsternas chattkanal begäranden och en robot kan inte skicka och ta emot meddelanden.

Läs mer om begränsningsgränser.

Felsöka

I följande avsnitt beskrivs olika sätt att felsöka vanliga scenarier.

Det går inte att lägga till chattkanal

I Microsoft Bot Framework-utvecklarportalen går du till Configuration>Bot Messaging för att kontrollera att slutpunkten har angetts korrekt.

Roboten får ett förbjudet undantag när den svarar på ett meddelande

Kontrollera att robotens Microsoft-app-ID och lösenord har sparats korrekt i robotkonfigurationsfilen som du laddar upp till webbappen.

Det går inte att lägga till roboten som deltagare

Kontrollera att robotens Communication Services-ID används korrekt när en begäran skickas för att lägga till en robot i en chatttråd.

Nästa steg

Prova chattrobotens demoapp för en 1:1-chatt mellan en chattanvändare och en robot via BotFramework WebChat-användargränssnittskomponenten.