Send activity feed notifications to users in Microsoft Teams
Article
The Microsoft Teams activity feed enables users to triage items that require attention by notifying them of changes. You can use the activity feed notification APIs in Microsoft Graph to extend this functionality to your apps. This allows your apps to provide richer experiences and better engage users by helping to keep them up to date with changes in the tools and workflows they use.
Understand the basics of activity feed notification
Activity feed notifications in Microsoft Teams are comprised of multiple bits of information, displayed together, as shown in the following image.
The components include:
The actor who initiated the activity
An icon that represents the activity type
The reason the actor did the activity
A text preview
A time stamp
The location of the activity
The following example shows how these components together provide the details about a notification. This example is a notification about a user mentioned in a Yammer community.
Requirements for using the activity feed notification APIs
Activity feed APIs work with a Teams app. The following are the requirements for sending activity feed notifications:
The Teams app manifest must have the Azure AD app ID added to the webApplicationInfo section. For details, see manifest schema.
Activity types must be declared in the activities section. For details, see manifest schema.
The Teams app must be installed for the recipient, either personally, or in a team or chat they are part of. For more information, see Teams app installation.
Teams app manifest changes
This section describes the changes that need to be added to Teams app manifest. Note that you must be using the Teams app manifest version 1.7 or greater.
Resource associated with the Azure AD app. Also known as reply or redirect URL in the Azure Portal.
Note
You might get an error if multiple Teams apps in the same scope (team, chat or user) are using the same Azure AD app. Make sure that you're using unique Azure AD apps.
activities section changes
"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}"
}
]
}
Parameter
Type
Description
type
string
Type of activity. This needs to be unique in a specific manifest.
description
string
Human-readable short description. This will be visible on the Microsoft Teams client.
templateText
string
Template text for the activity notification. You can declare your parameters by encapsulating parameters in {}.
Note
actor is a special parameter that always takes the name of the caller. In delegated calls, actor is the user's name. In application-only calls, it takes the name of the Teams app.
Install the Teams app
Teams apps can be installed in a team, a chat, or for a user personally, and can be distributed in multiple ways. For details, see Teams app distribution methods. Typically, sideloading is preferred for development purposes. After development, you can choose the right distribution method based on whether you want to distribute to one tenant or to all tenants.
For details about what topics are supported for each scenario, see the specific APIs. Custom text-based topics are supported for all scenarios.
Note
The activity icon is based on the context the request is made in. If the request is made with delegated permissions, the user's photo appears as the avatar, while the Teams app icon appears as the activity icon. In an application-only context, the Teams app icon is used as the avatar and the activity icon is omitted.
Example 1: Notify a user about a task created in a chat
This example shows how you can send an activity feed notification for a new task created in a chat. In this case, the Teams app must be installed in a chat with Id chatId and user 569363e2-4e49-4661-87f2-16f245c5d66a must be part of the chat as well.
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Microsoft.Graph.Chats.Item.SendActivityNotification.SendActivityNotificationPostRequestBody
{
Topic = new TeamworkActivityTopic
{
Source = TeamworkActivityTopicSource.EntityUrl,
Value = "https://graph.microsoft.com/v1.0/chats/{chatId}",
},
ActivityType = "taskCreated",
PreviewText = new ItemBody
{
Content = "New Task Created",
},
Recipient = new TeamworkNotificationRecipient
{
OdataType = "microsoft.graph.aadUserNotificationRecipient",
AdditionalData = new Dictionary<string, object>
{
{
"userId" , "569363e2-4e49-4661-87f2-16f245c5d66a"
},
},
},
TemplateParameters = new List<KeyValuePair>
{
new KeyValuePair
{
Name = "taskId",
Value = "12322",
},
},
};
await graphClient.Chats["{chat-id}"].SendActivityNotification.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new SendActivityNotificationPostRequestBody();
$topic = new TeamworkActivityTopic();
$topic->setSource(new TeamworkActivityTopicSource('entityurl'));
$topic->setValue('https://graph.microsoft.com/v1.0/chats/{chatId}');
$requestBody->setTopic($topic);
$requestBody->setActivityType('taskCreated');
$previewText = new ItemBody();
$previewText->setContent('New Task Created');
$requestBody->setPreviewText($previewText);
$recipient = new TeamworkNotificationRecipient();
$recipient->set@odatatype('microsoft.graph.aadUserNotificationRecipient');
$additionalData = [
'userId' => '569363e2-4e49-4661-87f2-16f245c5d66a',
];
$recipient->setAdditionalData($additionalData);
$requestBody->setRecipient($recipient);
$templateParametersKeyValuePair1 = new KeyValuePair();
$templateParametersKeyValuePair1->setName('taskId');
$templateParametersKeyValuePair1->setValue('12322');
$templateParametersArray []= $templateParametersKeyValuePair1;
$requestBody->setTemplateParameters($templateParametersArray);
$graphServiceClient->chats()->byChatId('chat-id')->sendActivityNotification()->post($requestBody);
Example 2: Notify a user about a task created in a team
This example shows how you can send an activity feed notification for a team. This example notifies the team owner about a new task created that requires their attention.
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Microsoft.Graph.Teams.Item.SendActivityNotification.SendActivityNotificationPostRequestBody
{
Topic = new TeamworkActivityTopic
{
Source = TeamworkActivityTopicSource.EntityUrl,
Value = "https://graph.microsoft.com/v1.0/teams/{teamId}",
},
ActivityType = "taskCreated",
PreviewText = new ItemBody
{
Content = "New Task Created",
},
Recipient = new TeamworkNotificationRecipient
{
OdataType = "microsoft.graph.aadUserNotificationRecipient",
AdditionalData = new Dictionary<string, object>
{
{
"userId" , "569363e2-4e49-4661-87f2-16f245c5d66a"
},
},
},
TemplateParameters = new List<KeyValuePair>
{
new KeyValuePair
{
Name = "taskId",
Value = "12322",
},
},
};
await graphClient.Teams["{team-id}"].SendActivityNotification.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new SendActivityNotificationPostRequestBody();
$topic = new TeamworkActivityTopic();
$topic->setSource(new TeamworkActivityTopicSource('entityurl'));
$topic->setValue('https://graph.microsoft.com/v1.0/teams/{teamId}');
$requestBody->setTopic($topic);
$requestBody->setActivityType('taskCreated');
$previewText = new ItemBody();
$previewText->setContent('New Task Created');
$requestBody->setPreviewText($previewText);
$recipient = new TeamworkNotificationRecipient();
$recipient->set@odatatype('microsoft.graph.aadUserNotificationRecipient');
$additionalData = [
'userId' => '569363e2-4e49-4661-87f2-16f245c5d66a',
];
$recipient->setAdditionalData($additionalData);
$requestBody->setRecipient($recipient);
$templateParametersKeyValuePair1 = new KeyValuePair();
$templateParametersKeyValuePair1->setName('taskId');
$templateParametersKeyValuePair1->setValue('12322');
$templateParametersArray []= $templateParametersKeyValuePair1;
$requestBody->setTemplateParameters($templateParametersArray);
$graphServiceClient->teams()->byTeamId('team-id')->sendActivityNotification()->post($requestBody);
Example 3: Notify a user about an event using a custom topic
As seen in the previous examples, you can link to different aspects of a team or a chat. However, if you want to link to an aspect that is not part of the team or is not represented by Microsoft Graph, or if you want to customize the name, you can set the source of the topic to text and pass in a custom value for it. Additionally, webUrl is required when you use topic source as text.
The Yammer notification example shown earlier uses a custom topic because Yammer's resources are not supported by Microsoft Graph.
Note
webUrl must start with the Microsoft Teams domain (teams.microsoft.com for example).
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Microsoft.Graph.Teams.Item.SendActivityNotification.SendActivityNotificationPostRequestBody
{
Topic = new TeamworkActivityTopic
{
Source = TeamworkActivityTopicSource.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 = new ItemBody
{
Content = "New deployment requires your approval",
},
Recipient = new TeamworkNotificationRecipient
{
OdataType = "microsoft.graph.aadUserNotificationRecipient",
AdditionalData = new Dictionary<string, object>
{
{
"userId" , "569363e2-4e49-4661-87f2-16f245c5d66a"
},
},
},
TemplateParameters = new List<KeyValuePair>
{
new KeyValuePair
{
Name = "deploymentId",
Value = "6788662",
},
},
};
await graphClient.Teams["{team-id}"].SendActivityNotification.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new SendActivityNotificationPostRequestBody();
$topic = new TeamworkActivityTopic();
$topic->setSource(new TeamworkActivityTopicSource('text'));
$topic->setValue('Deployment Approvals Channel');
$topic->setWebUrl('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');
$requestBody->setTopic($topic);
$requestBody->setActivityType('approvalRequired');
$previewText = new ItemBody();
$previewText->setContent('New deployment requires your approval');
$requestBody->setPreviewText($previewText);
$recipient = new TeamworkNotificationRecipient();
$recipient->set@odatatype('microsoft.graph.aadUserNotificationRecipient');
$additionalData = [
'userId' => '569363e2-4e49-4661-87f2-16f245c5d66a',
];
$recipient->setAdditionalData($additionalData);
$requestBody->setRecipient($recipient);
$templateParametersKeyValuePair1 = new KeyValuePair();
$templateParametersKeyValuePair1->setName('deploymentId');
$templateParametersKeyValuePair1->setValue('6788662');
$templateParametersArray []= $templateParametersKeyValuePair1;
$requestBody->setTemplateParameters($templateParametersArray);
$graphServiceClient->teams()->byTeamId('team-id')->sendActivityNotification()->post($requestBody);
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Microsoft.Graph.Teams.Item.SendActivityNotification.SendActivityNotificationPostRequestBody
{
Topic = new TeamworkActivityTopic
{
Source = TeamworkActivityTopicSource.Text,
Value = "Weekly Virtual Social",
WebUrl = "Teams webUrl",
},
PreviewText = new ItemBody
{
Content = "It will be fun!",
},
ActivityType = "eventCreated",
Recipient = new TeamworkNotificationRecipient
{
OdataType = "microsoft.graph.teamMembersNotificationRecipient",
AdditionalData = new Dictionary<string, object>
{
{
"teamId" , "7155e3c8-175e-4311-97ef-572edc3aa3db"
},
},
},
};
await graphClient.Teams["{team-id}"].SendActivityNotification.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new SendActivityNotificationPostRequestBody();
$topic = new TeamworkActivityTopic();
$topic->setSource(new TeamworkActivityTopicSource('text'));
$topic->setValue('Weekly Virtual Social');
$topic->setWebUrl('Teams webUrl');
$requestBody->setTopic($topic);
$previewText = new ItemBody();
$previewText->setContent('It will be fun!');
$requestBody->setPreviewText($previewText);
$requestBody->setActivityType('eventCreated');
$recipient = new TeamworkNotificationRecipient();
$recipient->set@odatatype('microsoft.graph.teamMembersNotificationRecipient');
$additionalData = [
'teamId' => '7155e3c8-175e-4311-97ef-572edc3aa3db',
];
$recipient->setAdditionalData($additionalData);
$requestBody->setRecipient($recipient);
$graphServiceClient->teams()->byTeamId('team-id')->sendActivityNotification()->post($requestBody);
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Microsoft.Graph.Teams.Item.SendActivityNotification.SendActivityNotificationPostRequestBody
{
Topic = new TeamworkActivityTopic
{
Source = TeamworkActivityTopicSource.Text,
Value = "Weekly Virtual Social",
WebUrl = "Teams webUrl",
},
PreviewText = new ItemBody
{
Content = "It will be fun!",
},
ActivityType = "eventCreated",
Recipient = new TeamworkNotificationRecipient
{
OdataType = "microsoft.graph.channelMembersNotificationRecipient",
AdditionalData = new Dictionary<string, object>
{
{
"teamId" , "7155e3c8-175e-4311-97ef-572edc3aa3db"
},
{
"channelId" , "19:0ea5de04de4743bcb4cd20cb99235d99@thread.tacv2"
},
},
},
};
await graphClient.Teams["{team-id}"].SendActivityNotification.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new SendActivityNotificationPostRequestBody();
$topic = new TeamworkActivityTopic();
$topic->setSource(new TeamworkActivityTopicSource('text'));
$topic->setValue('Weekly Virtual Social');
$topic->setWebUrl('Teams webUrl');
$requestBody->setTopic($topic);
$previewText = new ItemBody();
$previewText->setContent('It will be fun!');
$requestBody->setPreviewText($previewText);
$requestBody->setActivityType('eventCreated');
$recipient = new TeamworkNotificationRecipient();
$recipient->set@odatatype('microsoft.graph.channelMembersNotificationRecipient');
$additionalData = [
'teamId' => '7155e3c8-175e-4311-97ef-572edc3aa3db',
'channelId' => '19:0ea5de04de4743bcb4cd20cb99235d99@thread.tacv2',
];
$recipient->setAdditionalData($additionalData);
$requestBody->setRecipient($recipient);
$graphServiceClient->teams()->byTeamId('team-id')->sendActivityNotification()->post($requestBody);
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Microsoft.Graph.Chats.Item.SendActivityNotification.SendActivityNotificationPostRequestBody
{
Topic = new TeamworkActivityTopic
{
Source = TeamworkActivityTopicSource.Text,
Value = "Weekly Virtual Social",
WebUrl = "Teams webUrl",
},
PreviewText = new ItemBody
{
Content = "It will be fun!",
},
ActivityType = "eventCreated",
Recipient = new TeamworkNotificationRecipient
{
OdataType = "microsoft.graph.chatMembersNotificationRecipient",
AdditionalData = new Dictionary<string, object>
{
{
"chatId" , "19:d65713bc498c4a428c71ef9353e6ce20@thread.v2"
},
},
},
};
await graphClient.Chats["{chat-id}"].SendActivityNotification.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new SendActivityNotificationPostRequestBody();
$topic = new TeamworkActivityTopic();
$topic->setSource(new TeamworkActivityTopicSource('text'));
$topic->setValue('Weekly Virtual Social');
$topic->setWebUrl('Teams webUrl');
$requestBody->setTopic($topic);
$previewText = new ItemBody();
$previewText->setContent('It will be fun!');
$requestBody->setPreviewText($previewText);
$requestBody->setActivityType('eventCreated');
$recipient = new TeamworkNotificationRecipient();
$recipient->set@odatatype('microsoft.graph.chatMembersNotificationRecipient');
$additionalData = [
'chatId' => '19:d65713bc498c4a428c71ef9353e6ce20@thread.v2',
];
$recipient->setAdditionalData($additionalData);
$requestBody->setRecipient($recipient);
$graphServiceClient->chats()->byChatId('chat-id')->sendActivityNotification()->post($requestBody);
Example 7: 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.
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Microsoft.Graph.Teamwork.SendActivityNotificationToRecipients.SendActivityNotificationToRecipientsPostRequestBody
{
Topic = new TeamworkActivityTopic
{
Source = TeamworkActivityTopicSource.EntityUrl,
Value = "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}",
},
ActivityType = "pendingFinanceApprovalRequests",
PreviewText = new ItemBody
{
Content = "Internal spending team has a pending finance approval requests",
},
Recipients = new List<TeamworkNotificationRecipient>
{
new TeamworkNotificationRecipient
{
OdataType = "microsoft.graph.aadUserNotificationRecipient",
AdditionalData = new Dictionary<string, object>
{
{
"userId" , "569363e2-4e49-4661-87f2-16f245c5d66a"
},
},
},
new TeamworkNotificationRecipient
{
OdataType = "microsoft.graph.aadUserNotificationRecipient",
AdditionalData = new Dictionary<string, object>
{
{
"userId" , "ab88234e-0874-477c-9638-d144296ed04f"
},
},
},
new TeamworkNotificationRecipient
{
OdataType = "microsoft.graph.aadUserNotificationRecipient",
AdditionalData = new Dictionary<string, object>
{
{
"userId" , "01c64f53-69aa-42c7-9b7f-9f75195d6bfc"
},
},
},
},
TemplateParameters = new List<KeyValuePair>
{
new KeyValuePair
{
Name = "pendingRequestCount",
Value = "5",
},
},
};
await graphClient.Teamwork.SendActivityNotificationToRecipients.PostAsync(requestBody);
Microsoft Teams users can customize the notifications they see in their feed, as a banner, and so on. Notifications generated through activity feed APIs can also be customized. Users can choose how they are notified via settings in Microsoft Teams. Teams apps will appear in the list for the user to choose from, as shown in the following screenshot.
Users can click Edit next to an app and customize the notifications, as shown in the following example. The description field in the Teams app manifest is displayed.
FAQs
Who needs to install the Teams app?
The target user must have the Teams app that is sending notifications installed.
Can a user send notifications to themselves?
No, a user cannot send notifications to themselves. For this scenario, use application permissions.
Can a Teams app control how the notifications are shown to the user?
No, only users are allowed to change notification settings.
I installed my app; why don't I see notification settings under the user account?
The settings will appear after the first notification is sent by the Teams app. This reduces the number of settings that users see.
I started getting a 409 (conflict) error; how do I resolve it?
Conflict errors primarily occur when multiple Teams apps installed in the same scope (team, chat, user, and so on) have the same Azure AD appId in the webApplicationInfo section of the manifest. When this happens, you will get an error such as Found multiple applications with the same Azure AD App ID 'Your AzureAD AppId'.. Make sure that you use unique Azure AD apps for unique Teams apps. Note that you can have the same Teams app installed in multiple scopes (team + user for example).