Créer des extensions de message à l’aide de Bot Framework

Les extensions de message créées à l’aide de Bot Framework (basé sur un bot) utilisent un service web en tant que bot. Vous pouvez utiliser des extensions de message pour permettre aux utilisateurs d’interagir avec votre service web à partir de différents emplacements dans le client Teams, tels que la zone de rédaction de message, la zone de commande, ou directement à partir d’un message et de renvoyer des données structurées, telles que des cartes.

L’extension de message basé sur un bot tire parti du schéma de messagerie et du protocole de communication sécurisé de Bot Framework. Le bot est défini dans le manifeste de l’application pour l’application Teams et vous pouvez également définir différents types de commandes pour votre extension de message, tels que les commandes d’action ou les commandes de recherche.

Il existe deux types de commandes d’extension de message, la commande d’action et la commande de recherche. Le type de commande d’extension de message définit les éléments d’interface utilisateur et les flux d’interaction disponibles pour votre service web. Vous pouvez utiliser une commande de recherche ou une commande d’action pour interagir avec votre service web via un bot dans Teams.

Commandes de recherche

Les commandes de recherche d’extension de message permettent aux utilisateurs de rechercher des systèmes externes et d’insérer les résultats de cette recherche dans un message sous la forme d’un carte. Ce document vous guide sur la sélection des emplacements d’appel de commandes de recherche et l’ajout de la commande de recherche au manifeste de votre application.

Remarque

Le résultat carte limite de taille est de 28 Ko. Le carte n’est pas envoyé si sa taille dépasse 28 Ko.

Pour savoir comment définir des commandes de recherche d’extension de message, consultez la vidéo suivante :

La commande de recherche dans une extension de message est configurée à l’aide de la composeExtensions.commands propriété et du query type dans le manifeste de l’application (précédemment appelé manifeste d’application Teams). Les descriptions des commandes et des paramètres améliorent la facilité d’utilisation et l’efficacité d’une extension de message. Une bonne description de commande offre un résumé clair et concis des fonctionnalités de l’application.

Le code suivant est un exemple de propriété composeExtensions définissant une commande de recherche :

