向 Microsoft Teams 中的用户发送活动源通知

  • 项目

Microsoft Teams 活动源使用户能够通过通知更改来对需要注意的项目进行会审。 可以使用 Microsoft Graph 中的活动源通知 API 将此功能扩展到应用。 这允许你的应用提供更丰富的体验，并通过帮助用户及时了解他们所使用的工具和工作流的更改，从而更好地吸引用户。

活动源通知的用例

  • 新闻：帮助用户随时了解最新信息，例如新作业或新帖子。
  • 协作：在评论中共享文件或 @ 提及用户时，用户可以在通知横幅中看到文本预览。
  • 提醒：通知，用于通知事件或任务。 例如，你今天有一个训练截止日期，应用会向你发送提醒通知，以帮助你记住任务或事件。
  • 警报：需要紧急或立即关注的通知。 例如，培训的截止日期已过，或者管理员发送了修复优先级最高的 bug 的请求。

活动源通知的优点

  • 活动源通知是一种本机 Teams 集成，可让用户无缝地进入选项卡应用，从而将 活动 中的其他用户参与度引入应用。
  • 活动源通知在 Teams 桌面和移动客户端中附带 OS 通知，以便从系统弹出窗口和声音中获取用户的注意力。
  • 通知内容高度可自定义，允许用户预览通知事件的摘要。
  • 你可以将应用深层链接到通知，以便在用户选择通知时，它会增加用户应用参与度。
  • 可以向各种收件人发送活动源通知。 例如，向一组用户发送个人通知或发送批通知。
  • 应用清单 (以前称为 Teams 应用清单) 本地化支持活动源通知中的模板化文本。

了解活动源通知的基础知识

在 Teams 中，活动源通知由多个信息位一起显示，如下图所示：

屏幕截图显示活动源通知的组件。

组件包括：

计数器 说明
1 虚拟形象：显示发起活动的人员。
2 活动类型或应用图标：活动类型或应用图标描述活动类型。 对于应用通知，行图标将替换为应用图标。
3 标题：执行组件 + 原因： 执行组件：启动活动的用户或应用的名称。 原因：描述活动。
4 时间戳：显示活动发生时间。
5 文本预览：显示通知开头的截断行。
6 位置：显示活动在 Teams 中发生的位置。

以下示例演示这些组件一起提供有关通知的详细信息。

屏幕截图显示了通知的示例。

活动源通知卡的类型

以下变体显示了可以显示的活动源通知卡的类型。 应用徽标替换应用生成的通知的用户头像：

屏幕截图显示桌面中的活动源通知。

计数器 说明
1 Teams 自定义
2 Windows
3 Mac

使用活动源通知 API 的要求

活动源 API 可与 Teams 应用配合使用。 以下是发送活动源通知的要求：

  • 应用清单必须将Microsoft Entra应用 ID 添加到 webApplicationInfo 节。 有关详细信息，请参阅 应用清单架构。
  • 可以发送活动通知，无论是否在应用清单中添加活动类型。
    • 默认情况下，可以使用活动通知 API，而无需在应用清单中添加 activities 节。 活动 systemDefault 类型是保留的，这样就可以在活动源通知的行中 Actor+Reason 提供自由格式的文本。 有关详细信息，请参阅 发送可自定义的活动源通知。

      注意

      活动 systemDefault 类型仅在 公共开发人员预览版中可用。

    • 如果要在传统模式下发送模板化通知， activityTypes 则必须在 活动 部分中添加 属性。 有关详细信息，请参阅 应用清单架构。
  • 必须为收件人安装 Teams 应用，无论是个人安装，还是在他们所属的团队或聊天中。

权限

使用委托权限或应用程序权限发送活动源通知。 使用应用程序权限时，建议使用 特定于资源的许可 (RSC) ， TeamsActivity.Send.User 因为用户同意发送活动通知的权限。 确保在应用清单文件中添加 RSC 权限。

应用清单更新

本部分介绍需要添加到应用清单的更新。 确保使用 应用清单 版本 1.7 或更高版本。

"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.7/MicrosoftTeams.schema.json",
"manifestVersion": "1.7",

webApplicationInfo 更新

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}
参数 类型 说明
id string Microsoft Entra应用 ID (客户端 ID) 。
resource string 与 Microsoft Entra 应用关联的资源。 在 Microsoft Azure 门户中也称为回复或重定向 URL。

注意

如果同一范围内的多个 Teams 应用 (团队、聊天或用户) 使用同一Microsoft Entra应用，则可能会收到错误。 请确保使用唯一Microsoft Entra应用。

活动更新

