Publicera en handläggare till mobila eller anpassade appar

Artikel
12/09/2024

Du kan ansluta dina handläggare till en anpassad app så att appens användare kan interagera med handläggare direkt från din app.

I de flesta fall är din anpassade app en mobilapp som antingen är en webbaserad app eller en inbyggd app eller adapter till andra tjänster som ditt företag kräver.

Det finns olika sätt att ansluta till din mobilapp, beroende på om din app är en webbaserad app eller en ursprunglig app.

Att ansluta din handläggare till en webbaserad app är relativt enkelt eftersom det innebär att du kopierar en kod kodavsnitt till din app. Både webbaserade appar och inbyggda eller anpassade appar kräver dock fortfarande betydande utvecklarkunskaper för att fullt ut integrera handläggare i din app. Båda procedurerna beskrivs i den här artikeln.

Förutsättningar

.NET Core SDK version 2.1.
NuGet-paket Microsoft.Bot.Connector.DirectLine.
En handläggare skapad i Copilot Studio och med att du vill ansluta till din app.

Anslut din handläggare till en webbaserad app

I Copilot Studio, väljer Kanaler på navigeringsmenyn.
Välj panelen Mobilapp för att öppna konfigurationsfönstret.
Kopiera koden under avsnittet Webbaserade appar och lämna apputvecklare som ska läggas till i den webbaserade appen.

Anslut din handläggare till en inbyggd eller anpassad app

Tips!

I det här avsnittet beskrivs hur du ansluter till en mobilapp, men samma process kan användas för anpassade appar, t.ex. IoT (sakernas Internet).

Om ditt mål är att ansluta till Azure Bot Service kanaler kan utvecklarna, förutom att följa instruktionerna Hit, läsa mer på Publicera en handläggare till Azure Bot Service kanaler.

Viktigt

Instruktioner i det här avsnittet kräver programvaruutveckling från dig eller dina utvecklare. Den är avsedd för erfarna IT-proffs, t.ex. IT-administratörer eller IT-utvecklare med en gedigen förståelse för utvecklarverktyg, verktyg samt IDE:er.

Kodexempel

Kodavsnitt som används i det här dokumentet är från:

Anslutningsprogram exempelkod

Referenser

Anvisningarna i det här dokumentet hänvisar till följande källmaterial:

Hämta dina Copilot Studio handläggare parametrar

Om du vill ansluta till den handläggare du skapade måste du hämta namnet på handläggare och den token som slutpunkt för att identifiera den.

I Copilot Studio navigerar du till sidan Översikt för din handläggare och kopierar namnet på din handläggare.
Välj Kanaler>Mobilapp.
På sidan Mobilapp bredvid Tokenslutpunkt väljer du Kopiera. Du behöver denna slutpunkt för steget Hämta Direct Line-token.

Hämta Direct Line-token

För att starta en konversation med din handläggare behöver du en Direct Line token. Denna token kan hämtas genom att göra en GET-förfrågan till slutpunkt som visas på Copilot Studio-skärmen. Denna token måste sedan användas som rubrik för efterföljande anrop till Directline API.

Exempel:

GET <BOT TOKEN ENDPOINT>

Om begäran lyckas returneras en Direct Line token, förfallotid och ett conversationId för den begärda handläggare. Exempel:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

Exempel på exempelkod

I följande exempel används exempel från exempelkoden anslutningsprogram för att hämta en Direct Line token för a Copilot Studio handläggare.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

Svarsobjektet är samma som i GETGET-förfrågan som vi såg tidigare.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Används Direct Line för att kommunicera med handläggare

När du har hämtat Direct Line token är du redo att ha en konversation med din Copilot Studio handläggare med Direct Line. För att starta en konversation och skicka och ta emot meddelanden, följ instruktionerna på Bot Framework Direct Line API.

I följande exempel används exempel från exempelkoden anslutningsprogram för att starta en konversation och skicka och ta emot meddelanden från a Copilot Studio handläggare.

Initiera en DirectLineClient-instans med din Direct Line-token och starta en konversation:

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

När en konversation har startats kan den identifieras och kopplas ihop med hjälp av kombinationen token och conversationtId. Skicka ett användarmeddelande till en befintlig konversation:

   // 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",
           });
       }
   }

Hämta handläggare:s svar med samma token och conversationId. De hämtade Direct Line svar aktiviteterna innehåller både användarens och handläggare meddelanden. Du kan filtrera svar aktiviteter efter ditt handläggare namn för att bara få meddelandet handläggare svar.

   // Use the same token to create a directLineClient
   using (var directLineClient = new DirectLineClient(token))
   {
       // To get the first response set string watermark = null
       // More information about watermark is available at
       // https://learn.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
   }

Uppdatera Direct Line-token

Du kan behöva lägga till kod för att uppdatera Direct Line token om ditt program har en lång konversation med handläggare. Token förfaller men kan uppdateras innan det upphör att gälla. Läs mer på Direct Line-autentisering.

I följande exempel används exempel från Anslutningsprogram exempelkod för att uppdatera token för en befintlig Copilot Studio-konversation:

  // 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

Parsa konversationsnyttolast från handläggare

När du har startat en konversation med handläggare använder konversationens JSON-nyttolast standardaktiviteten Microsoft Bot Framework Direct Line . Du kan läsa mer på Bot Framework Direct Line API.

Hantera överlämnande av aktivitet

Om ditt program behöver överlämnas till en live-handläggare måste du överlämna aktiviteten. Överlämningsaktiviteten skickas när noden ”Överför till handläggare” trycks ned. Du kan läsa mer om nyttolast för av överlämningsaktiviteten.

Utlösa ett välkomstmeddelande

Om du vill att din handläggare ska skicka hälsningen systemämne automatiskt när en användare startar en konversation kan du skicka en aktivitet med Type=event och Name=startConversation.

Dela via