{
 "composeExtensions": [
    {
      "botId": "eccdf132-0900-4d36-936b-dec5e6357f11",
      "commands": [
        {
          "id": "Dev",
          "type": "query",
          "title": "Jedi",
          "description": "May the force be with you",
          "initialRun": true,
          "fetchTask": false,
          "context": [
            "commandBox",
            "compose",
            "message"
          ],
          "parameters": [
            {
              "name": "Luke",
              "title": "Skywalker",
              "description": "Jedi master",
              "inputType": "text"
            }
          ]
        }
      ],
      "canUpdateConfiguration": true
    }
  ],

Paramètres

Vous devez ajouter les paramètres suivants à votre composeExtensions.commands tableau d’objets :

Nom de la propriété	Objectif	Obligatoire ?	Version du manifeste
id	ID unique que vous affectez à la commande de recherche. La demande de l’utilisateur inclut cet ID.	Oui	1.0
title	Nom de la commande. Cette valeur apparaît dans l’interface utilisateur.	Oui	1.0
description	Texte d’aide indiquant l’action de cette commande. Cette valeur apparaît dans l’interface utilisateur.	Oui	1.0
semanticDescription	Description sémantique de la commande pour la consommation par les modèles de langage volumineux (LLM).	Non	1.17
type	Type de commande. La valeur par défaut est query.	Non	1.4
initialRun	Si cette propriété a la valeur true, cela indique que cette commande doit être exécutée dès que l’utilisateur sélectionne cette commande dans l’interface utilisateur.	Non	1.0
context	Tableau facultatif de valeurs qui définit le contexte dans lequel l’action de recherche est disponible. Les valeurs possibles sont message, compose ou commandBox. La valeur par défaut est compose,commandBox.	Non	1,5

Vous devez ajouter les détails des paramètres de recherche suivants qui définissent le texte visible par votre utilisateur dans le client Teams :

Nom de la propriété	Objectif	Est-ce obligatoire ?	Version minimale du manifeste
parameters	Définit une liste statique de paramètres pour la commande .	Non	1.0
parameter.name	Décrit le nom du paramètre. est parameter.name envoyé à votre service dans la demande de l’utilisateur.	Oui	1.0
parameter.description	Décrit les objectifs du paramètre ou l’exemple de la valeur qui doit être fournie. Cette valeur apparaît dans l’interface utilisateur.	Oui	1.0
parameter.semanticDescription	Description sémantique du paramètre pour la consommation par les grands modèles de langage (LLM).	Non	1.17
parameter.title	Titre ou étiquette court du paramètre convivial.	Oui	1.0
parameter.inputType	Définissez sur le type de l’entrée requise. Les valeurs possibles incluent text, textarea, number, date, time, toggle. La valeur par défaut est définie sur text.	Non	1.4
parameters.value	Valeur initiale du paramètre. La valeur n’est pas prise en charge	Non	1,5

Pour plus d’informations, consultez Schéma de manifeste d’application.

Étape suivante

Définir la commande de recherche d’extension de message

Commandes d’action

Remarque

Lorsqu’une action de message est lancée, les détails de la pièce jointe ne sont pas envoyés dans le cadre de l’activité d’appel turncontext .

Les commandes d’action vous permettent de présenter à vos utilisateurs une fenêtre contextuelle modale appelée module de tâche dans Teams. Le module de tâche collecte ou affiche des informations, traite l’interaction et les renvoie à Teams. Ce document vous guide sur la façon de sélectionner des emplacements d’appel de commande d’action, de créer votre module de tâche, d’envoyer un message final ou une carte, de créer une commande d’action à l’aide d’App Studio ou de le créer manuellement.

La commande d’action dans une extension de message est configurée à l’aide de la composeExtensions.commands propriété et action tapez dans le manifeste de l’application.

Le code suivant est un exemple de propriété composeExtensions définissant une commande d’action :

"composeExtensions": [
        {
            "botId": "xxxxxx-xxx-bot-ID-xxxxxxxx}",
            "commands": [
                {
                    "id": "createCard",
                    "context": [
                        "compose",
                        "message",
                        "commandBox"
                    ],
                    "description": "Command to run action to create a Card from Compose Box",
                    "title": "Create Card",
                    "type": "action",
                    "parameters": [
                        {
                            "name": "title",
                            "title": "Card title",
                            "description": "Title for the card",
                            "inputType": "text"
                        },
                        {
                            "name": "subTitle",
                            "title": "Subtitle",
                            "description": "Subtitle for the card",
                            "inputType": "text"
                        },
                        {
                            "name": "text",
                            "title": "Text",
                            "description": "Text for the card",
                            "inputType": "textarea"
                        }
                    ]
                }
            ]
        }
    ]

Paramètres

Vous devez ajouter les paramètres suivants à votre composeExtensions.commands tableau d’objets :

Nom de la propriété	Objectif	Obligatoire ?	Version du manifeste
id	ID unique que vous affectez à cette commande. La demande de l’utilisateur inclut cet ID.	Oui	1.0
title	Nom de la commande. Cette valeur apparaît dans l’interface utilisateur.	Oui	1.0
type	Type d’extension de message. La valeur par défaut est action.	Non	1.4
fetchTask	Définissez sur true pour une carte adaptative ou une vue web incorporée pour votre module de tâche, etfalse pour une liste statique de paramètres ou lors du chargement de la vue web par un taskInfo.	Non	1.4
context	Tableau facultatif de valeurs qui définit l’emplacement d’appel de l’extension de message. Les valeurs possibles sont message, compose ou commandBox. La valeur par défaut est ["compose", "commandBox"].	Non	1,5

Si vous utilisez une liste statique de paramètres, vous devez également ajouter les paramètres suivants :

Nom de la propriété	Objectif	Est-ce obligatoire ?	Version minimale du manifeste
parameters	Décrit la liste statique des paramètres de la commande . Utilisez uniquement lorsque fetchTask est false.	Non	1.0
parameter.name	Décrit le nom du paramètre. Il est envoyé à votre service dans la demande de l’utilisateur.	Oui	1.0
parameter.description	Décrit les objectifs du paramètre ou l’exemple de la valeur à fournir. Cette valeur apparaît dans l’interface utilisateur.	Oui	1.0
parameter.title	Titre ou étiquette court du paramètre convivial.	Oui	1.0
parameter.inputType	Définissez sur le type d’entrée requis. Les valeurs possibles incluent text, textarea, number, date, time, toggle. La valeur par défaut est définie sur text.	Non	1.4

Si vous utilisez une vue web incorporée, vous pouvez éventuellement ajouter l’objet taskInfo pour extraire votre vue web sans appeler directement votre bot. Si vous sélectionnez cette option, le comportement est similaire à celui de l’utilisation d’une liste statique de paramètres. Dans la mesure où la première interaction avec votre bot est réponse au module de tâche envoyer l’action. Si vous utilisez un taskInfo objet, vous devez définir le paramètre sur fetchTaskfalse.

Nom de la propriété	Objectif	Est-ce obligatoire ?	Version minimale du manifeste
taskInfo	Spécifiez le module de tâche à précharger lors de l’utilisation d’une commande d’extension de message.	Non	1.4
taskInfo.title	Titre initial du module de tâche.	Non	1.4
taskInfo.width	Largeur du module de tâche, un nombre en pixels ou une disposition par défaut telle que large, mediumou small.	Non	1.4
taskInfo.height	Hauteur du module de tâche, un nombre en pixels ou une disposition par défaut telle que large, mediumou small.	Non	1.4
taskInfo.url	URL de la vue web initiale.	Non	1.4

Pour plus d’informations, consultez Schéma de manifeste d’application.

Étape suivante

Définir des commandes d’action d’extension de message

Voir aussi

• Actions universelles pour les extensions de message basées sur la recherche
• Extension de message basée sur l’API