teamwork: sendActivityNotificationToRecipients

Namespace: microsoft.graph

Send activity feed notifications to multiple users, in bulk.

For more information, see sending Teams activity notifications.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) TeamsActivity.Send Not available.
Delegated (personal Microsoft account) Not supported. Not supported.
Application TeamsActivity.Send.User TeamsActivity.Send

Note: The TeamsActivity.Send.User permission uses resource-specific consent. RSC permissions pertain to the individual recipients in the payload.

HTTP request

POST /teamwork/sendActivityNotificationToRecipients

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.

Note: The token provided must be at least 45 minutes from expiry. The API call will return a 412 Precondition Failed response if the token expires within 45 minutes.

Request body

In the request body, supply a JSON representation of the parameters.

The following table shows the parameters that can be used with this action.

Parameter Type Description
topic teamworkActivityTopic The topic of the notification. Specifies the resource being talked about.
activityType String The activity type must be declared in the Teams app manifest, except for the systemDefault Reserved activity type, which provides free-form text in the Actor+Reason line of the notification.
chainId Int64 Optional. The chain ID of the notification. Used to override a previous notification. Use the same chainId in subsequent requests to override the previous notification.
previewText itemBody The preview text for the notification. Microsoft Teams only shows the first 150 characters.
templateParameters keyValuePair collection The values for the template variables defined in the activity feed entry corresponding to activityType in the Teams app manifest.
teamsAppId String Optional. The Teams app ID of the Teams app associated with the notification. Used to disambiguate installed apps when multiple apps with the same Microsoft Entra ID app ID are installed for the same recipient user. Avoid sharing Microsoft Entra ID app IDs between Teams apps.
recipients teamworkNotificationRecipient collection Recipients of the notification. Only recipients of type aadUserNotificationRecipient are supported. There's an upper limit of 100 recipients in a single request.

The following resource is supported when setting the source value of the topic property to entityUrl:

Response

If successful, this action returns a 202 Accepted response code.

Examples

Example 1: Notify multiple users about pending finance approval requests

The following example shows how to send an activity feed notification to multiple users in bulk. This example notifies multiple stakeholders about pending finance approval requests.

Request

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"
        }
    ] 
}

Response

HTTP/1.1 202 Accepted

Example 2: Notify multiple users about an event using a custom topic

If you want to link an aspect that isn't represented by Microsoft Graph, or you want to customize the name, you can set the source of the topic to text and pass in a custom value for it. webUrl is required when using topic source as text.

Request

POST https://graph.microsoft.com/v1.0/teamwork/sendActivityNotificationToRecipients
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"
    },
    "templateParameters": [
        {
            "name": "deploymentId",
            "value": "6788662"
        }
    ],
    "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"
    	}
    ]
}

Response

HTTP/1.1 202 Accepted