Building a Microsoft Teams Bot: Posting an Adaptive Card carousel as a welcome message

In November 2020, I was happy to release my side project "Snooze Bot" as a free app on the Microsoft Teams store: https://appsource.microsoft.com/en-us/product/office/WA200002297 

I had been working on it for a few weeks. The fact that all of us were under lockdown gave me some extra time in the evenings and weekends to focus on learning the Microsoft Teams platform and create an app on it which addressed a gap which I noticed in my day to day use. 

We all get a lot of Teams messages daily and need a way to manage them or come back to them at a later time. Snooze bot helps us do exactly that. It lets us Snooze message which we want to deal with later. When a message is snoozed, we get an option to select the duration after which Snooze Bot should remind us about the message. When the time arrives, the bot will send you personal message in teams reminding about the snoozed message.

If you haven't checked out Snooze Bot yet, feel free to install it and give it a try. I am happy to hear any feedback and potential improvements. 

One of my goals when creating the app was to learn about the Microsoft Teams developer platform and also blog about the interesting things I came across. So in this series of posts, let's outline some Microsoft Teams development concepts which I found really useful. The first one being posting an Adaptive Card carousel as a welcome message when the bot is added by the user.

It's always recommended as a good practice to send a welcome message when the user adds the bot. According to the Microsoft docs: 

In personal contexts, welcome messages set your bot's tone. The message includes a greeting, what the bot can do, and some suggestions for how to interact (for example, “Try asking me about …”). If possible, these suggestions should return stored responses without having to sign in.

https://docs.microsoft.com/en-us/microsoftteams/platform/bots/design/bots#introduce-a-bot

Also, sending the welcome message one of the requirements before the app is accepted in AppSource by the validation team.

So we can send a simple chat message from the bot to the user as a welcome message. So why go for an Adaptive Card carousel? This is because adding too much information in a single message can get overwhelming for the user and they might be tempted to just skip it. Also if your bot has a lot of functionality you need a way to efficiently present that information to the user. This is where carousels created by Adaptive Cards some into play:  

So let's have a look at the code which helps us send the welcome message in Snooze Bot

The Adaptive Card json:

First, we need to define the Adaptive cards which will show up in the welcome message. I am storing mine as json files in my solution. The cards contain helpful text and also links to images which show the functionality of Snooze Bot

	{
	"type": "AdaptiveCard",
	"version": "1.2",
	"body": [
	{
	"type": "TextBlock",
	"size": "extraLarge",
	"text": "Snooze Bot"
	},
	{
	"type": "TextBlock",
	"text": "You can use me to snooze teams messages in personal chats, groups chats and channels.",
	"wrap": true
	},
	{
	"type": "Image",
	"url": "https://welcomemessagestrg.blob.core.windows.net/images/welcomeuser.png"
	},
	{
	"type": "TextBlock",
	"text": "Click on the **three dots** next to any Microsoft Teams chat message, then **More actions** and select **Snooze message**",
	"wrap": true
	}
	]
	}

view raw snoozeadaptivecard1.json hosted with ❤ by GitHub

	{
	"type": "AdaptiveCard",
	"version": "1.2",
	"body": [
	{
	"type": "TextBlock",
	"text": "When the selected time arrives, I will send you a personal card reminding you about the snoozed message. From the personal card, either you can go directly to the Teams message or you can snooze the message again",
	"wrap": true
	},
	{
	"type": "Image",
	"url": "https://welcomemessagestrg.blob.core.windows.net/images/welcomeuser2.PNG"
	}
	]
	}

view raw snoozeadaptivecard2.json hosted with ❤ by GitHub

The Bot:

Next, the actual bot code itself. Since I am using .NET Core for this bot we will need the Adaptive cards nuget package:

NuGet Gallery | AdaptiveCards 2.4.0

And here is the code where we do the following things:

1) Capture the OnMembersAddedAsync event from the Bot Framework

2) Get the Adaptive cards from the json files 

