机器人配置体验

项目
04/13/2024

机器人配置体验允许用户在安装后直接在频道或群聊中设置和重新配置其机器人的设置，从而从一开始就提高操作效率。此功能消除了重复的用户干预的需要，这些干预以前阻碍了应用的及时实现。用户现在可以在安装期间根据特定的工作流和首选项定制机器人，并根据需要重新配置设置，以适应不断变化的要求，确保机器人的持续相关性和价值。

例如，假设有一个跟踪和共享新闻主题或监视 GitHub 存储库的机器人。这些机器人最初配置为与用户工作流保持一致，可以轻松地重新配置，以便直接从群聊响应新主题或存储库，简化内容管理和交互，而无需离开 Teams 环境。这种灵活的配置体验通过将机器人无缝集成到日常操作中，显著提高了用户体验和工作效率。

下面是一个示例，其中用户将机器人添加到群聊，然后将其配置为符合其特定要求。然后，用户重新配置机器人以更改状态。

配置

该图显示了将机器人配置为 Teams 通道的过程。

配置

屏幕截图显示了消息撰写区域中机器人的配置选项。

生成机器人配置体验

注意

机器人配置体验仅在频道或群组聊天中受支持。

生成机器人配置体验时，必须确保用户必须能够在首次安装时配置机器人，并随时重新配置机器人。

若要生成机器人配置体验，请执行以下步骤：

更新应用清单
配置机器人

更新应用清单

在应用清单 (以前称为 Teams 应用清单) 文件中，按如下所示更新 fetchTask 对象下的 bots.configuration 属性：

"bots": [
    {
      "botId": "${{AAD_APP_CLIENT_ID}}",
     "needsChannelSelector": false,
      "scopes": [
        "personal",
        "team",
        "groupChat"
      ],
      "configuration":{
        "groupChat":{
          "fetchTask": true
        },
        "team":{
          "fetchTask": true
        }
      },
      "isNotificationOnly": false
    }
  ],

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

配置机器人

当用户在频道或群组聊天中安装机器人时，fetchTask应用清单文件中的属性会config/fetch根据文件中的定义teamsBot.js启动或 config/submit 。

如果将应用清单中的属性设置为 fetchTask ：

false：机器人不会提取对话或自适应卡片。相反，机器人必须提供在调用机器人时使用的静态对话或卡片。有关详细信息，请参阅对话框。
true：机器人按定义启动 config/fetch 或 config/submit 。调用机器人时，可以根据 channelData 和 userdata 中提供的上下文返回自适应卡片或对话。

下表列出了与调用请求关联的响应类型：

调用请求	响应类型
`config/fetch`	`Type: "continue"` 或 `Type = "auth"`
`config/submit`	`Type: "continue"` 或 `Type: "message"`

type: "continue"： type: "continue" 用于在机器人配置中定义对话或自适应卡片的延续。当类型设置为 continue时，它表示机器人希望用户进行进一步的交互，以继续执行配置过程。

adaptiveCardForContinue是一个自定义函数，可返回要在机器人工作流的不同阶段使用的自适应卡的 JSON。这些函数用于根据用户与机器人的交互返回不同方案的自适应卡片。

当用户提交配置时，将 config/submit 触发调用。它读取用户的输入并返回不同的自适应卡片。还可以更新机器人配置以返回对话框。

C#
JavaScript

示例代码参考

protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
    ConfigResponseBase response = adaptiveCardForContinue();
    return Task.FromResult(response);
}

示例代码参考

async handleTeamsConfigFetch(_context, _configData) {
    let response = {};
    const adaptiveCard = CardFactory.adaptiveCard(this.adaptiveCardForContinue());
    response = {
       config: {
          value: {
             card: adaptiveCard,
             height: 500,
             width: 600,
             title: 'test card',
          },
          type: 'continue',
       },
    };
    return response;
}

type: "auth"：还可以请求用户进行身份验证，作为对请求的 config/fetch 响应。该 type: "auth" 配置提示用户通过指定的 URL 登录，该 URL 必须链接到可在浏览器中打开的有效身份验证页。对于机器人要求对用户进行身份验证的方案，身份验证至关重要。它可确保验证用户的身份，维护机器人功能中的安全性和个性化体验。

注意

仅 type: "auth" 支持第三方身份验证。不支持单一登录 (SSO) 。有关第三方身份验证的详细信息，请参阅添加身份验证。

C#
JavaScript

示例代码参考

protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
    ConfigResponseBase response = new ConfigResponse<BotConfigAuth> {
       Config = new BotConfigAuth {
          SuggestedActions = new SuggestedActions {
             Actions = new List<CardAction> {
                new CardAction {
                   type: "openUrl",
                   value: "https://example.com/auth",
                   title: "Sign in to this app"
                }
             }
          },
       Type = "auth"
    }
};

示例代码参考

async handleTeamsConfigFetch(_context, _configData) {
    let response = {};
    response = {
       config: {
          type: "auth",
          suggestedActions: {
             actions: [{
                type: "openUrl",
                value: "https://example.com/auth",
                title: "Sign in to this app"
             }]
          },
      },
    };
    return response;
}

type="message"：当类型设置为 message 时，它表示机器人正在向用户发送一条简单的消息，指示交互的结束或提供信息，而无需进一步输入。

C#
JavaScript

示例代码参考

protected override Task<ConfigResponseBase> OnTeamsConfigSubmitAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
    ConfigResponseBase response = new ConfigResponse<TaskModuleResponseBase>
    {
       Config = new TaskModuleMessageResponse
       {
          Type = "message",
          Value = "You have chosen to finish setting up bot"
       }
    };
    return Task.FromResult(response);
}

示例代码参考

async handleTeamsConfigSubmit(context, _configData) {
    let response = {};
    response = {
       config: {
          type: 'message',
          value: 'You have chosen to finish setting up bot',
       },
    }
    return response;
}

当用户重新配置机器人时， fetchTask 应用清单文件中的属性将在 config/fetch 机器人逻辑中启动。用户可以在安装后通过两种方式重新配置机器人设置：

@mention 消息撰写区域中的机器人。选择邮件撰写区域上方显示的 “设置” 选项。对话框中将显示一个对话框，更新或更改机器人的配置设置。
将鼠标悬停在机器人上，将显示机器人配置文件卡。若要更新或更改机器人的配置设置，请选择机器人配置文件卡中的设置图标。

最佳做法

如果想要拥有机器人的单个通道级配置，请确保根据通道跟踪配置。不会存储配置数据，并且调用有效负载包括足够的 channelData。
提供清晰且用户友好的对话框，提示用户输入机器人正常运行所需的信息，例如 URL、区域路径或仪表板链接。
避免在安装后发送多个通知或配置请求，因为这可能会让用户感到困惑。

代码示例

示例名称	说明	.NET	Node.js	清单
机器人配置应用	此示例代码介绍团队和群组聊天中机器人的配置和重新配置，`message`以及`continue`响应类型。	View	View	View
具有身份验证的机器人配置应用	此示例代码介绍团队和群组聊天中机器人的配置和重新配置，`message`以及`auth`响应类型。	View	View	View

分步指南

按照分步指南配置机器人，在安装过程中或在安装机器人的团队或群组聊天安装之后配置机器人。

通过

机器人配置体验

生成机器人配置体验

更新应用清单

配置机器人

最佳做法

代码示例

分步指南

另请参阅

其他资源