Share via

Démarrage rapide : Ajout d’un bot à une application de conversation

  • Article

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, vous intégrez le bot à une application de conversation que vous créez à l’aide du Kit de développement logiciel (SDK) Communication Services Chat.

Dans ce guide de démarrage rapide, vous apprenez à :

Prérequis

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, utilisez le Portail Azure pour créer une ressource Azure Bot Service. Le canal de conversation Communication Services prend en charge les bots monolocataires, les bots d’identité managée et les bots multilocataires. Pour les besoins de ce démarrage rapide, nous allons utiliser un bot multilocataire.

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

Pour les bots 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 d’application et le mot de passe Microsoft qui sont attribués à votre bot lors de son 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 d’application web du bot pour exposer 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éez 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.

    Screenshot that shows creating a web app resource in the Azure portal.

  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.

    Screenshot that shows details to set to create a web app deployment.

  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 qui s’affiche dans les détails de la ressource. L’URL fait partie du point de terminaison que vous créez pour l’application web.

    Screenshot that shows how to copy the web app endpoint URL.

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

Ensuite, dans la ressource de bot, créez un point de terminaison de messagerie d’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 à l’URL avec /api/messages.

  3. Cliquez sur Enregistrer.

Screenshot that shows how to create a bot messaging endpoint by using the web app hostname.

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 les bots Visual Studio pour 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 :

    Screenshot that shows publishing your web app from Visual Studio.

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

    Screenshot that shows how to select Azure as target in a new publishing profile.

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

    Screenshot that shows how to select Azure App Service as the specific target.

  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.

    Screenshot that shows setting the deployment configuration with the web app name.

Obtenir une ressource Communication Services

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 Conversation de Communication Services

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.

    Screenshot that shows opening the Communication Services Chat channel.

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

    Screenshot that shows how to connect a Communication Service resource to the bot.

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

    Screenshot that shows how to save the selected Communication Service resource to create a new Communication Services user ID.

  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.

    Screenshot that shows the new Communication Services user ID assigned to the bot.

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. Utilisez la commande suivante pour créer l’application C# :

    dotnet new console -o ChatQuickstart

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

    cd ChatQuickstart
dotnet build

Installer le package

Installez le SDK Conversation Communication Services 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 ainsi que le jeton d’accès d’utilisateur que vous avez généré précédemment. Utilisez la classe CommunicationIdentityClient du kit de développement logiciel (SDK) Identity pour créer un utilisateur et émettre un jeton à transmettre à 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);
        }
    }
}

Lancement d’un thread de conversation avec le bot

Utilisez la méthode createChatThread sur chatClient pour créer un fil 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 méthode GetChatThreadClient retourne un client de fil pour un fil qui existe déjà :

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

Envoyer un message à un fil de conversation

Utiliser SendMessage pour envoyer un message à un fil de conversation :

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 recevoir les messages de conversation en interrogeant la méthode GetMessages sur le client de fil de conversation selon des 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 kits SDK mobiles Azure pour vous abonner aux notifications de messages entrants :

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

Lorsque vous avez terminé d’utiliser le fil de conversation, supprimez le fil :

chatClient.DeleteChatThread(threadId);

Déploiement de l’application de conversation en C#

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:

    Screenshot that shows deploying the chat application to Azure from Visual Studio.

  3. Une fois que vous avez publié la solution, exécutez-la et vérifiez si Echobot 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 avez besoin de 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 sont uniquement prises en charge dans les cas d’utilisation d’Azure Communication Services où tous les participants au chat sont des utilisateurs Azure Communication Services, et non pour les cas d’utilisation d’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 de métadonnées microsoft.azure.communication.chat.bot.contenttype est requis uniquement dans un message envoyé d’un utilisateur à un bot.

Champs d’activité de bot pris en charge

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 de conversation 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 conversation Communication Services supprimé)

  • Événement

    • Name
    • Value

  • Saisie

Autres champs communs

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

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>messagerie Bot pour vérifier que le point de terminaison a été 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 individuelle entre un utilisateur de conversation et un bot via le composant d’interface utilisateur BotFramework WebChat.