使用 Bot Framework 生成消息扩展

使用 Bot Framework 构建的消息扩展 (基于机器人) 使用 Web 服务作为机器人。 可以使用消息扩展使用户能够从 Teams 客户端的不同位置（例如撰写消息区域、命令框）与 Web 服务交互，或者直接从消息发送回结构化数据（如卡片）。

基于机器人的消息扩展利用 Bot Framework 的消息传送架构和安全通信协议。 机器人在 Teams 应用的应用清单中定义，你还可以为消息扩展定义不同类型的命令，例如操作命令或搜索命令。

消息扩展命令有两种类型：操作命令和搜索命令。 消息扩展命令类型定义可供 Web 服务使用的 UI 元素和交互流。 可以使用搜索命令或操作命令通过 Teams 中的机器人与 Web 服务交互。

搜索命令

邮件扩展搜索命令允许用户搜索外部系统，并将该搜索结果以卡的形式插入邮件中。 本文档指导你如何选择搜索命令调用位置，以及如何将搜索命令添加到应用清单。

注意

结果卡大小限制为 28 KB。 如果卡的大小超过 28 KB，则不会发送该卡。

请参阅以下视频，了解如何定义消息扩展搜索命令：

消息扩展中的搜索命令是使用 composeExtensions.commands 应用清单中的 属性和 query 类型配置的， (以前称为 Teams 应用清单) 。 命令和参数说明增强了消息扩展的可用性和有效性。 良好的命令说明提供对应用功能的清晰而简洁的摘要。

以下代码是定义搜索命令的属性示例 composeExtensions ：

