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

Important

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du SDK Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section Extensions de messagerie - V3 SDK dans le dossier Ressources de la documentation.

Les commandes d’action vous permettent de présenter à vos utilisateurs une fenêtre popup modale appelée module de tâche dans Teams. Le module de tâche collecte ou affiche des informations, traite l’interaction et renvoie les informations à Teams. Ce document vous guide sur la sélection d’emplacements d’appel de commande d’action, la création de votre module de tâche, l’envoi d’un message final ou d’une carte, la création d’une commande d’action à l’aide d’app studio ou sa création manuelle.

Avant de créer la commande d’action, vous devez déterminer les facteurs suivants :

  1. À partir d’où la commande d’action peut-elle être déclenchée ?
  2. Comment le module de tâche sera-t-il créé ?
  3. Le message final ou la carte sera-t-il envoyé au canal à partir d’un bot, ou le message ou la carte sera-t-il inséré dans la zone de composition du message à envoyer par l’utilisateur ?

Sélectionner des emplacements d’appel de commande d’action

Tout d’abord, vous devez déterminer l’emplacement à partir de lequel votre commande d’action doit être invoquée. En spécifiant le manifeste de votre application, votre commande peut être invoquée à partir d’un ou plusieurs context des emplacements suivants :

  • Zone de composition de message : boutons situés en bas de la zone composer un message.

  • Zone de commande : en @mentioning votre application dans la zone de commande.

    Notes

    Si l’extension de messagerie est invoquée à partir de la zone de commande, vous ne pouvez pas répondre par un message bot inséré directement dans la conversation.

  • Message : directement à partir d’un message existant via le ... menu de dépassement d’un message.

    Notes

    L’appel initial à votre bot inclut un objet JSON contenant le message à partir duquel il a été appelé. Vous pouvez traiter le message avant de le présenter avec un module de tâche.

L’image suivante affiche les emplacements d’où la commande d’action est invoquée :

emplacements d’appel de commande d’action

Sélectionnez comment créer votre module de tâche

En plus de sélectionner l’endroit à partir de lequel votre commande peut être invoquée, vous devez également sélectionner comment remplir le formulaire dans le module de tâche pour vos utilisateurs. Vous avez les trois options suivantes pour créer le formulaire qui est rendu à l’intérieur du module de tâche :

  • Liste statique de paramètres: il s’agit de la méthode la plus simple. Vous pouvez définir une liste de paramètres dans le manifeste de votre application que le client Teams rendu, mais ne peut pas contrôler la mise en forme dans ce cas.
  • Carte adaptative: vous pouvez choisir d’utiliser une carte adaptative, ce qui offre un meilleur contrôle sur l’interface utilisateur, mais vous limite aux contrôles disponibles et aux options de mise en forme.
  • Affichage web incorporé: vous pouvez choisir d’incorporer un affichage web personnalisé dans le module de tâche pour avoir un contrôle complet sur l’interface utilisateur et les contrôles.

Si vous choisissez de créer le module de tâche avec une liste statique de paramètres et lorsque l’utilisateur soumet le module de tâche, l’extension de messagerie est appelée. Lorsque vous utilisez une vue web incorporée ou une carte adaptative, votre extension de messagerie doit gérer un événement d’appel initial de l’utilisateur, créer le module de tâche et le renvoyer au client.

Sélectionner la façon dont le message final est envoyé

Dans la plupart des cas, la commande d’action entraîne l’insertion d’une carte dans la zone composer un message. L’utilisateur peut l’envoyer dans le canal ou la conversation. Dans ce cas, le message provient de l’utilisateur et le bot ne peut ni modifier ni mettre à jour la carte.

Si l’extension de messagerie est invoquée à partir de la zone de composition ou directement à partir d’un message, votre service web peut insérer la réponse finale directement dans le canal ou la conversation. Dans ce cas, la carte adaptative provient du bot, le bot la met à jour et répond au thread de conversation si nécessaire. Vous devez ajouter l’objet au manifeste de l’application en utilisant le même ID et en bot définissant les étendues appropriées.