3) Insert the adaptive cards into a Bot Framework carousel and send it to the user

	using AdaptiveCards;
	using Microsoft.Bot.Builder;
	using Microsoft.Bot.Builder.Teams;
	using Microsoft.Bot.Schema;
	using System;
	using System.Collections.Generic;
	using System.IO;
	using System.Threading;
	using System.Threading.Tasks;
	namespace TeamsBlogBot
	{
	public class SnoozeBot : TeamsActivityHandler
	{
	//Fired when the Teams app is added by the user
	protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
	{
	foreach (var member in membersAdded)
	{
	//membersAdded also contains the id of the bot. So confirm if the user being added is not the bot itself.
	if (member.Id != turnContext.Activity.Recipient.Id)
	{
	//Create a list out of the Adaptive Cards
	var welcomeAttachments = new List<Attachment>();
	var adaptiveCardAttachment = GetCardAttachment("WelcomeCard1.json");
	welcomeAttachments.Add(adaptiveCardAttachment);
	var adaptiveCardAttachment2 = GetCardAttachment("WelcomeCard2.json");
	welcomeAttachments.Add(adaptiveCardAttachment2);
	//Send the carousel back to Teams
	await turnContext.SendActivityAsync(MessageFactory.Carousel(welcomeAttachments));
	}
	}
	}
	internal Attachment GetCardAttachment(string cardFileName)
	{
	string path = Path.Combine(Environment.CurrentDirectory, @"AdaptiveCardJson\", cardFileName);
	string json = GetCardJSON(path);
	var adaptiveCardResult = AdaptiveCard.FromJson(json);
	return new Attachment
	{
	Content = adaptiveCardResult.Card,
	ContentType = AdaptiveCard.ContentType,
	};
	}
	public static string GetCardJSON(string path)
	{
	if (!File.Exists(path))
	return string.Empty;
	using (var f = File.OpenText(path))
	{
	return f.ReadToEnd();
	}
	}
	}
	}

view raw sendadaptivecardwelcome.cs hosted with ❤ by GitHub

And that's it. Whenever a user will download and install the app, the welcome message will be sent to them introducing your bot and it's funtionality. Hope you found the post useful!

Microsoft 365 multi-tenant apps: Working with application permissions in Microsoft Graph

Creating multi-tenant (SaaS) apps in Microsoft 365 has been possible for a while now. Azure AD multi tenant apps allow us to host our custom applications in an Azure AD/M365 "home" tenant while enabling the apps to also have access to resources hosted in other tenants. To know more about multi-tenant apps, head over to the Microsoft docs: https://docs.microsoft.com/en-in/azure/active-directory/develop/single-and-multi-tenant-apps

Hosting applications in a home tenant as SaaS has a lot of advantages particularly for ISVs when it comes to product based applications. Users are able to consume the apps directly by signing into them instead of the conventional way of an admin having to deploy the product to the customer tenant first. It makes life easy for the admins as well as they don't have to go through complex deployment scripts and instructions. Moreover, after the application is deployed, new features and bug fixes can be rolled out to the application "on the fly" as opposed to releasing feature packs and hotfixes which again have to be installed manually.

So in this post, we are going to have a look at using the Microsoft Graph API in such apps configured to be multi tenant.

(Multi tenant apps also allow users with personal Microsoft accounts to sign into them but that is a topic for another day! Also, in this post we will only focus on the application permissions i.e. granting permissions to applications without a user context)

Configure an app to be a multi-tenant in the home tenant's Azure AD

1) When creating a multitenant app registration, make sure that the "Accounts in any organizational directory" is selected. Also, we need to add a redirect url as this will be the url the admin will be redirected to after successfully granting consent to our application. Ideally, this would be the landing page of your application but in the screenshot I am just using the AAD home as an example:

2) Assign required permissions. In this case, we are going to demo the code to get all the Microsoft 365 Groups on the tenant and also the root SharePoint Online site, so selecting the relevant permissions here:

3) Create a client secret and record it along with the client id. We will need this later in our code.

Granting consent to a multi tenant app in other "consumer" tenant

Next, let's have a look at how the multi tenant app hosted in it's home tenant can be granted permission to access resources in other tenants. 

What we will have to do is to construct a url for admin consent which would be unique to our application. An Azure AD admin of the other tenant will need to navigate to the url and then consent to granting the permissions to our app on the tenant. The Azure AD url will have the following structure:

https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=<replace-with-client-id>&scope=https://graph.microsoft.com/.default

view raw m365multitenantadminconsent.txt hosted with ❤ by GitHub

In the link above, replace the client id with the client id of your multi tenant Azure AD app. Also, notice that we are using the /.default static scope which means that all permissions configured in the app will be requested for consent. 

When the admin navigates to this url, they will see the consent prompt:

Once the consent is granted, the multitenant app will have permissions to access the resources on the other tenant. This can be checked by going to:

Azure Active Directory > Enterprise Applications > All applications and searching for our app there.

This confirms that the multi tenant app has permissions on this tenant. Also this process can be repeated on any number of Azure AD/M365 tenants.

Use the Microsoft Graph API to get Microsoft 365 data from the consumer tenant

With everything setup and also the admin consent granted, let's have a look at the Microsoft Graph code to get data from the consumer tenant.

In this code, I am using the .NET SDK for Microsoft Graph found on nuget here:

Microsoft.Graph

And the new preview version of Microsoft.Graph.Auth found here:

Microsoft.Graph.Auth

And finally here is the code to get all the Microsoft 365 Groups and the SharePoint root site url of the consumer tenant. For the sake of simplicity, I am using a .NET Core console application:

	using Microsoft.Graph;
	using Microsoft.Graph.Auth;
	using Microsoft.Identity.Client;
	using System;
	using System.Threading.Tasks;
	namespace M365.Multitenant.App
	{
	class Program
	{
	static async Task Main(string[] args)
	{
	var clientId = "<client-id>";
	var clientSecret = "<client-secret>";
	var tenantId = "mytenant.onmicrosoft.com"; //Tenant Id of Consumer tenant. This can also be the GUID found in AAD Properties page.
	IConfidentialClientApplication confidentialClientApplication = ConfidentialClientApplicationBuilder
	.Create(clientId)
	.WithTenantId(tenantId)
	.WithClientSecret(clientSecret)
	.Build();
	ClientCredentialProvider authenticationProvider = new ClientCredentialProvider(confidentialClientApplication);
	GraphServiceClient graphServiceClient = new GraphServiceClient(authenticationProvider);
	//Will need at least the Group.Read.All Application permissions on Microsoft Graph resource
	var groups = await graphServiceClient.Groups.Request().GetAsync();
	Console.WriteLine("List of groups on the tenant:");
	foreach (var group in groups)
	{
	Console.WriteLine(group.DisplayName);
	}
	//Will need at least the Sites.Read.All Application permissions on Microsoft Graph resource
	var rootSite = await graphServiceClient.Sites.Root.Request().GetAsync();
	Console.WriteLine($"SharePoint root site url is: {rootSite.WebUrl}");
	}
	}
	}

view raw m365.multitenant.app.graph.cs hosted with ❤ by GitHub

And we are able to get the data from the consumer tenant back:

Thanks for reading! Hope this helps.