Delen via

Quickstart: Een bot toevoegen aan uw chat-app

  • Artikel

Meer informatie over het bouwen van conversationele AI-ervaringen in een chattoepassing met behulp van het Chatberichtenkanaal van Azure Communication Services dat beschikbaar is in Azure Bot Service. In deze quickstart maakt u een bot met behulp van de BotFramework SDK. Vervolgens integreert u de bot in een chattoepassing die u maakt met behulp van de Communication Services Chat SDK.

In deze snelstart leert u de volgende zaken:

Vereisten

Een bot maken en implementeren in Azure

Als u Azure Communication Services-chat wilt gebruiken als een kanaal in Azure Bot Service, implementeert u eerst een bot. Als u een bot wilt implementeren, voert u de volgende stappen uit:

Een Azure Bot Service-resource maken

Gebruik eerst Azure Portal om een Azure Bot Service-resource te maken. Communication Services Chat-kanaal ondersteunt bots met één tenant, bots met beheerde identiteiten en multitenant-bots.

De app-id en het app-wachtwoord van de bot ophalen

Haal vervolgens de Microsoft-app-id en het wachtwoord op die zijn toegewezen aan uw bot wanneer deze wordt geïmplementeerd. U gebruikt deze waarden voor latere configuraties.

Een bot-app maken en publiceren naar een web-app

Als u een bot wilt maken, kunt u een van de volgende handelingen uitvoeren:

  • Wijzig Bot Builder-voorbeelden voor uw scenario, maak een web-app en implementeer vervolgens uw botvoorbeeld.
  • Gebruik de Bot Builder SDK om een bot te maken en te publiceren naar een web-app.

Voor deze quickstart gebruiken we het Echo Bot-voorbeeld uit de Bot Builder-voorbeelden.

Een web-app maken voor het opslaan van de bot-app

Als u de web-app wilt maken, gebruikt u de Azure CLI om een Azure-app Service-resource te maken of de app te maken in Azure Portal.

Ga als volgende te werk om een bot-web-app te maken met behulp van Azure Portal:

  1. Selecteer een resource maken in de portal. Voer in het zoekvak de web-app in. Selecteer de tegel Web App .

    Schermopname van het maken van een web-app-resource in Azure Portal.

  2. Selecteer of voer in Web-app maken details in voor de app, inclusief de regio waar u de app wilt implementeren.

    Schermopname met details die moeten worden ingesteld om een web-app-implementatie te maken.

  3. Selecteer Beoordelen en maken om de implementatie te valideren en de implementatiedetails te controleren. Ten slotte selecteert u Maken.

  4. Wanneer de web-app-resource wordt gemaakt, kopieert u de hostnaam-URL die wordt weergegeven in de resourcedetails. De URL maakt deel uit van het eindpunt dat u voor de web-app maakt.

    Schermopname van het kopiëren van de eindpunt-URL van de web-app.

Een berichteindpunt voor de bot maken

Azure Bot Service verwacht doorgaans dat de Bot Application Web App Controller een eindpunt in het formulier beschikbaar /api/messagesmaakt. Het eindpunt verwerkt alle berichten die naar de bot worden verzonden.

Maak vervolgens in de botresource een eindpunt voor het verzenden van web-apps:

  1. Ga in Azure Portal naar uw Azure Bot-resource. Selecteer Configuratie in het resourcemenu.

  2. Plak in Configuratie voor het berichteindpunt de hostnaam-URL van de web-app die u in de vorige sectie hebt gekopieerd. Voeg de URL toe met /api/messages.

  3. Selecteer Opslaan.

Schermopname van het maken van een botberichteneindpunt met behulp van de hostnaam van de web-app.

De web-app implementeren

