Saturday, August 1, 2020

Simplifying Proactive Messaging in Microsoft Teams with Microsoft Graph's new API permissions

Proactive Messaging enables you to send notifications in Microsoft Teams without user interaction. Basically, a user or team doesn’t need to interact with the bot to receive its notifications. However, this functionality requires the bot to be installed as a personal app or in a team that the user is a member of. Otherwise, the bot doesn’t have the needed information to proactively contact the user.

There has already been guidance explaining how to combine Microsoft Teams with Microsoft Graph to fulfill the installation requirement. Previously, this process had to be executed manually or programmatically using Graph permissions such as User.ReadWrite.All or Directory.ReadWrite.All that allow any application to be installed. In case of users installing the app manually to receive bot notifications, the proactive concept was no longer complete.

The table turns and the process becomes simpler! Microsoft Graph API introduces two new application permissions TeamsAppInstallation.ReadWriteSelfForUser.All and TeamsAppInstallation.ReadWriteSelfForTeam.All. Those new scoped API permissions allow a Teams app to read, install, upgrade, and uninstall ITSELF for any user/team, without a signed-in user 💛 How cool is that!!! This is how it looks in Azure AD:

To use these new permissions, add a webApplicationInfo key to your team’s app manifest. It must include your Azure AD app ID and the resource URL for the app. Ensure your Azure AD app has the application permission that will fulfill your requirement. E. g.: TeamsAppInstallation.ReadWriteSelfForUser.All if you want to manage notifications for users. This is how webApplicationInfo looks:

"webApplicationInfo": {
  "id":"692107eb-eca3-45da-b81b-e336c762d5e4",
  "resource":"api://692107eb-eca3-45da-b81b-e336c762d5e4"
}

Microsoft has also provided detailed information about the usage of this new approach which is still in public preview. Check out this documentation for more information.

I gave this new approach a try with a bot I've been developing at my company and must say that it works very well. Thanks for the Microsoft Graph Teams team for providing us with these two new application permissions 💛