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

  • 项目

Microsoft Teams 活动源会通知用户更改，使他们能够对需要注意的项目进行会审。 Teams 中的活动源通知包括以下功能：

  • 与 Teams 的本机集成，使用户无缝地进入选项卡应用，并从“Teams 活动 ”窗格向应用提供额外的用户参与。
  • Teams 桌面和移动客户端中的操作系统通知，其中包含弹出窗口和声音。
  • 可自定义的通知内容，使你能够向用户显示更多或更少的预览内容。
  • 能够将选项卡、个人应用、机器人消息或自适应卡片深层链接到通知，以提高用户对应用的参与度。
  • 能够向多个收件人发送活动源通知，例如向一组用户发送批量通知。

可以使用 Microsoft Graph 中的活动源通知 API 将此功能扩展到应用。 通过这种方式，你可以提供更丰富的体验，并通过帮助他们及时了解他们所使用的工具和工作流的更改来吸引用户。

Microsoft Graph 中的活动源通知 API 支持以下用例：

  • 新闻 - 让用户随时了解最新信息，例如新作业或新帖子。
  • 协作 - 当用户共享文件或在评论中 @ 提及时，在通知横幅中向用户显示预览。
  • 提醒 - 向用户发送有关事件或任务的通知。
  • 警报 - 发送需要紧急或立即关注的通知，例如过期截止日期或高优先级工作项。

可以使用活动源通知执行以下操作：

  • 通知个人需要注意的自定义内容。
  • 在选项卡应用或 URL 中显示丰富内容。
  • 支持复杂的用户交互。
  • 从发起通知的用户发送委托的通知。

Teams 处理通知的本地化。

活动源通知的组件

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

显示活动源通知的组件的图像，包括参与者、原因、时间戳、预览和主题。

下表介绍了这些组件。

组件 说明
化身 显示发起活动的人员。
活动类型或应用图标 活动的类型。 对于应用通知，行图标将替换为应用图标。
标题：Actor + reason Actor 是启动活动的用户或应用的名称。 原因 描述活动。
Timestamp 显示活动发生的时间。
文本预览 显示通知开头的截断行。
主题 请求正文中主题的关联资源或文本值。

下图显示了 Teams 中的活动源通知示例。 在此示例中，用户共享了应用中的帖子。

Yammer 活动源通知的图像

活动源通知卡的类型

以下选项卡显示可以显示的活动源通知卡的类型。 对于应用生成的通知，用户徽标将替换为应用徽标。

Teams 自定义

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

Windows

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

Mac

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

使用活动源通知 API 的要求

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

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

      注意

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

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

权限

可以使用委托权限或应用程序权限发送活动通知。 使用应用程序权限时，建议使用 特定于资源的许可 (RSC) ， TeamsActivity.Send.User 因为该权限允许用户同意发送活动通知。 必须在 Teams 应用 清单架构中声明 RSC 权限。

Teams 应用清单更新

本部分介绍实现活动源通知需要对 Teams 应用清单所做的更改。 需要使用 Teams 应用清单 版本 1.7 或更高版本。

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

webApplicationInfo 更新

必须在应用清单webApplicationInfo属性中更新Microsoft Entraid和resource信息。

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

注意

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

活动更新

必须在应用清单中定义 activities 属性才能发布用户活动源。

"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 人类可读的简短说明。 说明在 Microsoft Teams 客户端上可见。
templateText string 活动通知的模板文本。 可以通过将参数封装在大括号 {}中来声明参数。

注意

  • actor 是始终采用调用方名称的特殊参数。 在委托调用中， actor 是用户的名称。 在仅限应用程序的调用中，它采用 Teams 应用的名称。

  • 不应在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 应用安装。

向用户发送活动源通知

注意

若要在 iOS 和 Android 客户端上显示活动源通知，必须将该应用包含在允许列表中。 仅支持第三方应用。

由于 Teams 应用可以为用户安装、在团队中或在聊天中安装，因此可以在三个上下文中发送通知。 有关如何在每个上下文中发送通知的详细信息，请参阅以下主题：

此外，一次最多可以向 100 个用户批量发送通知。 有关详细信息，请参阅以下主题：

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

注意

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

示例 1：通知用户在聊天中创建的任务

以下示例演示如何为聊天中创建的新任务发送活动源通知。 在这种情况下，Teams 应用必须安装在具有 ID chatId 的聊天中，并且用户 569363e2-4e49-4661-87f2-16f245c5d66a 也必须是聊天的一部分。

请求

POST https://graph.microsoft.com/v1.0/chats/{chatId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/chats/{chatId}"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

响应

HTTP/1.1 204 No Content

示例 2：通知用户在团队中创建的任务

以下示例演示如何为团队发送活动源通知。 此示例通知团队所有者创建的新任务需要他们注意。

请求

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/{teamId}"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

响应

HTTP/1.1 204 No Content

示例 3：使用自定义主题通知用户有关事件

如前面的示例所示，可以链接到不同的团队或聊天方面。 但是，如果要链接到不属于团队的某个方面，或者 Microsoft Graph 不表示该方面，或者如果要自定义名称，则可以将 的源topictext设置为 并为其传递自定义值。 此外， webUrl 在将 topic 源用作 text时是必需的。