De laatste stap voor het maken van een bot is het implementeren van de web-app. Gebruik voor deze quickstart het voorbeeld van de Echo-bot . De functionaliteit van de Echo-bot is beperkt tot het echoën van de gebruikersinvoer. U implementeert deze als volgt in uw web-app in Azure:

  1. Gebruik Git om deze GitHub-opslagplaats te klonen:

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

  2. Open in Visual Studio het Echo Bot-project.

  3. Open het Appsettings.json-bestand in het Visual Studio-project. Plak de Microsoft-app-id en het app-wachtwoord dat u eerder hebt gekopieerd:

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

    Gebruik vervolgens Visual Studio of VS Code voor C#-bots om de bot te implementeren.

    U kunt ook een opdrachtpromptvenster gebruiken om een Azure-bot te implementeren.

  4. Klik in Visual Studio in Solution Explorer met de rechtermuisknop op het EchoBot-project en selecteer Publiceren:

    Schermopname van het publiceren van uw web-app vanuit Visual Studio.

  5. Selecteer Nieuw om een nieuw publicatieprofiel te maken. Selecteer Azure voor Target:

    Schermopname van het selecteren van Azure als doel in een nieuw publicatieprofiel.

    Selecteer Azure-app Service voor het specifieke doel:

    Schermopname van het selecteren van Azure-app Service als het specifieke doel.

  6. Selecteer in de implementatieconfiguratie de web-app in de resultaten die worden weergegeven nadat u zich hebt aangemeld bij uw Azure-account. Als u het profiel wilt voltooien, selecteert u Voltooien en selecteert u Publiceren om de implementatie te starten.

    Schermopname van het instellen van de implementatieconfiguratie met de naam van de web-app.

Een Communication Services-resource ophalen

Nu uw bot is gemaakt en geïmplementeerd, maakt u een Communication Services-resource om een Communication Services-kanaal in te stellen:

  1. Voer de stappen uit om een Communication Services-resource te maken.

  2. Maak een Communication Services-gebruiker en geef een toegangstoken voor gebruikers uit. Zorg ervoor dat u het bereik instelt op chatten. Kopieer de tokentekenreeks en de gebruikers-id-tekenreeks.

Het Communication Services-chatkanaal inschakelen

Wanneer u een Communication Services-resource hebt, kunt u een Communication Services-kanaal instellen in de botresource. In dit proces wordt een gebruikers-id gegenereerd voor de bot.

  1. Ga in Azure Portal naar uw Azure Bot-resource. Selecteer Kanalen in het resourcemenu. Selecteer Azure Communications Services - Chat in de lijst met beschikbare kanalen.

    Schermopname van het openen van het Communication Services Chat-kanaal.

  2. Selecteer Verbinding maken om een lijst weer te geven met Communication Services-resources die beschikbaar zijn in uw abonnement.

    Schermopname van het verbinden van een Communication Service-resource met de bot.

  3. Selecteer in het deelvenster Nieuwe verbinding de Communication Services-chatresource en selecteer vervolgens Toepassen.

    Schermopname van het opslaan van de geselecteerde Communication Service-resource om een nieuwe Communication Services-gebruikers-id te maken.

  4. Wanneer de resourcegegevens worden geverifieerd, wordt een bot-id weergegeven in de kolom Bot Azure Communication Services-id . U kunt de bot-id gebruiken om de bot in een chatthread weer te geven met behulp van de Communication Services Chat AddParticipant-API. Nadat u de bot als deelnemer aan een chat hebt toegevoegd, begint de bot chatgerelateerde activiteiten te ontvangen en kan deze reageren in de chat-thread.

    Schermopname van de nieuwe Communication Services-gebruikers-id die is toegewezen aan de bot.

Een chat-app maken en de bot toevoegen als deelnemer

Nu u de Communication Services-id van de bot hebt, kunt u als deelnemer een chatgesprek met de bot maken.

Volg de quickstart Chat toevoegen aan uw app

Volg de stappen in de quickstart Chat toevoegen aan uw app om een chat-app te maken.

  1. Vervang <Resource_Endpoint> door het Communication Services-eindpunt uit de stap Een Communication Service-resource ophalen.
  2. Vervang <Access_Token> door het toegangstoken van de gebruiker uit de stap Een Communication Service-resource ophalen.
  3. Vervang <Access_ID> door de bots ACS_ID uit de stap Chatkanaal van Communication Services inschakelen.

