Build A Microsoft Teams Bot with Adaptive Cards
Hello everyone, Welcoming all of you to my first blog post and I hope it’ll help you to make your own bots.
So in the past few months I have been involved in a project where a Microsoft teams bot was developed using Asp .NET Core and the Microsoft Bot Framework. Here are some of the stuff I learnt during the development of which I thought I would share with you guys.
Firstly let me give you a brief introduction of Microsoft Bots. Microsoft Teams has it’s own application portal through which you can install various different types of applications and integrate them within your Microsoft Teams groups for efficiency. These application comes in five different forms which are namely Tabs, Messaging Extensions, Bots, Web-hooks and Microsoft Graphs. Hence Microsoft Bot is a smart application which allows users of your organization or members of your team to connect and conversate with your private web services or APIs through your customized bot.
Microsoft bots are really easy to build. The bots can be of different categories as well; Such like Proactive bots : Where the bots sends a message to the user before the user interacts with the bot, QnA bots : Where the bot answers your questions in a professional or friendly manner etc. You can build your bot in any possible manner of how you want it to respond when called upon.
Let’s get started :
Any application will have a front-end and a back-end. Hence the front-end component of the Microsoft QnA Bot of which I will demonstrate here will be written from Json. Yes, the bot builder framework has it’s own frontend component and it is called Cards which allows us to create more rich and responsive reply messages from the bot rather than just plain text. Cards are of many types as well these can be Adaptive cards, Thumbnail Cards, Hero Card etc. I believe a choosing an adaptive card template and editing it to suit your purpose will be the easiest.
Designing Adaptive Cards
Option 1 : Designer | Adaptive Cards , this website is the official website for adaptive cards which has it’s own inbuilt designer tab through which you can design your front-end adaptive card and view it.
As you can see you can edit the front-end adaptive card by adding text boxes, columns, choice sets, input boxes, calendars etc.
Option 2: This is the option which I use because you can right away edit the card and view it on Microsoft Teams by getting it as a message reply. First head to Microsoft teams and search up app studio from your Microsoft Applications. Head onto Card editor and create any kind of card you would like your bot to return to you. It is recommended to make adaptive cards as they support both mobile and web/desktop applications.
The cards utilize a JSON format hence by editing the code you can see all changes in the left side. Furthermore, by clicking on “Send me this card” option you can directly see how a user sees the card in the actual Microsoft teams chat.
Now we that you have a rough idea of how the front end component of the bot works, it’s time to move to our QnA service. The QnA service is also provided to us by Microsoft. You can make any type of QnA service, let it be professional, friendly or even arrogant straight through www.qnamaker.ai , You just have to add questions with their relevant answers and train the service so that it would respond to even asking a question with grammatical and spelling mistakes in it, and Yes, it is smart like that! Fun Fact : You can apply the above front-end Json format as an answer onto the QnA maker and it will actually show you a beautiful card as an answer.
Moving on, we will be making a QnA bot as I mentioned before. Hence to initialize making the bot you will first have to download a template through visual studio code, also remember you have to separately install the adaptive card package as well.
I recommend you to start development through an echo bot template, where the bot will reply to you using the same text you send to it.
Here I will demonstrate a prebuilt chat bot, which uses a clean architecture coding method along with repository pattern , data mocking and dependency injection. Hence, this bot is written using Asp .NET Core and it uses dapper for SQL database connections. Maybe you heard too many new terms in the pervious sentence but it isn’t much of a deal at all.
I will be showing you the flow, as for how the bot actually works.
For example, the bot I have been working with is a professional bot which helps out the company staff along with company’s HR team to efficiently find internal data within the company. Hence, we will be providing a keyword “attendance” to the bot. The bot will return us an adaptive card showing us our last attendance, furthermore you can interact with this card asking the bot to give us more information about our attendance filtered out by the specific year and month. Upon submission, you will be shown all the related attendances for a specific month as a report. Just one keyword “attendance” helps us to find our latest attendance, as well as get to know if we have underworked on certain days of a specific month and year as well.
Alright, this is how it works. As I mentioned above, you have to connect the bot to your QnA service. This can be done by obtaining the QnA service’s ID from the service itself. Furthermore, you have to create a bot resource group at the azure web portal and get the application ID and it’s password. It’s a pretty straight forward process and you can find it here, Deploy your bot — Bot Service | Microsoft Docs .
The clean architecture coding methodology refers to the separation of business logics, APIs/DB connections/repositories, infrastructure of the code and other external dependencies.
The most important part of making your own bot is understanding how the bot responds to your messages.
IturnContext interface of the bot is mainly the reply the bot stores and gives us when we send a specific keyword to the bot, it simply provides information needed to process an incoming activity. For example, as I send the keyword “attendance” to the bot. The turnContext object can store various replies to be shown to the user at any specific point we desire. Let it be a simple text , an adaptive card or even a piece of media/pictures. Cancellation token must also always be passes when calling the bot, which ends the specific piece of request-response with the bot and user. There are many more methods in the Iturncontext interface, I will be only using the most common one.
Moreover, as for the example we took, when the keyword “attendance” is given, the bot must first return you an adaptive card to take input of a specific month and year, and finally display a summary to you. Here, the turnContext object also saves a special [value] field which is the input field IDs of the adaptive card we will be showing to the user. It must also be noted that the bot always processes string inputs. Hence parsing of any value to a string or from a string must be done as needed
These id’s must be unique from one another and can be changed from the json card format of the adaptive card itself as show below.
The above used is an application called Bot Emulator which helps us execute our code and check for any run time errors it even helps us debug the bot.
Hence, when the user clicks on a specific year and month., The turnContext object will save the value and it’s unique ID. This value of the turnContext can be manipulated to get any output we desire. Below is an example of how it has been done.
As I mentioned, I will be taking the id of the adaptive card which is save in the tunrContext object to distinguish if it is the adaptive card input field I require to work with. There after, I will be showing the user the respective adaptive card, here which is the AttendanceMonthlyCard.json. The final output of the flow will be like:
Moving on to how I get data to the specific cards. As I mentioned, I will be using dapper which allows us to directly apply any SQL schema and filter data out of our databases. For the above output result, the usage of dapper will be as follows. The infrastructure package of the bot consists of a mock repository and also the actual database repository. This has been connected to their relevant Interfaces as shown below.
So how does the data binding actually happens. Here we will be using the Unit of Work coding pattern. The data which we will be filtering out of the database, has to be mapped properly according to our request-response from the frontend.
An object mapping has been used to map the request to the relative response. AutoMapper is a component that helps to copy data from one type of object to another type of object. Simply, it is an to object-object mapper. AutoMapper also helps us to transform one object type to another. The mapping service must be registered within the object mapping class as well :
This is then followed by the dependency injection methodology where the unit of work of each class is being connected with it’s relevant response.
Finally I will show you how to output the results from the mapped response to our adaptive card.
Here, the FormatAttendanceData is a private method which is used to format the date-time format accordingly. The installed adaptive cards NuGet package has been used here to map decode the JSON file and bind our relevant data from the response to it.
It’s a quite simple procedure but it might seem hard at first. However, there is much more to building an advanced bot with Microsoft. This involves flows, dialogs etc. However, building an interactive with Microsoft and integrating it Teams, Skype or any other web platform is made really efficient thanks to Microsoft Azure.
I hope to talk about dialogs within the Bot Framework SDK in my next blog, until then cheers and stay safe!
