Publicar un copiloto a aplicaciones móviles o personalizadas

Artículo
09/27/2024

Puede conectar su copiloto a una aplicación personalizada para que los usuarios de la aplicación puedan interactuar con el copiloto directamente desde su aplicación.

En la mayoría de los casos, su aplicación personalizada será una aplicación para dispositivos móviles nativa o basada en web o bien un adaptador para otros servicios que su empresa requiera.

Existen diferentes procedimientos para conectarse a su aplicación móvil, dependiendo de si su aplicación es una aplicación basada en la web o una aplicación nativa.

Conectar su copiloto a una aplicación web es relativamente sencillo, ya que implica copiar un fragmento de código en su aplicación. Sin embargo, tanto las aplicaciones basadas en la web como las aplicaciones nativas o personalizadas aún requieren una considerable experiencia de desarrollador para integrar completamente el copiloto en su aplicación. Ambos procedimientos se describen en este artículo.

Requisitos previos

.NET Core SDK versión 2.1.
Paquete Nuget Microsoft.Bot.Connector.DirectLine.
Un copiloto creado en Copilot Studio que desea conectar a su aplicación.

Conectar su copiloto a una aplicación basada en web

En Copilot Studio, en el menú de navegación, Seleccionar Canales.
Seleccione el icono de Aplicación móvil para abrir la ventana de configuración.
Copie el código debajo de la sección Aplicaciones basadas en la web y proporcióneselo a sus desarrolladores de aplicaciones para que lo agreguen a su aplicación basada en la web.

Conectar su copiloto a una aplicación nativa o personalizada

Propina

Aunque esta sección describe cómo conectarse a una aplicación móvil, podría aplicarse el mismo proceso para aplicaciones personalizadas o nativas, como aplicaciones IoT (Internet de las cosas).

Si su objetivo es conectarse a los canales de Azure Bot Service, además de seguir las instrucciones que se proporcionan aquí, sus desarrolladores pueden obtener más información en Publicar un copiloto en los canales de Azure Bot Service.

Importante

Las instrucciones de esta sección requieren que usted o sus desarrolladores realicen tareas de desarrollo de software. Está destinado a profesionales de TI con experiencia, como administradores de TI o desarrolladores que tienen una sólida comprensión de las herramientas de desarrollo, las utilidades y los IDE.

Ejemplos de código

Los fragmentos de código utilizados en este documento son de:

Código de muestra del conector

Referencias

Las instrucciones de este documento hacen referencia al material de origen siguiente:

Recuperar sus parámetros de copiloto de Copilot Studio

Para conectarse al copiloto que ha creado, deberá recuperar el nombre de su copiloto y punto de conexión de token para identificarlo.

En Copilot Studio, navega a la página Descripción general de tu copiloto y copia su nombre.
Seleccionar Canales>Aplicación móvil.
En la página de la Aplicación móvil , junto a Token punto de conexión, Seleccionar Copiar. Necesitará este punto de conexión para el paso Obtener símbolo de Direct Line.

Obtener símbolo de Direct Line

Para iniciar una conversación con su copiloto, necesita un símbolo de Direct Line. Este token se puede obtener realizando una solicitud GET al punto de conexión indicado en la pantalla de Copilot Studio. Este símbolo (token) debe usarse como encabezado para las llamadas posteriores a la API de línea directa.

Ejemplo:

GET <BOT TOKEN ENDPOINT>

Si la solicitud es correcta, se devolverá un token de Direct Line, tiempo de vencimiento y un conversationId para el copiloto solicitado. Ejemplo:

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

Ejemplo de código de muestra

El siguiente ejemplo utiliza muestras del Código de ejemplo de conector para obtener un símbolo de Direct Line para un copiloto de 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; }
}

El objeto respuesta es el mismo que la solicitud que vimos anteriormente. GET

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

Utilizar Direct Line para comunicarse con el copiloto

Después de recuperar el token, estás listo para tener una conversación con tu copiloto con Direct Line Copilot Studio Direct Line Para iniciar una conversación y enviar y recibir mensajes, siga las instrucciones de la API de Direct Line de Bot Framework.

El siguiente ejemplo utiliza muestras de Código de ejemplo de conector para iniciar una conversación y enviar y recibir mensajes de un copiloto de Copilot Studio.

Inicie una instancia de DirectLineClient con el token de Direct Line y empiece una conversación:

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

Una vez iniciada, cada conversación se puede identificar y conectar mediante la combinación de token y conversationtId. Envíe un mensaje de usuario a una conversación existente:

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

Recupere la respuesta del copiloto usando el mismo token y conversationId. Las actividades respuesta recuperadas contienen mensajes tanto del usuario como del copiloto. Direct Line Puede filtrar las actividades de respuesta por el nombre de su copiloto para obtener solo el mensaje de respuesta del copiloto.

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

Actualizar el símbolo de Direct Line

Es posible que necesites agregar código para actualizar el token si tu aplicación tiene una conversación larga con el copiloto. Direct Line El símbolo expira, pero puede actualizarlo antes de que expire; obtenga más información en Autenticación de Direct Line.

El siguiente ejemplo utiliza muestras del Código de ejemplo de conector para actualizar el token para una conversación de Copilot Studio existente:

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

Analizar la carga de la conversación del copiloto

Después de iniciar una conversación con el copiloto, la carga útil JSON de la conversación utiliza la actividad estándar. Microsoft Bot Framework Direct Line Puede obtener más información en la API de Direct Line de Bot Framework.

Gestionar la actividad de transferencia

Si su aplicación debe transferirse a un proveedor de agente por chat, deberá gestionar la actividad de transferencia. La actividad de transferencia se envía cuando se introduce el nodo "Transferir a agente". Puede obtener más información sobre la carga de la actividad de transferencia.

Desencadenar un mensaje de bienvenida

Si desea que su copiloto envíe automáticamente el tema del saludo del sistema cuando un usuario inicia una conversación, puede enviar una actividad con Type=event y Name=startConversation.

Compartir vía