{
 "composeExtensions": [
    {
      "botId": "eccdf132-0900-4d36-936b-dec5e6357f11",
      "commands": [
        {
          "id": "Dev",
          "type": "query",
          "title": "Jedi",
          "description": "May the force be with you",
          "initialRun": true,
          "fetchTask": false,
          "context": [
            "commandBox",
            "compose",
            "message"
          ],
          "parameters": [
            {
              "name": "Luke",
              "title": "Skywalker",
              "description": "Jedi master",
              "inputType": "text"
            }
          ]
        }
      ],
      "canUpdateConfiguration": true
    }
  ],

参数

必须将以下参数添加到 composeExtensions.commands 对象数组：

属性名称	用途	是否必需？	清单版本
id	分配给搜索命令的唯一 ID。 用户请求包含此 ID。	是	1.0
title	命令名称。 此值显示在用户界面 (UI) 中。	是	1.0
description	指示此命令执行的操作的帮助文本。 此值显示在 UI 中。	是	1.0
semanticDescription	供大型语言模型使用的命令的语义说明。	否	1.17
type	命令的类型。 默认值为“query”。	否	1.4
initialRun	如果此属性设置为 true，则表示应在用户在 UI 中选择此命令后立即执行此命令。	否	1.0
context	可选的值数组，用于定义搜索操作可用的上下文。 可取值包括 message、compose 或 commandBox。 默认值为 compose。commandBox。	否	1.5

必须添加以下搜索参数详细信息，用于定义在 Teams 客户端中对用户可见的文本：

属性名称	用途	是否必需？	最低清单版本
parameters	定义命令的参数的静态列表。	否	1.0
parameter.name	描述参数的名称。 在 parameter.name 用户请求中将 发送到服务。	是	1.0
parameter.description	描述参数的用途或必须提供的值的示例。 此值显示在 UI 中。	是	1.0
parameter.semanticDescription	大型语言模型使用的参数的语义说明。	否	1.17
parameter.title	简短的用户友好型参数标题或标签。	是	1.0
parameter.inputType	设置为所需的输入类型。 可能的值包括 text、、textarea、numberdate、time、toggle。 默认值设置为 text。	否	1.4
parameters.value	参数的初始值。 目前不支持该值	否	1.5

有关详细信息，请参阅 应用清单架构。

后续步骤

定义邮件扩展搜索命令

操作命令

注意

启动邮件操作时，附件详细信息不会作为调用活动的 turncontext 一部分发送。

使用操作命令，可以在 Teams 中向用户显示称为任务模块的模式弹出窗口。 任务模块收集或显示信息、处理交互并将信息发送回 Teams。 本文档指导你如何选择操作命令调用位置、创建任务模块、发送最终消息或卡片、使用 App Studio 创建操作命令或手动创建操作命令。

消息扩展中的操作命令是使用 composeExtensions.commands 属性并在 action 应用清单中键入配置的。

以下代码是定义操作命令的属性示例 composeExtensions ：

"composeExtensions": [
        {
            "botId": "xxxxxx-xxx-bot-ID-xxxxxxxx}",
            "commands": [
                {
                    "id": "createCard",
                    "context": [
                        "compose",
                        "message",
                        "commandBox"
                    ],
                    "description": "Command to run action to create a Card from Compose Box",
                    "title": "Create Card",
                    "type": "action",
                    "parameters": [
                        {
                            "name": "title",
                            "title": "Card title",
                            "description": "Title for the card",
                            "inputType": "text"
                        },
                        {
                            "name": "subTitle",
                            "title": "Subtitle",
                            "description": "Subtitle for the card",
                            "inputType": "text"
                        },
                        {
                            "name": "text",
                            "title": "Text",
                            "description": "Text for the card",
                            "inputType": "textarea"
                        }
                    ]
                }
            ]
        }
    ]

参数

必须将以下参数添加到 composeExtensions.commands 对象数组：

属性名称	用途	是否必需？	清单版本
id	分配给此命令的唯一 ID。 用户请求包含此 ID。	是	1.0
title	命令名称。 此值显示在 UI 中。	是	1.0
type	消息扩展类型。 默认值为“action”。	否	1.4
fetchTask	true对于任务模块的自适应卡片或嵌入式 Web 视图，或者对于参数的静态列表，false或者当通过 taskInfo加载 Web 视图时，将 设置为 。	否	1.4
context	可选的值数组，用于定义从中调用消息扩展的位置。 可取值包括 message、compose 或 commandBox。 默认值为 ["compose", "commandBox"]。	否	1.5

如果使用参数的静态列表，还必须添加以下参数：

属性名称	用途	是否必需？	最低清单版本
parameters	描述命令的参数的静态列表。 仅当 fetchTask 为 false 时使用。	否	1.0
parameter.name	描述参数的名称。 这会在用户请求中发送到服务。	是	1.0
parameter.description	描述参数的用途或应提供的值的示例。 此值显示在 UI 中。	是	1.0
parameter.title	简短的用户友好型参数标题或标签。	是	1.0
parameter.inputType	设置为所需的输入类型。 可能的值包括 text、textarea、number、date、time、toggle。 默认值设置为 text。	否	1.4

如果使用嵌入式 Web 视图，可以选择添加 taskInfo 对象来提取 Web 视图，而无需直接调用机器人。 如果选择此选项，则行为类似于使用静态参数列表。 在此情况下，与机器人的第一次交互是响应任务模块提交操作。 如果使用 taskInfo 对象，则必须将 fetchTask 参数设置为 false。

属性名称	用途	是否必需？	最低清单版本
taskInfo	指定使用消息扩展命令时要预加载的任务模块。	否	1.4
taskInfo.title	初始任务模块标题。	否	1.4
taskInfo.width	任务模块宽度，以像素为单位的数字或默认布局，如 large、medium 或 small。	否	1.4
taskInfo.height	任务模块高度，以像素为单位的数字或默认布局，如 large、medium 或 small。	否	1.4
taskInfo.url	初始 Web 视图 URL。	否	1.4

有关详细信息，请参阅 应用清单架构。

后续步骤

定义消息扩展操作命令

另请参阅

• 基于搜索的消息扩展的通用操作
• 基于 API 的消息扩展