前面显示的 Yammer 通知示例使用自定义主题，因为 Microsoft Graph 不支持 Yammer 的资源。

注意

webUrl 必须从 Microsoft Teams 域 (teams.microsoft.com 开始，例如) 。

请求

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Deployment Approvals Channel",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "activityType": "approvalRequired",
    "previewText": {
        "content": "New deployment requires your approval"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "deploymentId",
            "value": "6788662"
        }
    ]
}

响应

HTTP/1.1 204 No Content

示例 4：通知团队成员有关事件

以下示例演示如何向所有团队成员发送活动源通知。 本示例通知团队成员有关新事件的信息。

请求

POST https://graph.microsoft.com/v1.0/teams/7155e3c8-175e-4311-97ef-572edc3aa3db/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.teamMembersNotificationRecipient",
        "teamId": "7155e3c8-175e-4311-97ef-572edc3aa3db"
    }
}

响应

HTTP/1.1 204 No Content

示例 5：通知频道成员有关事件

以下示例演示如何向所有频道成员发送活动源通知。 本示例通知频道成员有关新事件的信息。

请求

POST https://graph.microsoft.com/v1.0/teams/7155e3c8-175e-4311-97ef-572edc3aa3db/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.channelMembersNotificationRecipient",
        "teamId": "7155e3c8-175e-4311-97ef-572edc3aa3db",
        "channelId": "19:0ea5de04de4743bcb4cd20cb99235d99@thread.tacv2"
    }
}

响应

HTTP/1.1 204 No Content

示例 6：通知聊天成员有关事件

以下示例演示如何向所有聊天成员发送活动源通知。 本示例通知聊天成员有关新事件的信息。

请求

POST https://graph.microsoft.com/v1.0/chats/19:d65713bc498c4a428c71ef9353e6ce20@thread.v2/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.chatMembersNotificationRecipient",
        "chatId": "19:d65713bc498c4a428c71ef9353e6ce20@thread.v2"
    }
}

响应

HTTP/1.1 204 No Content

示例 7：通知多个用户有关待处理的财务审批请求

以下示例演示如何批量向多个用户发送活动源通知。 此示例通知多个利益干系人有关待处理的财务审批请求。

请求

POST https://graph.microsoft.com/v1.0/teamwork/sendActivityNotificationToRecipients
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipients": [
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
        },
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "ab88234e-0874-477c-9638-d144296ed04f"
        },
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "01c64f53-69aa-42c7-9b7f-9f75195d6bfc"
        }
    ],
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

响应

HTTP/1.1 202 Accepted

示例 8：使用 systemDefault 活动类型向用户发送通知

以下示例演示如何在没有清单中定义的活动类型的情况下为团队发送活动通知。 你可以在此处灵活提供自由格式文本。 有关详细信息，请参阅 保留活动类型。

注意

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

此示例通知团队所有者稍作休息。 value修改 中的 templateParameters 以自定义各种方案的通知。

请求

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/{teamId}"
    },
    "activityType": "systemDefault",
    "previewText": {
        "content": "Take a break"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "systemDefaultText",
            "value": "You need to take a short break"
        }
    ]
}

响应

HTTP/1.1 204 No Content

保留的活动类型

活动 systemDefault 类型是保留的，声明 活动时不能在清单中使用。 可以使用 systemDefault 活动类型来：

  • 轻松测试新方案和/或快速尝试活动源通知 API，而无需在应用清单中定义活动类型。
  • 对于应用商店应用，可以节省时间并简化流程，因为无需在应用清单中不断调整活动类型。 活动 systemDefault 类型已准备就绪，可从获取使用。

请记住，使用 systemDefault 活动类型时，无法：

  • 利用清单提供的内置本地化功能。
  • 依赖于使用活动类型发送可自定义的 systemDefault 通知。 用户可以使用 Microsoft Teams 客户端设置中的切换开关关闭应用的所有通知，这可能会阻碍你的应用与其用户之间的通信。

对于定期通知和大批量通知，我们仍建议使用模板化通知，因为它们需要在清单中使用活动模板。

systemDefault与应用清单中列出的活动类型无关，保留的活动类型仍然可用。

自定义通知的警报方式

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

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

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

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

常见问题解答

谁需要安装 Teams 应用？

目标用户必须安装发送通知的 Teams 应用。

用户是否可以向自己发送通知？

否，用户无法向自己发送通知。 对于此方案，请使用应用程序权限。

Teams 应用能否控制向用户显示通知的方式？

否，仅允许用户更改通知设置。

我安装了我的应用;为什么我在用户帐户下看不到通知设置？

Teams 应用发送第一个通知后，将显示这些设置。 这可以减少用户看到的设置数。

我开始收到 409 (冲突) 错误;如何解决此问题？

Conflict当在同一范围内安装的多个 Teams 应用 (团队、聊天、用户等，) 清单部分中具有相同Microsoft Entra appId webApplicationInfo 时，主要会发生错误。 发生这种情况时，会收到类似 Found multiple applications with the same Microsoft Entra App ID 'Your Microsoft Entra AppId'.的错误。 确保对唯一的 Teams 应用使用唯一Microsoft Entra应用。 可以在多个范围内安装同一个 Teams 应用， (团队 + 用户，例如) 。

相关内容