Build d’extensions de messages

Les extensions de message permettent aux utilisateurs d’interagir avec votre service web via des boutons et des formulaires dans le client Microsoft Teams. Les utilisateurs effectuer des recherches ou lancer des actions, dans un système externe à partir de la zone de rédaction de message, de la zone de commande ou directement d’un message. Les résultats de ces interactions peuvent être retournés au client Teams sous la forme d’un carte au format enrichi.

Importante

Les extensions de message sont disponibles dans les environnements Government Community Cloud (GCC), GCC-High et Department of Defense (DOD).

Ce document fournit une vue d’ensemble des extensions de message, des tâches exécutées dans différents scénarios, du fonctionnement des extensions de message, des commandes d’action et de recherche, et du déploiement de liens.

L’image suivante affiche les emplacements à partir desquels les extensions de message peuvent être appelées :

Remarque

@mentioning les extensions de message dans la zone de composition ne sont pas prises en charge.

Imprimante de bureau

Mobile

Scénarios dans lesquels les extensions de message sont utilisées

Scénario	Exemple
Vous avez besoin d’un système externe pour effectuer une action et retourner le résultat à votre conversation.	Réservez une ressource et autorisez le canal à connaître l’intervalle de temps réservé.
Vous devez rechercher quelque chose dans un système externe et partager les résultats avec la conversation.	Recherchez un élément de travail dans Azure DevOps et partagez-le avec le groupe sous forme de carte adaptative.
Vous souhaitez effectuer une tâche complexe impliquant plusieurs étapes ou une grande quantité d’informations dans un système externe et partager les résultats avec une conversation.	Créez un bogue dans votre système de suivi en fonction d’un message Teams, attribuez ce bogue à Bob et envoyez une carte au thread de conversation avec les détails du bogue.

Comprendre le fonctionnement des extensions de message

Une extension de message se compose d’un service web que vous hébergez et d’un manifeste d’application, qui spécifie l’emplacement dans le client Teams où votre service web est appelé. Le service web utilise le schéma de messagerie de Bot Framework et le protocole de communication sécurisé. Vous devez donc inscrire votre service web en tant que bot dans Bot Framework.

Remarque

Bien qu’il soit possible de créer manuellement le service web, nous vous recommandons d’utiliser le Kit de développement logiciel (SDK) Bot Framework pour utiliser le protocole.

Dans le manifeste de l’application (précédemment appelé manifeste d’application Teams), une seule extension de message est définie avec jusqu’à 10 commandes différentes. Chaque commande définit un type, tel que l’action ou la recherche et les emplacements dans le client à partir desquels il est appelé. Les emplacements d’appel incluent la zone de rédaction des messages, la barre de commandes et le message. Lors de l’appel, le service web reçoit un message HTTPS avec une charge utile JSON avec toutes les informations pertinentes. Répondez avec une charge utile JSON pour informer le client Teams de l’interaction suivante à activer.

Types de commandes d’extension de message

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. Certaines interactions, telles que l’authentification et la configuration, sont disponibles pour les deux types de commandes.

Commandes d’action

Les commandes d’action sont utilisées pour présenter aux utilisateurs une fenêtre contextuelle modale afin de collecter ou d’afficher des informations. Lorsque l’utilisateur envoie le formulaire, votre service web répond en insérant un message directement dans la conversation ou dans la zone de rédaction du message. Par la suite, l’utilisateur peut envoyer le message. Pour les flux de travail plus complexes, vous pouvez lier plusieurs formulaires entre eux.

Les commandes d’action sont déclenchées à partir de la zone de rédaction du message, de la zone de commande ou d’un message. Lorsque la commande est appelée à partir d’un message, la charge utile JSON initiale envoyée à votre bot inclut l’intégralité du message à partir duquel elle a été appelée. L’image suivante affiche la boîte de dialogue de commande d’action d’extension de message (appelée module de tâche dans TeamsJS v1.x) :

Commandes de recherche

