Publier un assistant dans les applications mobiles ou personnalisées

Vous pouvez connecter votre assistant à une application personnalisée afin que les utilisateurs de l’application puissent interagir avec l’assistant directement depuis votre application.

Dans la plupart des cas, votre application personnalisée est une application mobile qui est une application web ou une application native. Il peut également s’agir d’un adaptateur à d’autres services dont votre entreprise a besoin.

Différentes procédures existent pour la connexion à votre application mobile, selon que votre application est une application web ou une application native.

La connexion de votre assistant à une application web est relativement simple car elle implique de copier un extrait de code dans votre application. Cependant, les applications web et les applications natives ou personnalisées nécessitent toujours une expertise considérable des développeurs pour intégrer pleinement l’assistant dans votre application. Cet article décrit les deux procédures.

Prerequisites

• SDK .NET Core version 2.1.
• Package NuGet Microsoft.Bot.Connector.DirectLine.
• Un assistant créé dans Copilot Studio que vous souhaitez connecter à votre application.

Connecter votre assistant à une application web

1. Dans Copilot Studio, dans le menu de navigation, sélectionnez Canaux.

2. Sélectionnez la vignette Application mobile pour ouvrir la fenêtre de configuration.

3. Copiez le code sous la section Applications Web et fournissez-le aux développeurs de votre application pour qu’ils l’ajoutent à votre application Web.

   

Connecter votre assistant à une application native ou personnalisée

Si vous souhaitez vous connecter à des canaux Azure Bot Service, consultez Publier un agent sur Azure Bot Service canaux.

Références

Les instructions de ce document font référence au support source suivant :

• API Bot Framework Direct Line
• Authentification de Direct Line
• Variables contextuelles disponibles lors du transfert
• Activité de Microsoft Bot Framework

Récupérer les paramètres de votre assistant Copilot Studio

Pour vous connecter à l’agent que vous avez créé, récupérez le nom et le point de terminaison de jeton de votre agent pour l’identifier.

1. Dans Copilot Studio, accédez à la page Overview de votre agent et copiez le nom de votre agent.

2. Sélectionnez Canaux>Application mobile.

3. Sur la page Application mobile, en regard de Point de terminaison du jeton, sélectionnez Copier. Vous avez besoin de ce point de terminaison pour passer à l’étape Obtenir un jeton Direct Line.

   

Obtenir un jeton Direct Line

Pour entamer une conversation avec votre assistant, vous avez besoin d’un jeton Direct Line. Obtenez ce jeton en envoyant une requête GET au point de terminaison affiché dans l’écran Copilot Studio. Utilisez ce jeton comme en-tête pour les appels suivants à l’API de ligne directe.

Exemple :

GET <BOT TOKEN ENDPOINT>

Si la requête aboutit, le point de terminaison renvoie un jeton Direct Line, une date d’expiration et un conversationId pour l’assistant demandé.

Exemple :

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

Obtenir un exemple de code de jeton Direct Line

L’exemple suivant obtient un jeton Direct Line pour un agent 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; }
}

L’objet de réponse est identique à la GET requête que vous avez vue précédemment.

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

Utiliser Direct Line pour communiquer avec l’assistant

Après avoir récupéré le jeton Direct Line, vous êtes prêt à avoir une conversation avec votre agent Copilot Studio à l'aide de Direct Line. Pour lancer une conversation et envoyer et recevoir des messages, suivez les instructions de Bot Framework Direct Line API.

L’exemple suivant démarre une conversation et envoie et reçoit des messages d’un assistant Copilot Studio.

1. Initialisez une instance DirectLineClient avec le jeton Direct Line et démarrez une conversation :

      // 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. Une fois démarré, vous pouvez identifier et vous connecter à chaque conversation à l’aide de la combinaison de token et conversationtId. Envoyer un message utilisateur à une conversation existante :

      // 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. Récupérez la réponse de l’agent à l’aide des mêmes token et conversationId. Les activités de réponse Direct Line récupérées contiennent les messages de l’utilisateur et de l’assistant. Vous pouvez filtrer les activités de réponse en fonction du nom de votre assistant pour n’obtenir que le message de réponse de l’assistant.

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

Actualiser un jeton Direct Line

Vous devrez peut-être ajouter du code pour actualiser le jeton Direct Line si votre application a une longue conversation avec l’assistant. Le jeton expire, mais peut être actualisé avant son expiration. Pour plus d’informations, consultez Direct Line Authentication.

L’exemple suivant actualise le jeton pour une conversation Copilot Studio existante :

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

Analyser la charge utile de la conversation à partir de l’assistant

Après avoir démarré une conversation avec l’assistant, la charge utile JSON de conversation utilise l'activité standard Direct Line du Microsoft Bot Framework. Pour plus d’informations, consultez Bot Framework Direct Line API.

Gérer l’activité de transfert

Si votre application doit transférer l'interaction à un agent en direct, vous devez gérer l'activité de transfert. L’activité de transfert est envoyée lorsque le nœud Transfert vers l’agent est atteint. Vous pouvez en savoir plus sur la charge utile de l’activité de transfert.

Déclencher un message d’accueil

Pour que votre agent envoie automatiquement le sujet du système d’accueil lorsqu’un utilisateur démarre une conversation, envoyez une activité avec Type=event et Name=startConversation.