Ajout d’un bot à une application de conversation

Découvrez comment créer des expériences d’intelligence artificielle conversationnelle dans notre application de conversation en utilisant le canal de messagerie Azure Communication Services – Conversation disponible dans Azure Bot Service. Dans ce guide de démarrage rapide, vous créez un bot à l’aide du Kit de développement logiciel (SDK) BotFramework. Ensuite, intégrez le bot dans une application de conversation que vous créez à l’aide du Kit de développement logiciel (SDK) Communication Services Chat.

Cet article décrit les opérations suivantes :

• Créer et déployer un bot dans Azure
• Obtenez une ressource des Services de communication
• Activer le canal Conversation de Communication Services pour le bot
• Créer une application de conversation et ajouter le bot aux participants
• Explorer davantage de fonctionnalités pour votre bot

Prérequis

• Un compte et un abonnement Azure actifs. Créez un compte gratuitement.
• Visual Studio 2019 ou ultérieur.
• La dernière version de .NET Core. Dans ce guide de démarrage rapide, nous utilisons .NET Core 3.1. Veillez à installer la version qui correspond à votre instance de Visual Studio, 32 bits ou 64 bits.
• Kit de développement logiciel (SDK) Bot Framework

Créer et déployer un bot dans Azure

Pour utiliser la conversation Azure Communication Services comme canal dans Azure Bot Service, déployez d’abord un bot. Pour déployer un bot, procédez comme suit :

• Créer une ressource d’Azure Bot Service
• Obtenir l’ID d’application et le mot de passe du bot
• Créer une application web pour contenir la logique du bot
• Créer un point de terminaison de messagerie pour le bot

Créer une ressource d’Azure Bot Service

Tout d’abord, créez une ressource Azure Bot Service dans le portail Azure. Le canal Communication Services Chat prend en charge les bots monolocataires , les bots d’identité managée et les bots multilocataires. Cet exemple utilise un bot multi-locataire.

Pour configurer un bot à locataire unique ou d’identité managée, passez en revue les informations d’identité du bot.

Pour un bot d’identité managée, vous devrez peut-être mettre à jour l’identité du service de bot.

Obtenir l’ID d’application et le mot de passe d’application du bot

Ensuite, obtenez l’ID et le mot de passe de l’application Microsoft qui sont affectés à votre bot lors du déploiement. Vous utilisez ces valeurs pour les configurations ultérieures.

Créer une application web pour contenir la logique du bot

Pour créer une application web pour votre bot, vous pouvez réviser des exemples Bot Builder pour votre scénario ou utiliser le Kit de développement logiciel (SDK) Bot Builder pour créer une application web. L’un des exemples les plus simples est Echo Bot.

Azure Bot Service s’attend généralement à ce que le contrôleur de l’application web du bot expose un point de terminaison dans le formulaire /api/messages. Le point de terminaison gère tous les messages envoyés au bot.

Pour créer l’application bot, utilisez Azure CLI pour créer une ressource Azure App Service ou créer l’application dans le portail Azure.

Pour créer une application web de bot à l’aide du Portail Azure :

1. Dans le portail, sélectionnez Créer une ressource. Dans la zone de recherche, entrez application web. Sélectionnez la vignette Application web.

   

2. Dans Créer une application web, sélectionnez ou entrez les détails de l’application, y compris la région dans laquelle vous souhaitez déployer l’application.

   

3. Sélectionnez Réviser + Créer pour valider le déploiement et passer en revue les détails du déploiement. Sélectionnez ensuite Create (Créer).

4. Lorsque la ressource d’application web est créée, copiez l’URL du nom d’hôte affichée dans les détails de la ressource. L’URL fait partie du point de terminaison que vous créez pour l’application web.

   

Créer un point de terminaison de messagerie pour le bot

Ensuite, dans la ressource de bot, créez un point d'accès de messagerie pour application web.

1. Dans le portail Azure, accédez à votre ressource Azure Bot. Dans le menu Ressource, sélectionnez Configuration.

2. Dans Configuration, pour Point de terminaison de messagerie, collez l’URL du nom d’hôte de l’application web que vous avez copiée dans la section précédente. Ajoutez /api/messages à l'URL.

3. Sélectionnez Enregistrer.

Déployer l’application web

La dernière étape pour créer un bot consiste à déployer l’application web. Pour ce démarrage rapide, utilisez l’exemple Echo Bot. La fonctionnalité Echo Bot se limite à l’écho de l’entrée utilisateur. Voici comment le déployer sur votre application web dans Azure :

1. Utilisez Git pour cloner ce référentiel GitHub :

   git clone https://github.com/Microsoft/BotBuilder-Samples.git
   cd BotBuilder-Samples
   

2. Dans Visual Studio, ouvrez le projet Echo Bot.

