Créer un menu de commandes pour votre bot

Article
03/30/2023

Remarque

Il est recommandé de créer un bot de commande en suivant le guide pas à pas pour Créer un bot de commande avec JavaScript à l’aide de l’outil de développement nouvelle génération pour Teams. Pour plus d’informations sur teams Toolkit, consultez Vue d’ensemble du kit de ressources Teams pour Visual Studio Code et Vue d’ensemble du kit de ressources Teams pour Visual Studio.

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 bots - Kit de développement logiciel (SDK) v3 dans le dossier Kits de développement logiciel (SDK) hérités de la documentation.

Pour définir un ensemble de commandes principales auxquelles votre bot peut répondre, vous pouvez ajouter un menu de commandes avec une liste déroulante de commandes pour votre bot. La liste des commandes est présentée aux utilisateurs dans la zone de rédaction du message lorsqu’ils sont en conversation avec votre bot. Sélectionnez une commande dans la liste pour insérer la chaîne de commande dans la zone composer le message, puis sélectionnez Envoyer.

Imprimante de bureau
Mobile

Les menus de commande sont définis dans le manifeste de votre application. Vous pouvez utiliser le portail des développeurs pour les créer ou les ajouter manuellement dans le manifeste de l’application.

Un prérequis pour créer un menu de commande pour votre bot est que vous devez modifier un manifeste d’application existant. Les étapes d’ajout d’un menu de commande sont les mêmes, que vous créiez un nouveau manifeste ou que vous modifiiez un manifeste existant.

Pour créer un menu de commandes pour votre bot à l’aide du Portail des développeurs :

Ouvrez Teams et sélectionnez Apps dans le volet gauche. Dans la page Applications , recherchez Portail des développeurs, puis sélectionnez Ouvrir.
Dans le Portail des développeurs, sélectionnez l’onglet Applications . Si vous n’avez pas de package d’application existant, vous pouvez créer ou importer une application existante. Pour plus d’informations, consultez Portail des développeurs pour Teams.
Sélectionnez l’onglet Applications , sélectionnez Fonctionnalités de l’application dans le volet gauche, puis bots.
Sélectionnez Ajouter une commande sous la section Commandes .
Entrez la commande qui s’affiche en tant que menu de commandes pour votre bot.
Entrez la Description qui s’affiche sous le texte de la commande dans le menu. La description doit être une brève explication de l’objectif de la commande.
Sélectionnez la zone Étendue case activée, puis sélectionnez Ajouter. Cela définit l’emplacement où le menu de commande doit apparaître.

Une autre façon de créer un menu de commande consiste à le créer directement dans le fichier manifeste lors du développement de votre code source de bot. Pour utiliser cette méthode, suivez ces points :

Chaque menu prend en charge jusqu’à dix commandes.
Créez un menu de commandes unique qui fonctionne dans toutes les étendues.
Créez un menu de commandes différent pour chaque étendue.

L’exemple de code du manifeste pour un menu unique pour les deux étendues est le suivant :

{
  ⋮
  "bots":[
    {
      "botId":"[Microsoft App ID for your bot]",
      "scopes": [
        "personal",
        "team"
      ],
      "commandLists":[
        {
          "scopes":[
            "team",
            "personal"
          ],
          "commands":[
            {
              "title":"Help",
              "description":"Displays this help message"
            },
            {
              "title":"Search Flights",
              "description":"Search flights from Seattle to Phoenix May 2-5 departing after 3pm"
            },
            {
              "title":"Search Hotels",
              "description":"Search hotels in Portland tonight"
            },
            {
              "title":"Best Time to Fly",
              "description":"Best time to fly to London for a 5 day trip this summer"
            }
          ]
        }
      ]
    }
  ],
  ...
}

L’exemple de code du manifeste pour le menu pour chaque étendue est le suivant :

{
  ...
  "bots":[
    {
      "botId":"<Microsoft app ID for your bot>",
      "scopes": [
        "groupChat",
        "team"
      ],
      "commandLists":[
        {
          "scopes":[
            "team"
          ],
          "commands":[
            {
            "title":"help",
            "description":"Displays this help message for channels"
            }
          ]
        },
        {
          "scopes":[
            "groupChat"
          ],
          "commands":[
            {
            "title":"help",
            "description":"Displays this help message for group chat"
            }
          ]
        }
      ]
    }
  ],
  ...
}

Vous devez gérer les commandes de menu dans le code de votre bot à mesure que vous gérez les messages des utilisateurs. Vous pouvez gérer les commandes de menu dans le code de votre bot en analysant la partie @Mention du texte du message.

Les bots d’un groupe ou d’un canal répondent uniquement lorsqu’ils sont mentionnés @botname dans un message. Chaque message reçu par un bot dans une étendue de groupe ou de canal contient son nom dans le texte du message. Avant de gérer la commande retournée, votre analyse de message doit gérer le message reçu par un bot avec son nom.

Remarque

Pour gérer les commandes dans le code, elles sont envoyées à votre bot en tant que message standard. Vous devez les gérer comme vous le feriez pour tout autre message de vos utilisateurs. Les commandes du code insèrent du texte préconfiguré dans la zone de texte. L’utilisateur doit ensuite envoyer ce texte comme il le fait pour tout autre message.

Vous pouvez analyser la partie @Mention du texte du message à l’aide d’une méthode statique fournie avec le Microsoft Bot Framework. Il s’agit d’une méthode de la classe Activity nommée RemoveRecipientMention.

Le code C# pour analyser la partie @Mention du texte du message est le suivant :

// Remove recipient mention text from Text property.
// Use with caution because this function is altering the text on the Activity.
var modifiedText = turnContext.Activity.RemoveRecipientMention();

Vous pouvez analyser la partie @Mention du texte du message à l’aide d’une méthode statique fournie avec le Bot Framework. Il s’agit d’une méthode de la classe TurnContext nommée removeMentionText.

Le code JavaScript pour analyser la partie @Mention du texte du message est le suivant :

// Remove mention text from Text property, this function is altering the text on the Activity.
const modifiedText = TurnContext.removeMentionText(turnContext.activity, turnContext.activity.recipient.id);

Le code Python permettant d’analyser la partie @Mention du texte du message est le suivant :

# Remove recipient mention text from Text property, this function is altering the text on the Activity.
modified_text = TurnContext.remove_recipient_mention(turn_context.activity)

Pour permettre le bon fonctionnement de votre code de bot, vous devez suivre quelques bonnes pratiques.

Voici les meilleures pratiques du menu de commandes :

Restez simple : le menu du bot est destiné à présenter les fonctionnalités clés de votre bot.
Restez bref : les options de menu ne doivent pas être longues et ne doivent pas être des instructions de langage naturel complexes. Il doit s’agir de commandes simples.
Gardez-le invocable : les commandes ou les actions du menu bot doivent toujours être disponibles, quel que soit l’état de la conversation ou la boîte de dialogue dans lequel se trouve le bot.

Remarque

Si vous supprimez des commandes de votre manifeste, vous devez redéployer votre application pour implémenter les modifications. En général, toutes les modifications apportées au manifeste nécessitent le redéploiement de votre application.

Étape suivante

Conversations de canal et de groupe avec un bot

Créer un menu commandes

Créer un menu de commandes pour votre bot à l’aide du Portail des développeurs

Créer un menu de commandes pour votre bot en modifiant Manifest.json

Exemple de manifeste pour un menu unique pour les deux étendues

Exemple de manifeste pour le menu pour chaque étendue

Gérer les commandes de menu dans le code de votre bot

Meilleures pratiques pour le menu commande

Étape suivante

Voir aussi

Commentaires

Ressources supplémentaires