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

Importante

Les exemples de code de cette section sont basés sur la version 4.6 et les versions ultérieures du Kit de développement logiciel (SDK) Bot Framework. Si vous recherchez de la documentation pour les versions antérieures, consultez la section Extensions de message - Kit de développement logiciel (SDK) v3 dans le dossier Ressources de la documentation.

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.

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

  1. 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 de message que l’utilisateur doit envoyer ?

Consultez la vidéo suivante pour découvrir comment définir des commandes d’action d’extension de message :

[!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE4OANG]

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

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

  • Zone de rédaction du message : boutons situés en bas de la zone de rédaction du message.

    Contexte de commande = composer

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

    Contexte des commandes = commandBox

    Remarque

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

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

    Contexte des commandes = message

    Remarque

    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 lui présenter un module de tâche.

L’image suivante affiche les emplacements à partir desquels la commande d’action est appelée :

Appeler des emplacements par la commande action

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

En plus de sélectionner l’emplacement à partir duquel votre commande peut être appelée, vous devez également sélectionner comment remplir le formulaire dans le module de tâche pour vos utilisateurs. Vous disposez des trois options suivantes pour créer le formulaire rendu à l’intérieur du module de tâche :

  • Liste statique des 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 affiche, mais dans ce cas, vous ne pouvez pas contrôler la mise en forme.
  • Carte adaptative : vous pouvez choisir d’utiliser une carte adaptative, qui offre un meilleur contrôle sur l’interface utilisateur, tout en vous limitant sur les contrôles disponibles et les options de mise en forme.
  • Vue web incorporée : vous pouvez choisir d’incorporer une vue web personnalisée dans le module de tâche pour avoir un contrôle total 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 que l’utilisateur envoie le module de tâche, l’extension de message est appelée. Lorsque vous utilisez une vue web incorporée ou une carte adaptative, votre extension de message 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 le mode d’envoi du message final

Dans la plupart des cas, la commande d’action entraîne l’insertion d’une carte dans la zone de composition du 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 pas modifier ou mettre à jour davantage la carte.

Si l’extension de message est appelé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 bot au manifeste de l’application en utilisant le même ID et en 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 composeExtension au niveau supérieur du manifeste d’application JSON. Pour ce faire, vous pouvez utiliser l’une des méthodes suivantes :

Créer une commande d’action à l’aide du Portail des développeurs

Vous pouvez créer une commande d’action à l’aide du Portail des développeurs.

Remarque

La configuration requise pour créer une commande d’action est que vous avez déjà créé une extension de message. Pour plus d’informations sur la création d’une extension de message, consultez créer une extension de message.

Pour créer une commande d’action :

  1. Ouvrez le Portail des développeurs à partir du client Microsoft Teams et sélectionnez l’onglet Applications. Si vous avez déjà créé votre package d’application dans le Portail des développeurs, sélectionnez dans la liste. Si vous n’avez pas créé de package d’application, importez-en un existant.

  2. Après avoir importé un package d’application, sélectionnez Extensions de message sous Fonctionnalités de l’application.

  3. Pour créer une extension de message, vous avez besoin d’un bot inscrit par Microsoft. Vous pouvez utiliser un bot existant ou en créer un. Sélectionnez l’option Créer un bot , donnez un nom au nouveau bot, puis sélectionnez Créer.

    La capture d’écran vous montre comment créer un bot dans le portail des développeurs.

  4. Pour utiliser un bot existant, sélectionnez Sélectionner un bot existant et choisissez les bots existants dans la liste déroulante ou sélectionnez Entrer un ID de bot si vous avez déjà créé un ID de bot.

  5. Sélectionnez l’étendue du bot, puis Enregistrez.

  6. Sélectionnez Ajouter une commande dans la section Commande pour inclure les commandes, ce qui détermine le comportement de l’extension de message.

    Capture d’écran montrant comment ajouter une commande pour définir le comportement de l’extension de message.

  7. Sélectionnez Action , puis type de paramètre.

  8. Entrez ID de commande, Titre de la commande et Description de la commande.

  9. Entrez tous les paramètres et sélectionnez le type d’entrée dans la liste déroulante.

    Capture d’écran montrant comment ajouter des paramètres pour définir votre commande pour l’extension de message.

  10. Sélectionnez Ajouter un domaine sous Liens de préversion.

  11. Entrez domaine valide, puis sélectionnez Ajouter.

    Capture d’écran montrant comment ajouter un domaine valide à votre extension de messagerie pour les déploiements de liens.

  12. Sélectionnez Enregistrer.

    Capture d’écran montrant comment enregistrer tous vos paramètres et paramètres pour votre extension de message.

Pour ajouter des paramètres supplémentaires

  1. Sélectionnez ellipse sous la section de commande, puis sélectionnez Modifier le paramètre.

    Captures d’écran montrant comment ajouter des paramètres supplémentaires pour votre extension de message.

  2. Sélectionnez Ajouter des paramètres et entrez tous les paramètres.

    Capture d’écran montrant comment ajouter des paramètres supplémentaires pour votre extension de message.

Créer une commande d’action manuellement

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

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 un action. Non 1.4
fetchTask Cette propriété est définie 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 Cette propriété est un tableau facultatif de valeurs qui définit l’emplacement à partir duquel l’extension de message est appelé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 lorsque fetchTask est false. Non 1.0
parameter.name Cette propriété décrit le nom du paramètre. Il est envoyé à votre service dans la demande de l’utilisateur. Oui 1.0
parameter.description Cette propriété décrit les objectifs des paramètres ou l’exemple de la valeur qui doit être fournie. 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 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

Exemple de manifeste d’application

Cette section n’est pas un exemple de manifeste complet. Pour obtenir le schéma complet du manifeste d’application, consultez Schéma du manifeste d’application. Voici un exemple d’objet composeExtensions définissant deux commandes d’action :

...
"composeExtensions": [
  {
    "botId": "c8fa3cf6-b1f0-4ba8-a5bf-a241bc29adf3",
    "commands": [
      {
        "id": "To do",
        "type": "action",
        "title": "Create To do",
        "description": "Create a To do",
        "initialRun": true,
        "fetchTask": false,
        "context": [
          "commandBox",
          "compose"
        ],
        "parameters": [
          {
            "name": "Name",
            "title": "Title",
            "description": "To do Title",
            "inputType": "text"
          },
          {
            "name": "Description",
            "title": "Description",
            "description": "Description of the task",
            "inputType": "textarea"
          },
          {
            "name": "Date",
            "title": "Date",
            "description": "Due date for the task",
            "inputType": "date"
          }
        ]
      }
    ],
    "canUpdateConfiguration": true,
    "messageHandlers": [
      {
        "type": "link",
        "value": {
          "domains": [
            "yourapp.onmicrosoft.com"
          ]
        }
      }
    ]
  }
]
...

Exemple de code

Exemple de nom Description .NET Node.js
Action d’extension de message Teams Décrit comment définir des commandes d’action, créer un module de tâche et répondre à l’action d’envoi du module de tâche. View View

Guide pas à pas

Suivez le guide pas à pas pour créer une extension de message basée sur des actions Teams.

Étape suivante

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

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

Voir aussi