通过

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

  • 项目

重要

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

若要在团队或群组聊天中安装 Microsoft Teams 机器人，请为机器人添加 teams 或 groupchat 范围。 此操作允许对话的所有成员与你的机器人互动。 安装机器人后，它有权访问有关对话的元数据，例如对话成员列表。 此外，当它在团队中安装时，机器人可以访问有关该团队的详细信息和完整的频道列表。

组或通道中的机器人仅在被提及 @botname时接收消息。 他们不会收到发送到对话的任何其他消息。 必须直接 @mentioned 机器人。 当提到团队或频道时，或者有人在没有团队或频道的情况下回复来自机器人 @mentioning 的消息时，机器人不会收到消息。

注意

  • 所有 聊天 消息的 RSC 仅在 公共开发人员预览版中可用。
  • 使用特定于资源的许可 (RSC) ，机器人可以接收其安装到的团队中的所有频道消息，而无需为 @mentioned。 有关详细信息，请参阅使用 RSC 接收所有频道消息。
  • 不支持将消息或自适应卡片发布到专用频道。

观看以下视频，了解与机器人的频道和群组聊天对话：


设计准则

与个人聊天不同，在群组聊天和频道中，机器人必须提供快速简介。 必须遵循这些和更多机器人设计准则。 有关如何在 Teams 中设计机器人的详细信息，请参阅如何在频道和聊天中设计机器人对话。

现在，可以创建新的对话线程，并轻松管理频道中的不同对话。

创建新的对话线程

在团队中安装机器人时，必须创建新的对话线程，而不是回复现有对话线程。 有时，很难区分两个对话。 如果会话是线程会话，则更容易组织和管理频道中的不同对话。 这是主动消息传送的一种形式。

接下来，可以使用 entities 对象检索提及，并使用 Mention 对象向消息添加提及。

处理提及

从组或通道向机器人发送的每条消息都包含在 @mention 消息文本中及其名称的 。 机器人还可以检索消息中提及的其他用户，并在它发送的任何消息中添加提及。 群组聊天中的机器人使用 @mention启用用户提及;但是，它们不支持 @everyone 提及。

还必须从机器人接收的消息内容中去除 @mentions 。

检索提及

提及在有效负载的 entities 对象中返回，并包含用户的唯一 ID 和提及的用户名。 消息文本还将包括如 <at>@John Smith<at> 的提及。 但是，不要依赖消息中的文本来检索有关用户的任何信息。 发送消息的人员可以对其进行更改。 因此，请使用 entities 对象。

可以通过调用 Bot Builder SDK 中的 GetMentions 函数来检索消息中的所有提及，该函数将返回一组 Mention 对象。

以下代码显示检索提及的示例：

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Resolves the mentions from the entities activity.
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

向消息添加提及

有两种类型的提及：

注意

短信和自适应卡片都支持用户提及和标记提及。

用户提及

机器人可以在频道中发布的消息中提及其他用户。

Mention 对象具有必须使用以下方法设置的两个属性：

  • 在消息文本中包含 @username。
  • 在实体集合中包含提及对象。

Bot Framework SDK 提供帮助程序方法和对象来创建提及。

以下代码显示向消息添加提及的示例：

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var mention = new Mention
    {
        Mentioned = turnContext.Activity.From,
        Text = $"<at>{XmlConvert.EncodeName(turnContext.Activity.From.Name)}</at>",
        Type = "mention",
    };

    // Returns a simple text message.
    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

现在，可以在首次安装机器人或将其添加到群组或团队时发送简介消息。

支持在用户提及中Microsoft Entra对象 ID 和 UPN

除了现有 ID 之外，机器人还支持用户提及 ID，例如Microsoft Entra对象 ID 和用户主体名称 (UPN) 。 传入 Webhook 开始使用 Microsoft Entra 对象 ID 和 UPN 支持自适应卡片中的用户提及。

以下代码片段演示了在文本消息中提及具有 Entra 对象 ID 和 UPN 的用户的示例：

var userId = "Adele@microsoft.com"; //User Principle Name
var mention = new ChannelAccount(userId, "Adele"); 
var mentionObj = new Mention 
{
    Mentioned = mention,
    Text = $"<at>{mention.Name}</at>" ,
    Type = "mention"
}; 

// Returns a simple text message.var replyActivity = MessageFactory.Text($"Hello {mentionObj.Text}.");replyActivity.Entities = new List<Entity> { mentionObj };

// Sends an activity to the sender of the incoming activity.await turnContext.SendActivityAsync(replyActivity, cancellationToken);

以下代码片段演示了在自适应卡片中提及具有 Entra 对象 ID 和 UPN 的用户的示例：

{
    "type": "mention",
    "text": "<at>Adele</at>",
    "mentioned": {
            "id": "Adele@microsoft.com" ,// User Principle Name
            "name": "Adele"
    }
}

标记提及

机器人可以在短信和频道中发布的自适应卡片中提及标记。 当机器人 @mentions 在频道中标记时，标记将突出显示，并且与该标记关联的人员会收到通知。 当用户将鼠标悬停在标记上时，将显示一个弹出窗口，其中包含标记详细信息。

