Snabbstart: Lägga till en robot i chattappen
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:
- Skapa och distribuera en robot i Azure
- Hämta en Communication Services-resurs
- Aktivera Chat-kanalen för Communication Services för roboten
- Skapa en chattapp och lägg till roboten som deltagare
- Utforska fler funktioner för din robot
Förutsättningar
- Ett Azure-konto och en aktiv prenumeration. Skapa ett konto kostnadsfritt.
- Visual Studio 2019 eller senare.
- Den senaste versionen av .NET Core. I den här snabbstarten använder vi .NET Core 3.1. Se till att installera den version som motsvarar din instans av Visual Studio, 32-bitars eller 64-bitars.
- Bot Framework SDK
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:
I portalen väljer du Skapa en resurs. I sökrutan anger du webbapp. Välj panelen Webbapp .
I Skapa webbapp väljer eller anger du information för appen, inklusive den region där du vill distribuera appen.
Välj Granska + Skapa för att verifiera distributionen och granska distributionsinformationen. Välj sedan Skapa.
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.
Skapa en meddelandeslutpunkt för roboten
I robotresursen skapar du sedan en slutpunkt för webbappmeddelanden:
I Azure-portalen går du till din Azure Bot-resurs. I resursmenyn väljer du Konfiguration.
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
.Välj Spara.
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:
Använd Git för att klona den här GitHub-lagringsplatsen:
git clone https://github.com/Microsoft/BotBuilder-Samples.git cd BotBuilder-Samples
Öppna Echo Bot-projektet i Visual Studio.
Ö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.
Högerklicka på EchoBot-projektet i Solution Explorer i Visual Studio och välj Publicera:
Välj Ny för att skapa en ny publiceringsprofil. Som Mål väljer du Azure:
För det specifika målet väljer du Azure App Service:
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.
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:
Slutför stegen för att skapa en Communication Services-resurs.
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.
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.
Välj Anslut om du vill se en lista över kommunikationstjänster som är tillgängliga i din prenumeration.
I fönstret Ny Anslut ion väljer du kommunikationstjänstens chattresurs och väljer sedan Använd.
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.
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
Kör följande kommando för att skapa ett C#-program:
dotnet new console -o ChatQuickstart
Ä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:
Öppna chattprojektet i Visual Studio.
Högerklicka på ChatQuickstart-projektet och välj Publicera:
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.contenttype
azurebotservice.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 ServicesSenderDisplayName
.)ChannelData
(Konverterad till Communication ServicesChat Metadata
. Om någraChannelData
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
ochRecipient.Name
(Kommunikationstjänster Chattanvändar-ID och visningsnamn)From.Id
ochFrom.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.