通过

聊天：sendActivityNotification

命名空间：microsoft.graph

在聊天范围内发送活动源通知。 有关发送通知的详细信息以及执行此作的要求，请参阅 发送 Teams 活动通知。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） TeamsActivity.Send 不可用。
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 TeamsActivity.Send.Chat TeamsActivity.Send

注意： 权限 TeamsActivity.Send.Chat 使用 特定于资源的许可。

HTTP 请求

POST /chats/{chatId}/sendActivityNotification

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type application/json. 必需。

请求正文

在请求正文中，提供参数的 JSON 表示形式。

下表显示了可用于此操作的参数。

参数 类型 说明
activityType String 活动类型必须在 Teams 应用清单中声明，但保留活动类型除外systemDefault，该类型在通知行中Actor+Reason提供自由格式文本。
chainId Int64 可选。 通知的链 ID。 用于替代以前的通知。 在后续请求中使用相同的 chainId 来覆盖上一个通知。
iconId String 可选。 允许应用按活动类型发送自定义图标的唯一图标 ID。 图标 ID 必须存在于 Teams 应用清单架构中。 如果在清单中指定了图标 ID，但 API 请求正文中缺少该图标，则图标会回退到应用的默认图标。
previewText itemBody 通知的预览文本。 Microsoft Teams 显示前 150 个字符。
recipient teamworkNotificationRecipient 通知的收件人。 有关详细信息，请参阅 aadUserNotificationRecipient 和 chatMembersNotificationRecipient。
teamsAppId String 可选。 与通知关联的 Teams 应用的 Teams 应用 ID。 用于在为同一收件人用户安装多个应用时消除已安装应用Microsoft Entra ID ID 相同的应用时的歧义。 避免在 Teams 应用之间共享Microsoft Entra ID应用 ID。
templateParameters keyValuePair 集合 在 Teams 应用清单中对应于 activityType 的活动源条目中定义的模板变量的值。
topic teamworkActivityTopic 通知的主题。 指定要讨论的资源。

将 topic 属性entityURL的值设置为 source 时，支持以下资源：

注意： 实体 URL 必须与 URL 中聊天的 子资源相同。 此外，必须在聊天中安装 Teams 应用 。

响应

如果成功，此操作返回 204 No Content 响应代码。

示例

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

以下示例演示如何为聊天中创建的新任务发送活动源通知。 有关详细信息，请参阅 发送 Teams 活动通知。

请求

下面为请求示例。

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": "Task 12322"
        }
    ] 
}

响应

以下示例显示了相应的响应。

HTTP/1.1 204 No Content

示例 2：通知用户聊天消息中需要审批

与上一示例类似，此示例对 topic使用 entityUrl 。 但是，在这种情况下，它会链接到聊天中的消息。 邮件可以包含带有审批按钮的卡。

请求

下面为请求示例。

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}/messages/{messageId}"
    },
    "activityType": "approvalRequired",
    "previewText": {
        "content": "Deployment requires your approval"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "approvalTaskId",
            "value": "2020AAGGTAPP"
        }
    ]
}

响应

以下示例显示了相应的响应。

HTTP/1.1 204 No Content

示例 3：使用用户主体名称通知用户在聊天消息中需要审批

与上一示例类似，此示例对 topic使用 entityUrl 。 但是，在这种情况下，它会链接到聊天中的消息。 邮件可以包含带有审批按钮的卡。

请求

下面为请求示例。

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}/messages/{messageId}"
    },
    "activityType": "approvalRequired",
    "previewText": {
        "content": "Deployment requires your approval"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "jacob@contoso.com"
    },
    "templateParameters": [
        {
            "name": "approvalTaskId",
            "value": "2020AAGGTAPP"
        }
    ]
}

响应

以下示例显示了相应的响应。

HTTP/1.1 204 No Content

示例 4：通知用户与聊天相关的事件

如前面的示例所示，可以链接到聊天的不同方面。 但是，如果要链接到不是聊天的一部分或未由 Microsoft Graph 表示的方面，可以将 的topictext源设置为 并为其传入自定义值。 此外， webUrl 在将源设置为 topictext时是必需的。

请求

下面为请求示例。

POST https://graph.microsoft.com/v1.0/chats/{chatId}/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": "deploymentApprovalRequired",
    "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

示例 5：通知聊天成员在聊天中创建的任务

以下示例演示如何向所有聊天成员发送活动源通知。 此示例与前面的示例类似。 但是，在这种情况下， 收件人 是 chatMembersNotificationRecipient。 收件人中指定的 chatId 必须与请求 URL 中指定的 chatId 匹配。

请求

下面为请求示例。

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

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/chats/19:1c3af46e9e0f4a5293343c8813c47619@thread.v2"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.chatMembersNotificationRecipient",
        "chatId": "19:1c3af46e9e0f4a5293343c8813c47619@thread.v2"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "Task 12322"
        }
    ] 
}

响应

以下示例显示了相应的响应。

HTTP/1.1 204 No Content

示例 6：使用自定义图标通知聊天成员有关事件

如果要使用自定义图标而不是默认应用图标通知聊天成员，可以在请求正文中设置可选的 iconId 属性。

注意：activityType清单中的 必须包含允许图标 ID 的列表才能使用此参数。 如果应用清单缺少自定义图标列表，则请求验证失败。 有关详细信息，请参阅 公共开发人员预览版应用清单。

请求

以下示例显示了一个请求。

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

{
  "topic": {
    "source": "entityUrl",
    "value": "https://graph.microsoft.com/v1.0/chats/19:1c3af46e9e0f4a5293343c8813c47619@thread.v2"
  },
  "activityType": "taskCreated",
  "previewText": {
    "content": "new task created"
  },
  "iconId": "taskCreatedIcon",
  "recipient": {
    "@odata.type": "microsoft.graph.chatMembersNotificationRecipient",
    "chatId": "19:1c3af46e9e0f4a5293343c8813c47619@thread.v2"
  },
  "templateParameters": [
    {
      "name": "taskId",
      "value": "Task 12322"
    }
  ]
}

响应

以下示例显示了相应的响应。

HTTP/1.1 204 No Content

相关内容