將專員發佈到行動裝置或自訂應用程式

發行項
12/09/2024

您可以將專員連線到自定義應用程式，以便該應用程式的使用者可以直接從應用程式內與專員交互。

在大部分的案例中，您的自訂應用程式將是行動裝置應用程式，它是 Web 應用程式，或是原生應用程式或您業務所需其他服務的配接器。

根據您的應用程式是 Web 應用程式或原生應用程式，有不同的程序可連接至行動裝置應用程式。

將專員連接到基於 Web 的應用程式相對簡單，因為它涉及將代碼程式碼片段複製到應用程式中。但是，基於 Web 的應用程式和本機或自定義應用程式仍然需要大量的開發人員專業知識才能將專員完全集成到您的應用程式中。本文將說明這兩個程序。

先決條件

.NET Core SDK 版本 2.1。
Nuget 套件 Microsoft.Bot.Connector.DirectLine。
在 Copilot Studio 您希望連線到您的應用程式中創建的專員。

連線專員到基於 Web 的應用程式

在 Copilot Studio 的導覽功能表中，選擇管道。
選取行動裝置應用程式圖標以開啟設定視窗。
在 Web 應用程式區段中複製程式碼，並將它提供給您的應用程式開發人員，以新增至您的 Web 應用程式。

連線專員到本機或自定義應用程式

提示

雖然本節描述如何連接至行動裝置應用程式，但是相同的程序可以應用於自訂或原生應用程式，例如 IoT (物聯網) 應用程式。

如果您的目標是連線 Azure Bot Service 個管道，除了按照此處的說明操作之外，您的開發人員還可以在發佈專員到 Azure Bot Service 渠道中瞭解更多資訊。

重要

本節中的指示需要由您或您的開發人員進行軟體開發。它適用於有經驗的 IT 專業人員，例如 IT 系統管理員或開發人員，他們深刻了解開發人員工具、公用程式及 IDE。

程式碼範例

本文件所用的程式碼片段來自：

連接器範例程式碼

檢索 # Copilot Studio 專員參數

要連線您構建的專員，您需要檢索專員的名稱和令牌端點來識別它。

Copilot Studio在 專員的 Overview (概述 ) 頁面，然後複製專員的名稱。
選擇管道>行動應用程式。
在行動應用程式頁面上，選擇權杖端點旁的複製。在取得 Direct Line 權杖的步驟中，您會需要此端點。

取得 Direct Line權杖

要使用專員開始對話，您需要一個 Direct Line 令牌。可以透過向 Copilot Studio 畫面中指示的端點發出 GET 要求來取得此權杖。然後必須將該權杖用作後續呼叫 directline API 的標題。

範例:

GET <BOT TOKEN ENDPOINT>

如果請求成功，將返回 Direct Line 請求的專員的 token、過期時間和 conversationId。範例:

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

範例程式碼

以下示例使用連接器示例代碼中的示例來獲取 Direct Line a Copilot Studio 專員的令牌。

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

回覆對象與我們之前看到的 GET 請求相同。

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

用於 Direct Line 與專員通信

檢索令牌 Direct Line 后，您就可以與 Your Copilot Studio 專員 Direct Line 進行對話了。要開始進行交談並傳送和接收訊息，請依照 Bot Framework Direct Line API 的指示進行。

以下範例使用連接器範例代碼中的範例來啟動對話並從 a# 發送和接收消息 a Copilot Studio 專員。

使用 Direct Line 權杖初始化 DirectLineClient 執行個體，並開始交談：

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

開始後，即可結合使用 token 和 conversationtId 來識別和連接每個交談。將使用者訊息傳送至現有的交談：

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

使用相同的 token and conversationId 檢索專員的回覆。 retrieved Direct Line 回覆活動同時包含 user 和專員的消息。您可以按專員的名稱篩選回覆活動，以僅獲取專員的回覆消息。

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

重新整理 Direct Line 權杖

如果您的應用程式與專員有長時間的對話，則可能需要添加代碼來刷新 Direct Line 令牌。權杖會到期，但在到期之前可以進行重新整理；在 Direct Line 驗證深入瞭解。

下列範例使用連接器範例程式碼中的範例，重新整理現有 Copilot Studio 交談的權杖：

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

解析專員

使用專員開始對話後，對話 JSON 負載將使用 standard Microsoft Bot Framework Direct Line 活動。您可以在 Bot Framework Direct Line API 中學到更多內容。

處理移交活動

如果您的應用程式需要移交給真人專員提供者，您需要處理該移交活動。當點擊 [轉接專員] 節點時，會傳送移交活動。您可以深入了解移交活動的承載。

觸發歡迎訊息

如果您希望專員在使用者開始對話時自動發送問候系統主題，則可以使用 and Type=event 發送活動 Name=startConversation。

共用方式為