De C#-chattoepassing lokaal uitvoeren

Gebruik de dotnet run opdracht om de chattoepassing lokaal uit te voeren:

dotnet run

U ontvangt een bericht van de bot in de console met de tekst 'Hallo wereld'.

Voorbeelduitvoer:

1730405535010:Hello World

Meer dingen die u met een bot kunt doen

Een bot kan meer dan een bericht zonder opmaak ontvangen van een gebruiker in een Communications Services Chat-kanaal. Enkele van de activiteiten die een bot van een gebruiker kan ontvangen, zijn:

  • Gespreksupdate
  • Berichtupdate
  • Bericht verwijderen
  • Indicator voor typen
  • Gebeurtenisactiviteit
  • Diverse bijlagen, waaronder adaptieve kaarten
  • Botkanaalgegevens

In de volgende secties ziet u enkele voorbeelden om deze functies te illustreren.

Een welkomstbericht verzenden wanneer een nieuwe gebruiker wordt toegevoegd aan de thread

De huidige logica van echobot accepteert invoer van de gebruiker en echot deze terug. Als u meer logica wilt toevoegen, zoals reageren op een door een deelnemer toegevoegde Communication Services-gebeurtenis, kopieert u de volgende code en plakt u deze in het EchoBot.cs bronbestand:

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

Een adaptieve kaart verzenden

Notitie

Adaptieve kaarten worden alleen ondersteund in azure Communication Services-gebruiksvoorbeelden waarbij alle chatdeelnemers Azure Communication Services-gebruikers zijn en niet voor gebruiksscenario's van Teams.

U kunt een adaptieve kaart naar de chatthread verzenden om de betrokkenheid en efficiëntie te vergroten. Een adaptieve kaart helpt u ook op verschillende manieren met gebruikers te communiceren. U kunt een adaptieve kaart verzenden vanuit een bot door de kaart toe te voegen als bijlage bij botactiviteiten.

Hier volgt een voorbeeld van het verzenden van een adaptieve kaart:

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

Haal voorbeeldpayloads op voor adaptieve kaarten bij Voorbeelden en sjablonen.

Voor een chatgebruiker voegt het Communication Services Chat-kanaal een veld toe aan de metagegevens van het bericht die aangeeft dat het bericht een bijlage heeft. In de metagegevens is de microsoft.azure.communication.chat.bot.contenttype eigenschap ingesteld op azurebotservice.adaptivecard.

Hier volgt een voorbeeld van een chatbericht waaraan een adaptieve kaart is gekoppeld:

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

Een bericht verzenden van gebruiker naar bot

U kunt een eenvoudig tekstbericht van een gebruiker naar de bot verzenden op dezelfde manier als u een sms-bericht naar een andere gebruiker verzendt.

Wanneer u echter een bericht met een bijlage van een gebruiker naar een bot verzendt, voegt u deze vlag toe aan de metagegevens van Communication Services Chat:

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

Als u een gebeurtenisactiviteit van een gebruiker naar een bot wilt verzenden, voegt u deze vlag toe aan de metagegevens van de Communication Services Chat:

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

In de volgende secties ziet u voorbeeldindelingen voor chatberichten van een gebruiker naar een bot.

Eenvoudig tekstbericht

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

Bericht met een bijlage

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

Bericht met een gebeurtenisactiviteit

Een nettolading van een gebeurtenis bevat alle JSON-velden in de berichtinhoud, behalve Name. Het Name veld bevat de naam van de gebeurtenis.

In het volgende voorbeeld wordt de gebeurtenisnaam endOfConversation met de nettolading "{field1":"value1", "field2": { "nestedField":"nestedValue" }} verzonden naar de 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"
}

Het metagegevensveld microsoft.azure.communication.chat.bot.contenttype is alleen vereist in een bericht dat van een gebruiker naar een bot wordt verzonden.