Ajouter la commande d’action au manifeste de votre application

Pour ajouter la commande d’action au manifeste de l’application, vous devez ajouter un nouvel objet au niveau supérieur du composeExtension manifeste d’application JSON. Pour ce faire, vous pouvez utiliser l’une des méthodes suivantes :

Créer une commande d’action à l’aide d’App Studio

Vous pouvez créer une commande d’action à l’aide d’App Studio ou du portail du développeur.

Notes

App Studio sera bientôt supprimé. Configurez, distribuez et gérez vos applications Teams avec le nouveau portail du développeur.

Notes

La condition préalable à la création d’une commande d’action est que vous avez déjà créé une extension de messagerie. Pour plus d’informations sur la création d’une extension de messagerie, voir créer une extension de messagerie.

Pour créer une commande d’action

  1. Ouvrez App Studio à partir Microsoft Teams client et sélectionnez l’onglet Éditeur de manifeste.

  2. Si vous avez déjà créé votre package d’application dans App Studio, sélectionnez-le dans la liste. Si vous n’avez pas créé de package d’application, importez-en un existant.

  3. Après avoir importé un package d’application, sélectionnez les extensions de messagerie sous Fonctionnalités. Vous obtenez une fenêtre instantanée pour configurer l’extension de messagerie.

  4. Sélectionnez Configurer dans la fenêtre pour inclure l’extension de messagerie dans l’expérience de votre application. L’image suivante affiche la fenêtre de mise en place de l’extension de messagerie :

    messaging extension set up
  5. Pour créer une extension de messagerie, vous avez besoin d’un bot inscrit par Microsoft. Vous pouvez utiliser un bot existant ou en créer un nouveau. Sélectionnez Créer une option de bot, donnez un nom au nouveau bot, puis sélectionnez Créer. L’image suivante affiche la création d’un bot pour l’extension de messagerie :

    create bot for messaging extension
  6. Sélectionnez Ajouter dans la section Commande de la page Extensions de messagerie pour inclure les commandes qui déterminent le comportement de l’extension de messagerie.
    L’image suivante affiche l’ajout de commande pour l’extension de messagerie :

    include command
  7. Sélectionnez Autoriser les utilisateurs à déclencher des actions dans des services externes à l’intérieur Teams. L’image suivante affiche la sélection de commande d’action :

    action command selection
  8. Pour utiliser un ensemble statique de paramètres pour créer votre module de tâche, sélectionnez Définir un ensemble de paramètres statiques pour la commande.

    L’image suivante affiche la sélection de paramètre statique de commande d’action :

    action command static parameter selection

    L’image suivante affiche un exemple de paramètre statique :

    action command static parameter set-up

    L’image suivante affiche un exemple de test de paramètre statique :

    action command static parameter testing
  9. Pour utiliser des paramètres dynamiques, sélectionnez récupérer un ensemble dynamique de paramètres à partir de votre bot. L’image suivante affiche la sélection du paramètre de commande d’action :

    action command dynamic parameter selection
  10. Ajoutez un ID de commande et un titre.

  11. Sélectionnez l’emplacement à partir de lequel vous souhaitez appeler la commande d’action. L’image suivante affiche l’emplacement d’appel de commande d’action :

    action command invoke location
  12. Sélectionnez Enregistrer.

  13. Pour ajouter d’autres paramètres, sélectionnez le bouton Ajouter dans la section Paramètres.

Créer une commande d’action manuellement

Pour ajouter manuellement votre commande d’extension de messagerie basée sur l’action au manifeste de votre application, vous devez ajouter les paramètres suivants au tableau composeExtension.commands d’objets :

