Legge til en robot i mobilapper og egendefinerte apper

[Dette emnet inneholder dokumentasjon for forhåndsversjonen, og kan bli endret.]

Du kan koble roboten til en egendefinert app slik at appens brukere kan samhandle med roboten direkte fra appen.

I de fleste tilfeller vil den egendefinerte appen være en mobilenhetsapp som enten er en nettbasert app eller en innebygd app eller en adapter til andre tjenester som virksomheten krever.

Det finnes forskjellige fremgangsmåter for å koble til mobilappen, avhengig av om appen er en nettbasert app eller en integrert app.

Det er relativt enkelt å koble roboten til en nettbasert app, siden det innebærer at du kopierer en kodesnutt til appen. Både nettbaserte apper og innebygde eller egendefinerte apper krever likevel betydelig utviklingsekspertise for å integrere roboten fullt ut i appen din. Begge prosedyrene beskrives i denne artikkelen.

Forutsetninger

Koble roboten din til en nettbasert app

  1. I Power Virtual Agents velger du Behandle i navigasjonsruten på siden, og går deretter til Kanaler-kategorien.

  2. Velg Mobilapp-flisen for å åpne konfigurasjonsvinduet.

  3. Kopier koden under Nettbaserte apper-delen, og gi den til programutviklerne slik at de kan legge den til den nettbaserte appen din.

    Legg til roboten i et nettbasert program.

Koble roboten din til en innebygd eller egendefinert app

Tips!

Selv om denne delen beskriver hvordan du kobler til en mobilapp, kan den samme prosessen brukes for tilpassede eller innebygde apper, for eksempel IoT-apper (Tingenes Internett).

Hvis målet er å koble til Azure Bot Service-kanaler, kan utviklerne dine – i tillegg til å følge instruksjonene her – lære mer på Koble roboten din til Azure Bot Service-kanaler.

Viktig!

Instruksjonene i denne delen krever programvareutvikling fra deg eller utviklerne. Den er beregnet på erfarne IT-medarbeidere, for eksempel IT-administratorer eller utviklere som har en solid forståelse av utviklerverktøy, og integrerte utviklingsmiljøer (IDE).

Forutsetninger

Eksempelkoder

Kodesnutter som brukes i dette dokumentet, er fra følgende steder:

Referanser

Instruksjonene i dette dokumentet refererer til følgende:

Hent Power Virtual Agents-robotparameterne dine

Hvis du vil koble til roboten du har bygget med Power Virtual Agents, må du hente robotens navn, robot-ID og leier-ID for å identifisere den.

  1. Kopier navnet på roboten i Power Virtual Agents.

    Hent navnet på roboten.

  2. Velg Behandle i navigasjonsruten på siden, og går deretter til Kanaler-kategorien.

  3. Velg Mobilapp.

    Mobilappkanal.

  4. Kopier og lagre verdiene for Robot-ID og leier-ID ved å klikke på Kopier. Du trenger disse i trinnet Hent Direct Line-token.

    Hent robotens parametere.

Hent Direct Line-token

Hvis du vil starte en samtale med Power Virtual Agents-roboten, trenger du et Direct Line-token. Du må legge til kode som henter et Direct Line-token med Robot-ID og Leier-ID fra den forrige delen i appen din.

Hvis du vil be om et Direct Line-token, kan du sende en GET-forespørsel til endepunkten nedenfor:

GET /api/botmanagement/v1/directline/directlinetoken
Spørringsparameter Kreves
botId ja
tenantId ja

Eksempel:

GET https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=<ENTER-YOUR-BOTID>&tenantId=<ENTER-YOUR-TENANTID>

Hvis forespørselen er vellykket, returneres et Direct Line-token for den forespurte roboten.

Eksempel på eksempelkode

Eksemplet nedenfor bruker eksempler fra Eksempelkode for kontakt for å hente et Direct Line-token for en Power Virtual Agents-robot.

