Publier un copilote dans les applications mobiles et personnalisées

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

Dans la plupart des cas, votre application personnalisée est une application pour appareil mobile qui est soit une application Web, soit une application native ou un adaptateur à d’autres services dont votre entreprise a besoin.

Il existe différentes procédures pour se connecter à votre application mobile, selon que votre application est une application Web ou une application native.

La connexion de votre copilote à une application Web est relativement simple, car elle implique la copie d’un extrait de code dans votre application. Cependant, les applications Web et les applications natives ou personnalisées nécessitent toujours un considérable travail de développeur pour intégrer pleinement le copilote dans votre application. Les deux procédures sont décrites dans cet article.

Conditions préalables

• Kit de développement logiciel .NET Core version 2.1.
• Package Nuget Microsoft.Bot.Connector.DirectLine.
• Copilote créé dans Copilot Studio que vous souhaitez connecter à votre application.

Connecter votre copilote à une application Web

1. Dans Copilot Studio, dans le menu de navigation, Sélectionner Chaînes.

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 copilote à une application native ou personnalisée

Si votre objectif est de vous connecter aux canaux Azure Bot Service, en plus de suivre les instructions présentées ici, vos développeurs peuvent en savoir plus dans la section Publier un copilote sur les canaux Azure Bot Service.

Exemples de code

Les extraits de code utilisés dans ce document proviennent de :

• Exemple de code de connecteur

Références

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

• Bot Framework Direct Line API
• Direct Line Authentification
• Variables de contexte disponibles sur transfert
• Microsoft Bot Framework Activité

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

Pour vous connecter au copilote que vous avez créé, vous devrez récupérer le nom de votre copilote et le point de terminaison du jeton pour l’identifier.

1. Dans Copilot Studio, accédez à la page Présentation de votre copilote et copiez le nom de votre copilote.

2. Sélectionner Chaînes>Application mobile.

3. Sur la page Application mobile , à côté de Jeton point de terminaison, Sélectionner Copier. Vous avez besoin de ce point de terminaison pour passer à l’étape Obtenir un jeton Direct Line.

   

Obtenir un jeton Direct Line

Pour démarrer une conversation avec votre copilote, vous avez besoin d’un jeton Direct Line. Ce jeton peut être obtenu en effectuant une requête GET au point de terminaison indiqué sur l’écran Copilot Studio. Ce jeton doit ensuite être utilisé comme en-tête pour les appels ultérieurs à l’API Directline.

Exemple :

GET <BOT TOKEN ENDPOINT>

Si la demande aboutit, un jeton Direct Line, un délai d’expiration et un ID conversationnel seront retournés pour le copilote demandé. Exemple :

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

Exemple de code

L’exemple suivant utilise des exemples de Code de connecteur pour obtenir un jeton Direct Line pour un copilote 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 réponse est le même que la requête que nous avons vue précédemment. GET

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

Utiliser Direct Line pour communiquer avec le copilote

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

L’exemple suivant utilise des échantillons de la section Exemple de code de connecteur pour démarrer une conversation et envoyer et recevoir des messages d’un copilote 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 commencée, chaque conversation peut être identifiée et jointe en utilisant 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 du copilote en utilisant les mêmes token et conversationId. Les activitésréponse récupérées contiennent à la fois les messages de l’utilisateur et du copilote. Direct Line Vous pouvez filtrer les activités de réponse par le nom de votre copilote pour n’obtenir que le message de réponse du copilote.

      // 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 le jeton Direct Line

Vous devrez peut-être ajouter du code pour actualiser le jeton si votre application a une longue conversation avec le copilote. Direct Line Le jeton expire, mais peut être actualisé avant son expiration ; en savoir plus sur Authentification Direct Line.

L’exemple suivant utilise des échantillons de la section Exemple de code de connecteur pour actualiser 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 conversation du copilote

Une fois que vous avez démarré une conversation avec le copilote, la charge utile JSON de la conversation utilise l’activité standard. Microsoft Bot Framework Direct Line Pour en savoir plus, voir API Bot Framework Direct Line.

Gérer l’activité de transfert

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

Déclencher un message d’accueil

Si vous souhaitez que votre copilote envoie automatiquement la rubrique système Bienvenue lorsqu’un utilisateur démarre une conversation, vous pouvez envoyer une activité avec Type=event et Name=startConversation.