Edit

Share via

team: sendActivityNotification

  • Article

Namespace: microsoft.graph

Send an activity feed notification in the scope of a team. For more information about sending notifications and the requirements for doing so, 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.Group TeamsActivity.Send

Note

The TeamsActivity.Send.Group permission uses resource-specific consent.

HTTP request

POST /teams/{teamId}/sendActivityNotification

Request headers

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

Request body

In the request body, supply 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 for 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 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.
recipient teamworkNotificationRecipient The recipient of the notification. For more information, see aadUserNotificationRecipient, channelMembersNotificationRecipient, and teamMembersNotificationRecipient.
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.

The following resources are supported when setting the source value of the topic property to entityUrl:

Note: The entity URL must be same or child resource of the team in the URL. Additionally, the Teams app must be installed in the team.

Response

If successful, this action returns a 204 No Content response code.

Examples

Example 1: Notify a user about pending finance approval requests

This example shows how you can send an activity feed notification for a team. This example notifies the team owner about pending finance approval requests.

Request

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": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Response

HTTP/1.1 204 No Content

Example 2: Notify a user about a channel tab

Similar to the previous example, this example uses entityUrl for the topic. However, this example links to a tab in a channel. The tab hosts a page showing the user the status of their hotel reservation. Selecting the notification takes the user to the tab, where they can check their reservation.

Request

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}/channels/{channelId}/tabs/{tabId}"
    },
    "activityType": "reservationUpdated",
    "previewText": {
        "content": "You have moved up the queue"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "reservationId",
            "value": "TREEE433"
        },
        {
            "name": "currentSlot",
            "value": "23"
        }
    ]
}

Response

HTTP/1.1 204 No Content

Example 3: Notify a user about a channel tab using user principal name

Similar to the previous example, this example uses entityUrl for the topic. However, this example links to a tab in a channel. The tab hosts a page showing the user the status of their hotel reservation. Selecting the notification takes the user to the tab, where they can check their reservation.

Request

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}/channels/{channelId}/tabs/{tabId}"
    },
    "activityType": "reservationUpdated",
    "previewText": {
        "content": "You have moved up the queue"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "jacob@contoso.com"
    },
    "templateParameters": [
        {
            "name": "reservationId",
            "value": "TREEE433"
        },
        {
            "name": "currentSlot",
            "value": "23"
        }
    ]
}

Response

HTTP/1.1 204 No Content

Example 4: Notify a user about an event using custom topic

As seen in the previous examples, you can link to different aspects of the team. However, if you want to link to an aspect that isn't part of the team or 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 setting topic source to text.

Request

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

Response

HTTP/1.1 204 No Content

Example 5: Notify the team members about pending finance approval requests

The following example shows how you can send an activity feed notification to all team members. This example is similar to previous examples. However, in this case, the recipient is a teamMembersNotificationRecipient. The teamId specified in the recipient must match the teamId specified in the request URL.

Note: The ability to send notifications to all team members is limited to teams with 10,000 members or less. If the team exceeds 10,000 members, none of the team members will receive a notification.

Request

The following example shows the request.

POST https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.teamMembersNotificationRecipient",
        "teamId": "e8bece96-d393-4b9b-b8da-69cedef1a7e7"
    },
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Response

The following example shows the response.

HTTP/1.1 204 No Content

Example 6: Notify the channel members about pending finance approval requests

The following example shows how you can send an activity feed notification to all channel members. This example is similar to the previous example. However, in this case, the recipient is a channelMembersNotificationRecipient. The teamId specified in the recipient must match the teamId specified in the request URL.

Request

The following example shows the request.

POST https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.channelMembersNotificationRecipient",
        "teamId": "e8bece96-d393-4b9b-b8da-69cedef1a7e7",
        "channelId": "19:3d61a2309f094f4a9310b20f1db37520@thread.tacv2"
    },
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

Response

The following example shows the response.

HTTP/1.1 204 No Content

Example 7: Notify about pending finance approval requests in channel message reply location

Similar to the previous example, this example uses entityUrl for the topic. However, this example links to a channel message reply. The channel message reply shows the status of the user's hotel reservation. Selecting the notification takes the user to the reply message in the channel, where they can check their reservation status.

Request

The following example shows the request.

POST https://graph.microsoft.com/v1.0/teams/e8bece96-d393-4b9b-b8da-69cedef1a7e7/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/beta/teams/{teamId}/channels/{channelId}/messages/{messageId}/replies/{replyId}"
    },
    "activityType": "reservationStatusUpdated",
    "previewText": {
        "content": "You have moved up the queue"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "jacob@contoso.com"
    },
    "templateParameters": [
        {
            "name": "reservationId",
            "value": "TREEE433"
        },
        {
            "name": "currentSlot",
            "value": "23"
        }
    ]
}

Response

The following example shows the response.

HTTP/1.1 204 No Content

Related content