在短信中提及标记

在 对象中 mention.properties ，添加 属性 'type': 'tag'。 如果未添加 属性'type': 'tag'，机器人会将提及视为用户提及。

示例：

在 type:tag ChannelAccount 中添加为 Properties 。

SDK 参考

​var mention = new ChannelAccount(tagId, "Test Tag"); 
​mention.Properties = JObject.Parse("{'type': 'tag'}"); 
​var mentionObj = new Mention 
​{ 
​    Mentioned = mention, 
​    Text = "<at>Test Tag</at>" 
​}; 

​var replyActivity = MessageFactory.Text("Hello " + mentionObj.Text); 
​replyActivity.Entities = new List<Microsoft.Bot.Schema.Entity> { mentionObj }; 
​await turnContext.SendActivityAsync(replyActivity, cancellationToken);
自适应卡片中的提及标记

在自适应卡片架构的 mentioned 对象下，添加 "type": "tag" 属性。 "type": "tag"如果未添加 属性，机器人会将提及视为用户提及。

可以使用列出 teamworkTags API 获取通道中可用的标记列表。

示例：

​{ 
​    "type": "mention", 
    ​"text": "<at>Test Tag</at>", 
​    "mentioned": { 
            ​"id": "base64 encoded id" ,// tag graph 64 base ID
​            "name": "Test Tag", 
            ​"type": "tag" 
​    } 
​}
查询参数
名称 说明
type 提及的类型。 支持的类型为 tag。
id 标记的唯一标识符。 有关详细信息，请参阅 teamworkTag。
错误代码
状态代码 错误代码 消息值 重试请求 开发人员操作
400 代码： Bad Request ID 为 {id string} 的提及标记在当前团队中不存在
只能在通道中提及标记
提及的标记无效，因为团队中不存在标记		 否 重新计算错误的请求有效负载。 有关详细信息，请查看返回的错误消息。
502 代码： Bad Gateway 无效的团队组 ID
标记的租户 ID 格式不正确
无法解析提及 ID		 否 手动重试。
节流限制

可以根据多个限制评估任何请求，具体取决于范围、窗口类型 (短) 和长) 、每条消息的标记数和其他因素。 即将达到的第一个限制会触发阻止行为。

确保未超过限制，以避免消息传递失败。 例如，机器人在 5 秒的窗口中只能发送两个带有标记提及的消息，每个消息最多只能有 10 个标记。

下表列出了机器人中标记提及的限制：

范围 窗口类型 每条消息的标记数 时间窗口 (秒) 每个时间窗口的最大消息数
每个线程的机器人数 短 10 5 2
  长 10 60 5
每个线程的所有机器人 短 10 5 4
  长型 10 60 5
限制
  • 仅在具有文本和自适应卡片的机器人到客户端消息流中支持标记提及。
  • 共享频道和专用频道不支持标记提及。
  • 连接器不支持标记提及。
  • 标记提及不支持机器人中的调用流。

在安装时发送消息

首次将机器人添加到群组或团队时，必须发送简介消息。 该消息必须简要说明机器人的功能以及如何使用它们。 必须订阅具有 teamMemberAdded eventType 的 conversationUpdate 事件。 添加任何新团队成员时，将发送该事件。 检查添加的新成员是否为机器人。 有关详细信息，请参阅向新团队成员发送欢迎消息。

添加机器人时，可以向团队的每个成员发送个人消息。 为此， 请提取团队名单 并向每个用户发送 直接消息。

注意

确保机器人发送的邮件相关，并为初始邮件增加价值，并且不会向用户发送垃圾邮件。

在以下情况下不要发送消息：

  • 例如，当团队规模较大时，超过 100 个成员。 机器人可能被视为垃圾邮件，添加机器人的人员可能会收到投诉。 你必须清楚地向所有看到欢迎消息的成员传达机器人的价值主张。
  • 首先在群组或频道中提及机器人，而不是先将其添加到团队。
  • 群组或频道已重命名。
  • 将团队成员添加到群组或频道。

Teams 机器人示例

代码示例

有关演示该功能的完整工作示例，请参阅 Bot Framework 的以下 Teams 示例：

示例名称 说明 .NET Node.js Python 清单
Teams 对话自动程序 此示例演示如何将机器人框架 v4 中提供的不同机器人对话事件用于个人和团队范围。 View View View View
使用 OAuthPrompt 进行身份验证 此示例演示 Bot Framework v4 中的身份验证和基本消息传送。 View View View View
Teams 文件上传 此示例演示如何在一对一对话中将文件与机器人一起使用。 View View View View
对话 (TeamsJS v1.x) 中称为任务模块 此示例演示如何对消息扩展使用对话框中的卡片中的值。 View View View View
在通道中启动新线程 此示例演示如何使用机器人在通道中使用新线程。 View View View View
Teams 应用本地化 此示例演示如何使用机器人和选项卡使用 Teams 应用本地化。 View View 不适用 View

分步指南

按照 分步指南创建 Teams 对话机器人。

后续步骤

订阅对话事件

另请参阅