using (var httpRequest = new HttpRequestMessage())
{   
    httpRequest.Method = HttpMethod.Get;
    UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
    uriBuilder.Query = $"botId={BotId}&tenantId={TenantId}";
    httpRequest.RequestUri = uriBuilder.Uri;
    using (var response = await s_httpClient.SendAsync(httpRequest))
    {
        var responseString = await response.Content.ReadAsStringAsync();
        string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
    }
}
/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
    public string Token { get; set; }
}

Svaret blir:

{
  "token": "<token>"
}

Bruk Direct Line til å kommunisere med roboten

Når du har hentet Direct Line-tokenet, er du klar til å ha en samtale med Power Virtual Agents-roboten med Direct Line. Følg instruksjonene under Bot Framework Direct Line API for å starte en samtale og sende og motta meldinger.

Eksempel på eksempelkode

Følgende eksempel bruker eksempler fra eksempelkoden for kobling for å starte en samtale og sende og motta meldinger fra en Power Virtual Agents-robot.

  1. Initialiser en DirectLineClient-forekomst med Direct Line-tokenet og start en diskusjon:

      // Use the retrieved token to create a DirectLineClient instance
      using (var directLineClient = new DirectLineClient(token))
      {
          var conversation = await directLineClient.Conversations.StartConversationAsync();
          string conversationtId = conversation.ConversationId;
      }
    
  2. Etter at du har startet en samtale, kan den identifiseres og kobles sammen ved hjelp av kombinasjonen av token og conversationtId. Sende en brukermelding til en eksisterende samtale:

      // Use the retrieved token to create a DirectLineClient instance
      // Use the conversationId from above step
      // endConversationMessage is your predefined message indicating that user wants to quit the chat
      while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
      {
          using (var directLineClient = new DirectLineClient(token))
          {
              // Send user message using directlineClient
              // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
              await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
              {
                  Type = ActivityTypes.Message,
                  From = new ChannelAccount { Id = "userId", Name = "userName" },
                  Text = inputMessage,
                  TextFormat = "plain",
                  Locale = "en-Us",
              });
          }
      }
    
  3. Hent svaret til roboten med samme token og converstaionId. De hentede Direct Line-svaraktivitetene inneholder meldingene for både bruker og robot. Du kan filtrere svaraktiviteter med navnet på boten for å bare få robotens svarmelding.

      // Use the same token to create a directLineClinet
      using (var directLineClient = new DirectLineClient(token))
      {
          // To get the first response set string watermark = null
          // More information about watermark is available at
          // https://docs.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0
    
          // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
          ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);
    
          // update watermark from response
          watermark = response?.Watermark;
    
          // response contains set of Activity from both user and bot
          // To display bot response only, filter Activity.From.Name equals to your bot name
          List<Activity> botResponses = response?.Activities?.Where(x =>
                    x.Type == ActivityTypes.Message &&
                      string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();
    
          // Display botResponses
      }
    

Oppdatere Direct Line-token

Det kan hende du må legge til kode for å oppdatere Direct Line-tokenet hvis appen har en lang samtale med roboten. Tokenet utløper, men kan oppdateres før det utløper. Finn ut mer under Direct Line-godkjenning.

Eksempel på eksempelkode

Eksemplet nedenfor bruker eksempler fra eksempelkoden for kobling for å oppdatere tokenet for en eksisterende Power Virtual Agents-samtale:

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Del opp samtalenyttelasten fra roboten

Etter at du har startet en samtale med robot, bruker JSON-nyttelasten for samtalen standard Microsoft Bot Framework Direct Line-aktiviteten. Du kan finne ut mer under Bot Framework Direct Line API.

Håndtere avleveringsaktivitet

Hvis programmet ditt trenger å avlevere til en live agent-leverandør, må du håndtere avleveringsaktiviteten. Avleveringsaktivitet sendes når noden "Overfør til agent" er nådd. Du kan finne ut mer om nyttelasten for avleveringsaktiviteten.

Utløs en velkomstmelding

Hvis du vil at roboten din skal sende et Hilsning-systememnet automatisk når en bruker starter en samtale, kan du sende en aktivitet med Type=event og Name=startsConversation.