为机器人创建命令菜单

项目
03/30/2023

注意

建议按照使用适用于 Teams 的新一代开发工具使用 JavaScript 生成命令机器人的分步指南创建命令机器人。有关 Teams 工具包的详细信息，请参阅适用于Visual Studio Code的 Teams 工具包概述和 Visual Studio 的 Teams 工具包概述。

重要

本部分中的代码示例基于 Bot Framework SDK 版本 4.6 和更高版本。如果要查找早期版本的文档，请参阅文档的旧版 SDK 文件夹中的机器人 - v3 SDK 部分。

若要定义机器人可以响应的核心命令集，可以添加包含机器人命令下拉列表的命令菜单。在用户与机器人对话时，命令列表将显示在用户的撰写消息区域中。从列表中选择一个命令，将命令字符串插入撰写消息框，然后选择“发送”。

桌面设备
移动设备

在应用清单中定义命令菜单。可以使用 开发人员门户 创建它们，也可以在应用清单中手动添加它们。

为机器人创建命令菜单的先决条件是必须编辑现有应用清单。无论是创建新清单还是编辑现有清单，添加命令菜单的步骤都是相同的。

若要使用开发人员门户为机器人创建命令菜单，请执行以下操作：

打开 Teams，然后从左窗格中选择“应用”。在 “应用 ”页中，搜索 “开发人员门户”，然后选择“ 打开”。
在 开发人员门户中，选择“ 应用 ”选项卡。如果没有现有应用包，可以创建或导入现有应用。有关详细信息，请参阅 Teams 开发人员门户。
选择“ 应用 ”选项卡，在左窗格中选择“ 应用功能 ”，然后选择“ 机器人”。
选择 “命令 ”部分下的“添加命令 ”。
输入显示为机器人的命令菜单的命令。
输入菜单中命令文本下方显示的 “说明 ”。说明必须是命令用途的简要说明。
选择“作用域检查”框，然后选择“添加”。这定义了命令菜单必须显示的位置。

创建命令菜单的另一种方法是在开发机器人源代码时直接在清单文件中创建。若要使用此方法，请遵循以下几点：

每个菜单最多支持 10 个命令。
创建一个在所有范围内生效的单个命令菜单。
为每个范围创建另一个命令菜单。

适用于两个范围的单个菜单的清单示例代码如下所示：

{
  ⋮
  "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"
            }
          ]
        }
      ]
    }
  ],
  ...
}

适用于每个范围的菜单的清单示例代码如下所示：

{
  ...
  "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"
            }
          ]
        }
      ]
    }
  ],
  ...
}

在处理来自用户的任何消息时，必须在机器人代码中处理菜单命令。可以通过分析消息文本的 @Mention 部分来处理机器人代码中的菜单命令。

组或通道中的机器人仅在消息提到 @botname 它们时才会响应。机器人在组或频道范围内收到的每条消息的消息文本中都包含其名称。在处理要返回的命令之前，消息分析必须处理机器人收到的含有其名称的消息。

注意

为了在代码中处理这些命令，命令将作为常规消息发送到机器人。你必须像处理来自用户的任何其他消息那样处理这些命令。代码中的命令会将预配置的文本插入文本框中。然后，用户必须像发送任何其他消息一样发送该文本。

可以使用随Microsoft Bot Framework提供的静态方法分析消息文本的@Mention部分。该方法是 Activity 类方法，名为 RemoveRecipientMention。

用于分析消息文本 @Mention 部分的 C# 代码如下所示：

// 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();

可以使用 Bot Framework 提供的一个静态方法分析消息文本的 @提及部分。该方法是 TurnContext 类方法，名为 removeMentionText。

用于分析消息文本 @Mention 部分的 JavaScript 代码如下所示：

// 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);

可以使用 Bot Framework 提供的一个静态方法分析消息文本的 @提及部分。该方法是 TurnContext 类方法，名为 remove_recipient_mention。

用于分析消息文本 @Mention 部分的 Python 代码如下所示：

# 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)

若要使机器人代码顺利运行，必须遵循一些最佳做法。

下面是命令菜单最佳做法：

保持简单：机器人菜单旨在呈现机器人的关键功能。
保持简短：菜单选项不能冗长，不能是复杂的自然语言语句。它们必须是简单的命令。
始终可调用：无论机器人所在的聊天或对话的状态如何，机器人菜单操作或命令必须始终可用。

注意

如果从清单中删除任何命令，则必须重新部署应用以实现更改。一般情况下，对清单所做的任何更改都需要重新部署应用。

后续步骤

使用机器人进行频道和群组对话

创建命令菜单

使用开发人员门户为机器人创建命令菜单

通过编辑 Manifest.json 为机器人创建命令菜单

适用于两个范围的单个菜单的清单示例

适用于每个范围的菜单的清单示例

在机器人代码中处理菜单命令

命令菜单最佳做法

后续步骤

另请参阅

反馈

其他资源