3. Dans le projet Visual Studio, ouvrez le fichier Appsettings.json. Collez l’ID d’application Microsoft et le mot de passe d’application que vous avez copiés précédemment :

      {
        "MicrosoftAppId": "<App-registration-ID>",
        "MicrosoftAppPassword": "<App-password>"
      }
   

   Ensuite, utilisez Visual Studio pour les bots C# pour déployer le bot.

   Vous pouvez également utiliser une fenêtre d’invite de commandes pour déployer un bot Azure.

4. Dans Visual Studio, dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet EchoBot, puis sélectionnez Publier :

   

5. Sélectionnez Nouveau pour créer un profil de publication. Pour Cible, sélectionnez Azure :

   

   Pour la cible spécifique, sélectionnez Azure App Service :

   

6. Dans la configuration du déploiement, sélectionnez l’application web dans les résultats qui s’affichent une fois que vous vous êtes connecté à votre compte Azure. Pour terminer le profil, sélectionnez Terminer, puis sélectionnez Publier pour lancer le déploiement.

   

Obtenir une ressource des services de communication

Maintenant que votre bot est créé et déployé, créez une ressource Communication Services à utiliser pour configurer un canal Communication Services :

1. Effectuez les étapes pourcréer une ressource Communication Services.

2. Créez un utilisateur Communication Services et émettez un jeton d’accès utilisateur. Veillez à définir l’étendue sur conversation. Copiez la chaîne de jeton et la chaîne d’ID utilisateur.

Activer le canal de conversation des services de communication

Lorsque vous disposez d’une ressource Communication Services, vous pouvez configurer un canal Communication Services dans la ressource de bot. Dans ce processus, un ID utilisateur est généré pour le bot.

1. Dans le portail Azure, accédez à votre ressource Azure Bot. Dans le menu de ressources, sélectionnez Canaux. Dans la liste des canaux disponibles, sélectionnez Azure Communications Services - Conversation.

   

2. Sélectionnez Se connecter pour afficher la liste des ressources Communication Services disponibles dans votre abonnement.

   

3. Dans le volet Nouvelle connexion, sélectionnez la ressource de conversation Communication Services, puis sélectionnez Appliquer.

   

4. Lorsque les détails de la ressource sont vérifiés, un ID de bot s’affiche dans la colonne ID Azure Communication Services du bot. Vous pouvez utiliser l’ID de bot pour représenter le bot dans un fil de conversation à l’aide de l’API AddParticipant de conversation Communication Services. Une fois que vous avez ajouté le bot à une conversation en tant que participant, le bot commence à recevoir des activités liées à la conversation, et il peut répondre dans le fil de conversation.

   

Créer une application de conversation et ajouter le bot aux participants

Maintenant que vous disposez de l’ID Communication Services du bot, vous pouvez créer un fil de conversation qui compte le bot parmi les participants.

Créer une application C#

1. Exécutez la commande suivante pour créer une application C# :

   dotnet new console -o ChatQuickstart
   

2. Remplacez votre répertoire par le nouveau dossier d’application et utilisez la dotnet build commande pour compiler votre application :

   cd ChatQuickstart
   dotnet build
   

Installer le package

Installez le Kit de développement logiciel (SDK) Communication Services Chat pour .NET :

dotnet add package Azure.Communication.Chat

Créer un client de conversation

Pour créer un client de conversation, utilisez votre point de terminaison Communication Services et le jeton d’accès utilisateur que vous avez généré précédemment. Utilisez la CommunicationIdentityClient classe du Kit de développement logiciel (SDK) Identity pour créer un utilisateur et émettre un jeton pour passer à votre client de conversation. Les jetons d’accès peuvent être générés dans le portail à l’aide des instructions suivantes.

Copiez le code suivant et collez-le dans le fichier source Program.cs :

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Communication Services endpoint
            Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

Démarrer un thread de conversation avec le bot

Utilisez la méthode createChatThread sur chatClient pour créer un thread de conversation. Remplacez l’ID par l’ID Communication Services du bot.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
    DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Obtenir un client de fil de conversation

La GetChatThreadClient méthode retourne un client de thread pour un thread qui existe déjà :

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Envoyer un message à un fil de conversation

SendMessage Pour envoyer un message à un thread :

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Recevoir les messages de conversation d’un fil de conversation

Vous pouvez obtenir des messages de conversation en interrogeant la GetMessages méthode sur le client de thread de conversation à intervalles définis :

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

Vérifiez la liste des messages pour la réponse d’écho du bot à Hello World.

Vous pouvez utiliser JavaScript ou les sdk mobiles Azure pour vous abonner aux notifications de messages entrantes :

// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Your code here
});

Nettoyer le fil de conversation

Une fois que vous avez terminé d’utiliser le thread de conversation, supprimez le thread :

chatClient.DeleteChatThread(threadId);

Déployer l’application de conversation C#