Nom de la propriété Objectif Obligatoire ? Version minimale du manifeste
id Cette propriété est un ID unique que vous affectez à cette commande. La demande de l’utilisateur inclut cet ID. Oui 1.0
title Cette propriété est un nom de commande. Cette valeur apparaît dans l’interface utilisateur. Oui 1.0
type Cette propriété doit être une action . Non 1.4
fetchTask Cette propriété est définie pour une carte adaptative ou un affichage web incorporé pour votre module de tâche, et pour une liste statique de paramètres ou lors du chargement de l’affichage true false web par un taskInfo . Non 1.4
context Cette propriété est un tableau facultatif de valeurs qui définit l’endroit d’où l’extension de messagerie est invoquée. 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 Cette propriété décrit la liste statique des paramètres de la commande. Utilisez uniquement quand fetchTask false est . Non 1.0
parameter.name Cette propriété décrit le nom du paramètre. Cette information est envoyée à votre service dans la demande de l’utilisateur. Oui 1.0
parameter.description Cette propriété décrit les objectifs du paramètre ou un exemple de la valeur à fournir. Cette valeur apparaît dans l’interface utilisateur. Oui 1.0
parameter.title Cette propriété est un titre ou une étiquette de paramètre convivial court. Oui 1.0
parameter.inputType Cette propriété est définie sur le type d’entrée requis. Les valeurs possibles text sont , , , , textarea number date time toggle . La valeur par défaut est définie sur text . Non 1.4

Si vous utilisez un affichage web incorporé, vous pouvez éventuellement ajouter l’objet pour récupérer votre affichage web sans appeler taskInfo 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 répond à l’action d’soumission du module de tâche. Si vous utilisez un taskInfo objet, vous devez définir le fetchTask paramètre sur false .

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 messagerie. Non 1.4
taskInfo.title Titre du module de tâche initial. Non 1.4
taskInfo.width Largeur du module de tâche, soit un nombre en pixels, soit une disposition par défaut telle large que medium , ou small . Non 1.4
taskInfo.height Hauteur du module de tâche, soit un nombre en pixels, soit une disposition par défaut telle large que medium , ou small . Non 1.4
taskInfo.url URL d’affichage web initiale. Non 1.4

Exemple de manifeste d’application

La section suivante est un exemple composeExtensions d’objet définissant deux commandes d’action. Il ne s’agit pas d’un exemple de manifeste complet. Pour obtenir le schéma de manifeste d’application complet, voir schéma de manifeste d’application:

...
"composeExtensions": [
  {
    "botId": "12a3c29f-1fc5-4d97-a142-12bb662b7b23",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "addTodo",
        "description": "Create a To Do item",
        "title": "Create To Do",
        "type": "action",
        "context": ["commandBox", "message", "compose"],
        "fetchTask": true,
        "parameters": [
          {
            "name": "Name",
            "description": "To Do Title",
            "title": "Title",
            "inputType": "text"
          },
          {
            "name": "Description",
            "description": "Description of the task",
            "title": "Description",
            "inputType": "textarea"
          },
          {
            "name": "Date",
            "description": "Due date for the task",
            "title": "Date",
            "inputType": "date"
          }
        ]
      },
      {
        "id": "reassignTodo",
        "description": "Reassign a todo item",
        "title": "Reassign a todo item",
        "type": "action",
        "fetchTask": true,
      }
    ]
  }
]
...

Exemple de code

Exemple de nom Description .NET Node.js
Teams d’extension de messagerie Décrit comment définir des commandes d’action, créer un module de tâche et répondre à une action d’soumission de module de tâche. View View
Teams d’extension de messagerie Décrit comment définir des commandes de recherche et répondre aux recherches. View View

Étape suivante

Si vous utilisez une carte adaptative ou un affichage web incorporé sans taskInfo objet, l’étape suivante consiste à :

Si vous utilisez les paramètres ou un affichage web incorporé avec un taskInfo objet, l’étape suivante consiste à :