"activities":
{
  "activityTypes": [
    {
      "type": "taskCreated",
      "description": "Task Created Activity",
      "templateText": "{actor} created task {taskId} for you"
    },
    {
      "type": "approvalRequired",
      "description": "Deployment requires your approval",
      "templateText": "{actor} created a new deployment {deploymentId}"
    }
  ]
}
参数 类型 说明
类型 string 活动的类型。 这在特定应用清单中必须是唯一的。
说明 string 人类可读的简短说明。 这在 Teams 客户端上可见。
templateText string 活动通知的模板文本。 可以通过在 中 {}封装参数来添加参数。

注意

  • actor是始终采用调用方名称的特殊参数。 在委托调用中， actor 是用户的名称。 在仅限应用程序的调用中，它采用 Teams 应用的名称。
  • 保留 systemDefault 的活动类型不得包含在 activities 应用清单的 部分中。 活动 systemDefault 类型允许你在活动源通知的行中 Actor+Reason 提供自由格式的文本。

授权更新

"authorization": 
{ 
  "permissions": { 
    "resourceSpecific": [ 
      {
        "type": "Application", 
         "name": "TeamsActivity.Send.User" 
      }, 
      { 
        "type": "Application",
        "name": "TeamsActivity.Send.Group"
      }, 
      { 
        "type": "Application", 
        "name": "TeamsActivity.Send.Chat" 
      } 
    ] 
  }
}
参数 类型 说明
类型 string RSC 权限的类型。
name string RSC 权限的名称。 有关详细信息，请参阅 支持的 RSC 权限。

安装 Teams 应用

Teams 应用必须安装在团队、聊天或个人范围内的用户中，用户才能接收活动源通知。 有关详细信息，请参阅 Teams 应用分发方法。 出于开发目的，我们更喜欢 自定义应用上传。 开发后，可以根据是要分发到一个租户还是所有租户来选择正确的分发方法。

还可以使用 Teams 应用安装 API 来管理 Teams 应用安装。

向用户发送活动源通知

由于 Teams 应用可以为用户安装、在团队中或在聊天中安装，因此它还可以在以下三个上下文中发送通知：

此外，一次最多可以向 100 个用户批量发送通知：

若要查找有关每个方案支持的主题的详细信息，请参阅特定 API。 所有方案都支持基于文本的自定义主题。

可以在以下方案中使用活动源通知：

  • 通知个人需要注意的自定义内容。
  • 在 Tab 应用或 URL 中显示丰富内容。
  • 支持复杂的用户交互。
  • 从发起通知的用户发送委托的通知。
  • 将模板放入应用清单中。
  • Teams 处理通知的本地化。

注意

活动图标基于发出请求的上下文。 如果使用委派的权限发出请求，则用户的照片显示为头像，而 Teams 应用图标显示为活动图标。 在仅限应用程序的上下文中，Teams 应用图标用作头像，并省略活动图标。

自定义通知

Teams 用户可以自定义他们在源或横幅中看到的通知。 还可以自定义通过活动源 API 生成的通知。 用户可以选择如何通过 Teams 中的设置来通知他们。 Teams 应用显示在供用户选择的列表中，如以下屏幕截图所示：

屏幕截图显示了 Teams 中的“通知”设置，其中突出显示了“自定义”选项。

用户可以选择应用旁边的 “编辑” 并自定义通知。 应用清单显示 字段 description 。

屏幕截图显示自定义为 Teams 应用的横幅和源的通知。

示例

有关如何发送活动源通知的示例，请参阅 发送活动源通知示例。

用于发送活动源通知的保留活动类型

  • 活动 systemDefault 类型是保留的，在添加 活动时不能在应用清单中使用。
  • 我们建议使用模板化通知，因为它们依赖于应用清单中的活动模板来定期发送和大量通知。
  • systemDefault即使应用清单中列出了其他活动类型，保留活动类型也可用。

活动类型的优点和限制 systemDefault 如下：

优点 限制
可以测试新方案并试用活动源通知 API，而无需将活动类型添加到应用清单。

使用 Teams 应用商店应用时 systemDefault ，活动类型简化了流程并节省时间，因为它无需对应用清单中的活动类型进行持续调整。 活动 systemDefault 类型已准备就绪，可立即使用。		 不能利用应用清单提供的内置本地化功能。

不能依赖使用活动类型发送可自定义通知 systemDefault 。 用户可以使用 Teams 客户端设置中的切换开关关闭应用的所有通知，这可能会阻碍应用与其用户之间的通信。

代码示例

示例名称 Description .NET Node.js
发送活动源通知 示例应用演示如何使用 Microsoft 图形 API 发送活动源通知。 View View

分步指南

按照 分步指南 在 Teams 中发送活动源通知。

另请参阅