Microsoft Graph Mailbag – Create engaging apps with the Microsoft Teams Activity Feed API

Microsoft Graph Mailbag

In today’s Microsoft Graph Mailbag post, we cover the newly released Microsoft Teams Activity Feed API and how it can engage your workforce!

Please be sure to follow this blog series using https://aka.ms/MSGraphMailbag or with RSS using https://developer.microsoft.com/graph/blogs/feed/?tag=MSGraphMailbag.

Introduction

Microsoft Teams has supported activity feed notifications since its inception.  Activity feed notifications are a great tool to understand what you have missed or to find who is mentioning you in channels or teams you are a part of. Now that users are familiar with this capability and know what to expect when they click on a notification, wouldn’t it be great if your custom Teams application could leverage the same behaviors? It’s now possible using the Microsoft Teams Activity Feed API!

It all starts with a Microsoft Teams app

To start leveraging the Activity Feed API, you will need a Microsoft Teams app. You won’t be able to send notifications to users and groups without having a Teams app with some specific settings turned on in your manifest.json.

Your manifest needs to hold two important areas that will make your app “notification aware” and will allow your code to add notifications to users and groups. First, you need to ensure you are running version 1.8 of the Teams manifest. Next, you need to ensure the webApplicationInfo represents the Azure Active Directory application ID you are using to send notifications. Finally, you must identify the types of activities you want to send to Teams. You won’t be able to send a notification that doesn’t match the activities registered in the Teams manifest.

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.8",
  //... Shortened for brevity
  "webApplicationInfo": {
    "id": "b4b9c71b-3303-4973-bc84-bfccec84ed89",
    "resource": "https://localhost:3000"
  },
  "activities": {
    "activityTypes": [
      {
        "type": "sendKudosToUser",
        "description": "Sending Kudos to a user",
        "templateText": "{actor} sent you a Kudos!"
      }
    ]
  }
}

It is very important to ensure the webApplicationInfo is the same ID as your Azure AD application.  If not, you will receive a response similar to the following:

{
  "error": {
    "code": "Forbidden",
    "message": "Application with AAD App Id '749adfd1-5168-42e5-aead-4be32b993892' is not authorized to generate notifications about 'https://graph.microsoft.com/v1.0/chats/19:44bb18e092d841beb4b847f27f2ddba6@thread.v2' to the recipient.",
    "innerError": {
      "date": "2021-04-26T13:18:21",
      "request-id": "d21ed58f-5e0f-46e1-ab5d-408c42aa562b",
      "client-request-id": "d21ed58f-5e0f-46e1-ab5d-408c42aa562b"
    }
  }
}

Getting the right permissions

Before sending any notification to a user, it is important to ensure your application has the right permissions (delegated or application) consented!

  • Read.All : Read all app catalogs (Optional, only used for generic notifications)
  • Send : Send a teamwork activity as the user

Notifying users in a chat

There are three contexts in which you might want to notify a user. The first one might be if you want to send a notification to a user in a chat. This would be a perfect scenario for bots to bring attention to specific areas of a chat or allow more engagement in the discussion. When users receive the notification, they will be redirected to the underlying chat thread.

To achieve this, you need to identify the chatId you are looking for and POST an individual notification to each user of the chat by looping through the chat participants or by sending a JSON batch request to Microsoft Graph.

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": "sendKudosToUser",
  "previewText": {
    "content": "Thanks for your help on this project!"
  },
  "recipient": {
    "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
    "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
  }
}

The result is a brand new notification that brings the user back to the chat:

Notifying users in a team

The second context where you might want to notify a user is within a team. A great scenario is to highlight when a file is updated and to notify the owner of this file in the corresponding team.  Another scenario would be to notify users to send thank you notes on the great work they have been doing with the use of bots or messaging extensions.

To achieve this, you need the teamId where you want to user to navigate after clicking on the notification.

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": "sendKudosToUser",
  "previewText": {
    "content": "Thanks for your help on this project!"
  },
  "recipient": {
    "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
    "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
  }
}

The result is a brand new notification that highlights the team where this is triggered and when clicked, bring the user back to the team:

Notifying a user with a custom entity

The third context is probably the most powerful as it integrates with all custom applications built in Microsoft Teams! You can notify and offer a deep link directly in your application or to an external URL, making this capability very engaging. And, it can integrate with any ISV or line of business (LOB) apps.

To send the right notification, use the following example on the /users endpoint:

POST https://graph.microsoft.com/v1.0/users/{userId}/teamwork/sendActivityNotification
Content-Type: application/json

{

  "topic": {
    "source": "text",
    "value": "Great collaboration",
    "webUrl": "https://teams.microsoft.com/l/entity/{appId}/{tabName}"
  },
  "activityType": "sendKudosToUser",
  "previewText": {
    "content": "Thanks for your help on this project!"
  }
}

Note that you will need to get the Teams application ID (which is not the one from the manifest) and can be achieved by using the following call:

GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{manifestId}'

See the following walkthrough of a custom-built solution leveraging this approach. You can find the solution on Github to start playing with it.

 

Closing note

This new capability is exciting and creates new ways to engage (and re-engage) with your users, all thanks to Microsoft Graph! For more information on the Activity Feed and how to use the API, check out the documentation.

Today’s post was written by Sébastien Levert, Senior Program Manager on the Microsoft Graph team. Join us for our next post May 11, 2021.

Feedback usabilla icon