Pour déployer l’application de conversation :

1. Dans Visual Studio, ouvrez le projet de conversation.

2. Cliquez avec le bouton droit sur le projet ChatQuickstart , puis sélectionnez Publier :

   

3. Une fois que vous avez publié la solution, exécutez-la et vérifiez si echo bot fait écho au message utilisateur à l’invite de commandes. Maintenant que vous disposez de la solution, vous pouvez continuer à jouer avec les différentes activités nécessaires pour les scénarios métier que vous devrez peut-être résoudre.

Autres possibilités offertes par les bots

Un bot peut recevoir plus qu’un message en texte brut d’un utilisateur dans un canal de conversation Communications Services. Voici quelques-unes des activités qu’un bot peut recevoir d’un utilisateur :

• Mise à jour de conversation
• Mise à jour de message
• Suppression de message
• Indicateur de saisie
• Activité d’événement
• Diverses pièces jointes, y compris les cartes adaptatives
• Données de canal de bot

Les sections suivantes présentent des exemples pour illustrer ces fonctionnalités.

Envoi d’un message d’accueil lorsqu’un nouvel utilisateur est ajouté au thread

La logique actuelle d’Echo Bot accepte l’entrée de l’utilisateur et la renvoie. Si vous souhaitez ajouter une logique supplémentaire (par exemple la réponse à un événement Communication Services ajouté par un participant), copiez le code suivant et collez-le dans le fichier source EchoBot.cs :

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples.Bots
{
    public class EchoBot : ActivityHandler
    {
        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        {
            if (turnContext.Activity.Type == ActivityTypes.Message)
            {
                var replyText = $"Echo: {turnContext.Activity.Text}";
                await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
            }
            else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
            {
                if (turnContext.Activity.MembersAdded != null)
                {
                    foreach (var member in turnContext.Activity.MembersAdded)
                    {
                        if (member.Id != turnContext.Activity.Recipient.Id)
                        {
                            await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
                        }
                    }
                }
            }
        }
    }
}

Envoi d’une carte adaptative

Remarque

Les cartes adaptatives ne sont prises en charge que dans les cas d’usage d’Azure Communication Services où tous les participants à la conversation sont des utilisateurs d’Azure Communication Services, et non pour les cas d’utilisation de l’interopérabilité Teams.

Vous pouvez envoyer une carte adaptative au fil de conversation pour augmenter l’engagement et l’efficacité. Une carte adaptative vous permet également de communiquer avec les utilisateurs de différentes façons. Vous pouvez envoyer une carte adaptative à partir d’un bot en ajoutant la carte en tant que pièce jointe d’activité de bot.

Voici un exemple d’envoi d’une carte adaptative :

var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
    ContentType = "application/vnd.microsoft.card.adaptive",
    Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);   
await turnContext.SendActivityAsync(reply, cancellationToken);             

Trouvez des exemples de charges utiles pour les cartes adaptatives dans Exemples et modèles.

Pour un utilisateur de conversation, le canal de conversation Communication Services ajoute un champ aux métadonnées du message qui indique que le message a une pièce jointe. Dans les métadonnées, la propriété de microsoft.azure.communication.chat.bot.contenttype est définie sur azurebotservice.adaptivecard.

Voici un exemple de message de conversation auquel une carte adaptative est jointe :

{
    "content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
    "senderDisplayName": "BotDisplayName",
    "metadata": {
    "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
    },
 "messageType": "Text"
}

Envoyer un message d’utilisateur à bot

Vous pouvez envoyer un message texte basique de l’utilisateur au bot de la même façon que vous envoyez un message texte à un autre utilisateur.

Toutefois, pendant l’envoi d’un message contenant une pièce jointe entre un utilisateur et un bot, ajoutez cet indicateur aux métadonnées de conversation Communication Services :

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"

Pour envoyer une activité d’événement d’un utilisateur à un bot, ajoutez cet indicateur aux métadonnées de conversation Communication Services :

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"

Les sections suivantes présentent des exemples de formats pour les messages de conversation d’un utilisateur vers un bot.

Envoyer un message texte simple

{
    "content":"Simple text message",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{
        "text":"random text",
        "key1":"value1",
        "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n
        "}, 
    "messageType": "Text"
}

Message avec une pièce jointe

{
    "content": "{
                        \"text\":\"sample text\", 
                        \"attachments\": [{
                            \"contentType\":\"application/vnd.microsoft.card.adaptive\",
                            \"content\": { \"*adaptive card payload*\" }
                        }]
        }",
    "senderDisplayName": "Acs-Dev-Bot",
    "metadata": {
        "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
        "text": "random text",
        "key1": "value1",
        "key2": "{\r\n  \"subkey1\": \"subValue1\"\r\n}"
    },
        "messageType": "Text"
}

Message avec une activité d’événement