Ondersteunde velden voor botactiviteit

In de volgende secties worden ondersteunde botactiviteitsvelden beschreven voor bot-naar-gebruikersstromen en gebruikers-naar-bot-stromen.

Bot-naar-gebruiker-stroom

De volgende velden voor botactiviteit worden ondersteund voor bot-naar-gebruikersstromen.

Activiteiten

  • Bericht
  • Typen

Velden voor berichtactiviteit

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (Geconverteerd naar Communication Services SenderDisplayName.)
  • ChannelData (Geconverteerd naar Communication Services Chat Metadata. Als toewijzingswaarden ChannelData objecten zijn, worden ze geserialiseerd in JSON-indeling en verzonden als een tekenreeks.)

Stroom van gebruiker naar bot

Deze velden voor botactiviteit worden ondersteund voor gebruikers-naar-bot-stromen.

Activiteiten en velden

  • Bericht

    • Id (Chatbericht-id van Communication Services)
    • TimeStamp
    • Text
    • Attachments

  • Gespreksupdate

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Berichtupdate

    • Id (Bericht-id van Communication Services-chat bijgewerkt)
    • Text
    • Attachments

  • Bericht verwijderen

    • Id (Chatbericht-id van Verwijderde Communication Services)

  • Gebeurtenis

    • Name
    • Value

  • Typen

Andere algemene velden

  • Recipient.Id en Recipient.Name (Communication Services Chat-gebruikers-id en weergavenaam)
  • From.Id en From.Name (Communication Services Chat-gebruikers-id en weergavenaam)
  • Conversation.Id (Chat-id van Communication Services)
  • ChannelId (Communication Services Chat indien leeg)
  • ChannelData (Metagegevens van chatberichten van Communication Services)

Hand-offpatronen van bot

Soms begrijpt een bot een vraag niet of kan deze een vraag niet beantwoorden. Een klant kan in de chat vragen om verbinding te maken met een menselijke agent. In deze scenario's moet de chatthread worden overgedragen van de bot aan een menselijke agent. U kunt uw toepassing ontwerpen om een gesprek van een bot over te schakelen naar een mens.

Communicatie tussen bots verwerken

In sommige gevallen moeten twee bots worden toegevoegd aan dezelfde chat-thread om verschillende services te kunnen bieden. In dit scenario moet u er mogelijk voor zorgen dat een bot geen geautomatiseerde antwoorden naar berichten van een andere bot verzendt. Als de interactie tussen de bots niet goed wordt verwerkt, kan dit leiden tot een oneindige lus met berichten.

U kunt de Communication Services-gebruikersidentiteit van een afzender van een bericht controleren in de eigenschap van From.Id de activiteit. Controleer of deze deel uitmaakt van een andere bot. Voer vervolgens de vereiste actie uit om een bot-naar-bot-communicatiestroom te voorkomen. Als dit type scenario resulteert in grote oproepvolumes, beperkt het Communication Services Chat-kanaal de aanvragen en kan een bot geen berichten verzenden en ontvangen.

Meer informatie over beperkingslimieten.

Problemen oplossen

In de volgende secties worden manieren beschreven om veelvoorkomende scenario's op te lossen.

Chatkanaal kan niet worden toegevoegd

Ga in de ontwikkelaarsportal van Microsoft Bot Framework naar Configuration>Bot Messaging om te controleren of het eindpunt juist is ingesteld.

Bot krijgt een verboden uitzondering tijdens het beantwoorden van een bericht

Controleer of de Microsoft-app-id en het wachtwoord van de bot correct zijn opgeslagen in het botconfiguratiebestand dat u uploadt naar de web-app.

Bot kan niet worden toegevoegd als deelnemer

Controleer of de Communication Services-id van de bot correct wordt gebruikt wanneer een aanvraag wordt verzonden om een bot toe te voegen aan een chatgesprek.

Volgende stappen

Aan de slag met chat

U wilt mogelijk ook: