Publier un assistant dans les applications mobiles ou personnalisées

2025-07-01

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 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 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. Les deux procédures sont décrites dans cet article.

Prérequis

kit 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

Dans Copilot Studio, dans le menu de navigation, sélectionnez Canaux.
Sélectionnez la vignette Application mobile pour ouvrir la fenêtre de configuration.
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

Astuce

Bien que cette section explique comment se connecter à une application mobile, le même processus peut être appliqué aux applications personnalisées ou natives, telles que les applications IoT (Internet des objets).

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 rubrique Publier un assistant dans les canaux Azure Bot Service.

Important

Les instructions de cette section nécessitent un développement logiciel de votre part ou de la part de vos développeurs. Elles sont destinées aux professionnels de l’informatique expérimentés, tels que les administrateurs informatiques ou les développeurs qui ont une solide compréhension des outils de développement, des utilitaires et des IDE.

Références

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

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

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

Dans Copilot Studio, accédez à la page Vue d’ensemble de votre assistant et copiez le nom de votre assistant.
Sélectionnez Canaux>Application mobile.
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. 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, le délai d’expiration et un conversationId pour l’assistant demandé seront renvoyés.

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 le même que la requête GET que nous avons 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 assistant Copilot Studio avec 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 agent Copilot Studio.

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

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

Récupérez la réponse de l’assistant en utilisant les 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 ; vous trouverez plus d’informations dans Authentification Direct Line.

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 de conversation JSON utilise l’activité Microsoft Bot Framework Direct Line standard. Vous trouverez plus d’informations sur Bot Framework Direct Line API.

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’assistant » 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 assistant 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.