Les commandes de recherche permettent aux utilisateurs de rechercher manuellement des informations dans un système externe via une zone de recherche ou en collant un lien vers un domaine surveillé dans la zone de rédaction du message et en insérant les résultats de la recherche dans un message. Dans un flux de commande de recherche simple, le message d’appel initial inclut la chaîne de recherche soumise par l’utilisateur. Vous répondez avec une liste de cartes et d’aperçus de cartes. Le client Teams affiche une liste d’aperçus de carte pour l’utilisateur. Lorsque l'utilisateur sélectionne une carte dans la liste, la carte en taille réelle est insérée dans la zone de composition du message.

Les cartes sont déclenchées à partir de la zone de rédaction du message ou de la zone de commande, mais pas à partir d’un message. Ils ne peuvent pas être déclenchés à partir d’un message. L’image suivante affiche la boîte de dialogue de la commande de recherche d’extension de message :

Remarque

Pour plus d’informations sur les cartes, voir ce que sont les cartes.

Déploiement de lien

Remarque

Le déploiement de liens est pris en charge uniquement pour les extensions de message basées sur un bot.

Lorsqu’une URL est collée dans la zone de rédaction du message, un service web est appelé. Cette fonctionnalité est appelée déploiement de liens. Vous pouvez vous abonner pour recevoir un appel lorsque des URL contenant un domaine spécifique sont collées dans la zone de rédaction du message. Votre service web peut déployer l’URL dans un carte détaillé, en fournissant plus d’informations que les carte d’aperçu de site web standard. Vous pouvez ajouter des boutons pour permettre aux utilisateurs d’agir immédiatement sans quitter le client Teams. Les images suivantes affichent la fonctionnalité de déploiement de lien lorsqu’un lien est collé dans une extension de message :

Build d’extensions de messages

Pour générer une extension de message, si vous n’en avez pas déjà une, il existe deux façons :

• Créer des extensions de message à l’aide de l’API (basée sur l’API) : vous pouvez facilement créer une extension de message à partir d’une API existante. Un document OpenAPI Description (OAD) est requis pour cette méthode.

• Créer des extensions de message à l’aide de Bot Framework (basé sur un bot) : si vous souhaitez une expérience conversationnelle en un-à-un, vous pouvez créer une extension de message à partir d’un bot.

Le tableau suivant vous aide à sélectionner un type d’extension de message pour commencer :

Extension de message basée sur l’API

• Création et maintenance plus simples et plus rapides.
• L’extension de message utilise une API.
• Aucune ressource ou code supplémentaire n’est nécessaire pour la logique du bot.
• Idéal pour les scénarios où l’extension de message doit uniquement communiquer avec un service web et n’a pas besoin d’une logique ou d’une gestion d’état complexe.
• Le trafic est privatisé, car il ne dépend pas de l’infrastructure de bot Azure.
• Prend en charge les commandes de recherche.

Extension de message basé sur un bot

• Plus flexible.
• L’extension de message utilise un Bot Framework.
• Peut tirer parti de toutes les fonctionnalités d’un bot.
• Idéal pour les scénarios où l’extension de message doit communiquer avec plusieurs services, gérer une logique complexe ou des interactions utilisateur, ou maintenir l’état entre les sessions.
• Prend en charge les commandes d’action, les commandes de recherche et le déploiement de liens.

Sélectionnez une option pour commencer à créer une extension de message :

Exemple de code

Exemple de nom	Description	.NET	Node.js	Python	Manifeste
Extension de message avec des commandes basées sur des actions	Cet exemple montre comment définir des commandes d’action, créer un dialogue et répondre à l’action d’envoi du dialogue.	View	View	View	View
Extension de message avec des commandes basées sur la recherche	Cet exemple montre comment créer une extension de message basée sur la recherche. Il recherche les packages nuget et affiche les résultats dans l’extension de messagerie basée sur la recherche.	View	View	View	View
Aperçu de l’action d’extension de message	Cet exemple montre comment utiliser l’aperçu de l’action dans Les extensions de messagerie à l’aide de Bot Framework v4.	View	View	N/A	View
Action d’extension de message pour la planification des tâches	Cet exemple montre comment planifier une tâche à partir de la commande d’action d’extension de message et obtenir un rappel carte à une date et une heure planifiées.	View	View	N/A	View