Une charge utile d’événement inclut tous les champs JSON dans le contenu du message, à l’exception de Name. Le champ Name contient le nom de l’événement.

Dans l’exemple suivant, le nom de l’événement endOfConversation avec la charge utile "{field1":"value1", "field2": { "nestedField":"nestedValue" }} est envoyé au bot :

{
    "content":"{
                   \"name\":\"endOfConversation\",
                   \"field1\":\"value1\",
                   \"field2\": {  
                       \"nestedField\":\"nestedValue\"
                    }
               }",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{  
                   "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
                   "text":"random text",
                   "key1":"value1",
                   "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n}"
               },
    "messageType": "Text"
}

Le champ microsoft.azure.communication.chat.bot.contenttype de métadonnées est requis uniquement dans un message envoyé d’un utilisateur à un bot.

Champs pris en charge pour l'activité des bots

Les sections suivantes décrivent les champs d’activité de bot pris en charge pour les flux de bot à utilisateur et d’utilisateur à bot.

Flux de bot à utilisateur

Les champs d’activité de bot suivants sont pris en charge pour les flux de bot à utilisateur.

Activités

• Message
• Saisie

Champs d’activité de message

• Text
• Attachments
• AttachmentLayout
• SuggestedActions
• From.Name (Converti en Communication Services SenderDisplayName.)
• ChannelData (Converti en Communication Services Chat Metadata. Si des valeurs de mappage ChannelData sont des objets, elles sont sérialisées au format JSON et envoyées sous forme de chaîne.)

Flux d’utilisateur à bot

Ces champs d’activité de bot sont pris en charge pour les flux d’utilisateur à bot.

Activités et champs

• Message

  • Id (ID de message du chat Communication Services)
  • TimeStamp
  • Text
  • Attachments

• Mise à jour de conversation

  • MembersAdded
  • MembersRemoved
  • TopicName

• Mise à jour de message

  • Id (ID de message de conversation Communication Services mis à jour)
  • Text
  • Attachments

• Suppression de message

  • Id (ID de message de chat des services de communication supprimé)

• Événement

  • Name
  • Value

• Saisie

Autres champs communs

• Recipient.Id et Recipient.Name (ID d’utilisateur et nom d’affichage du chat des services de communication)
• From.Id et From.Name (ID d’utilisateur et nom d’affichage du chat des services de communication)
• Conversation.Id (Identifiant de fil de conversation des services de communication)
• ChannelId (conversation avec Communication Services si vide)
• ChannelData (métadonnées de message de chat des Services de Communication)

Modèles de transfert de bot

Parfois, un bot ne comprend pas une question ou ne peut pas répondre à une question. Un client peut demander dans la conversation à être mis en relation avec un agent humain. Dans ces scénarios, le fil de conversation doit être transféré du bot à un agent humain. Vous pouvez concevoir votre application pour faire passer la conversation d’un bot à un humain.

Gérer la communication de bot à bot

Dans certains cas d’usage, deux bots doivent être ajoutés au même fil de conversation pour fournir des services différents. Dans ce scénario, vous devrez peut-être vous assurer qu’un bot n’envoie pas de réponses automatisées aux messages d’un autre bot. Si elle n’est pas gérée correctement, l’interaction automatisée des bots entre eux peut entraîner une boucle infinie de messages.

Vous pouvez vérifier l’identité de l’utilisateur Communication Services d’un expéditeur de message dans la propriété From.Id de l’activité. Vérifiez s’il appartient à un autre bot. Ensuite, effectuez l’action requise pour empêcher un flux de communication bot à bot. Si ce type de scénario entraîne des volumes d’appels élevés, le canal de conversation Communication Services limite les demandes et un bot ne peut pas envoyer et recevoir des messages.

En savoir plus sur les limites de l’accélérateur.

Dépanner

Les sections suivantes décrivent les différentes façons de résoudre les scénarios courants.

Impossible d’ajouter le canal de conversation

Dans le portail des développeurs Microsoft Bot Framework, accédez à Configuration>Bot Messaging pour vérifier que le point de terminaison est correctement défini.

Le bot obtient une exception d’interdiction lors de la réponse à un message

Vérifiez que l’ID et le mot de passe de l’application Microsoft du bot sont correctement enregistrés dans le fichier de configuration du bot que vous chargez dans l’application web.

Le bot ne peut pas être ajouté comme participant

Vérifiez que l’ID Communication Services du bot est utilisé correctement pendant l’envoi d’une demande d’ajout de bot à un fil de conversation.

Étapes suivantes

Essayez l’application de démonstration de bot de conversation pour une conversation 1:1 entre un utilisateur de conversation et un bot via le composant d’interface utilisateur BotFramework WebChat.

Articles connexes

Pour plus d’informations sur l’ajout d’un bot OpenAI, consultez Intégrer un bot OpenAI avec conversation.