Learning to build a Microsoft Teams Bot — Getting the Echo Bot up and running
About this Series
I am (as of the date of writing) the Head of Development for a number of development teams which are mostly based in three offices - London, Malta and Barcelona. They have varied and wildly different public holiday schedules and we don’t officially track them. We regularly have a team(s) not in the office/not available when everyone else is. This is where this bot comes in.
I’m going to massively over-engineer a solution to inform the teams of public holidays occurring in any of the other locations.
My goal for this series is to build a Teams Bot which can inform the end user of when the public holidays are in their region on either an on-demand or a scheduled basis. This is a POC/MVP with a longer term goal of having the bot do more useful things later, but as mentioned previously is a bit of overkill for now.
Originally I planned to do two articles however I found that the sheer amount of learning and the number of technologies which interact to get a bot up and running meant I couldn't do that meaningfully in a single article. Unless I wanted that article to be my magnum opus.
Disclaimer: I have built neither a Bot nor a Teams App before so this is very much a “follow along while I learn” article.
3 Part Series:
- Part 1: This article
- Part 2: Getting public holiday data into the bot
- Part 3: Making the bot proactive
This article aims to get an out-of-the-box Echo template Bot up and running in Teams, while being able to debug the interactions locally.
Creating the Echo Bot
This portion is essentially zero effort and code free given the templates kindly provided by Microsoft
I followed the article linked directly below; installed the Bot templates for VS 2019, installed the emulator and created an Echo Bot based off Bot Framework V4 using .Net Core 3.1.
It should just work at this point, and the emulator is a nice touch, as getting the bot up and running in Teams is a bit more of a pain.
Don’t try to navigate to the default URL of http://localhost:3978/api/messages in your browser. It won’t work as it appears to be set up for web-socket communication but you too can spend hours googling whats ‘broken’ with your lovely default template which doesn't seem to work. Its not broken, it just doesn't work like that.
Make sure that you use the full url of “http://localhost:3978/api/messages” when adding your bot to the emulator.
At this point, I had the following working in the emulator.
I spent some time debugging the various calls, and looking at the properties of the available objects to see what kind of possibilities exist for what I’m trying to do.
The next step is to figure out how to register the app in Azure to get calls working with ngrok, so we can later load the app into teams and still be able to debug it locally.
Setting up and testing ngrok
I had no idea ngrok existed before I started this learning journey, but it’s an amazingly simple yet useful product. It exposes a public URL to the internet, then forwards the traffic to an endpoint hosted on your local machine.
Download and extract ngrok from here.
You can either run it as a command line tool manually every time you want to use it, forever, or create a .bat file to do it for you.
ngrok http -host-header=rewrite 3978Either way, this will start ngrok running on the localhost port we have specified.
You should, hopefully, see something like this.
And of course it would be rude not to test it right?
So now I have the following.
Registering with Azure
The next step is to add a new resource in Azure, you are looking for ‘Bot Channels Registration.’ It’s in the Marketplace, so it may not be immediately obvious when you are looking for it.
Enter whatever default values are appropriate but make sure to choose the Pricing Tier of S1 (because free) and follow the prompt to Auto create App ID and password. Leave the messaging endpoint blank for now.
Once the resource has deployed successfully head over to settings and click on the “Manage” link on Microsoft App Id
Add a new client secret, and make sure to copy the value as you create it. Its a one time deal.
Add the Application Id and the Password you have just created and add it to your appsettings.json file, where placeholders have been left for you to do so. Run the application.
Finally, fire up ngrok and copy the https url into the Messaging Endpoint including /api/messages as below.
Click on “Test in Web Chat” and you are testing your local bot, using an Azure Portal Test Client. How cool is that?
This does, apparently break the local bot emulator as I am completely unable to get it to work with the MicrosoftAppId and MicrosoftAppPassword fields the the appsettings.json file populated. Despite the fact that there are fields in the emulator to provide these values, it doesn't seem to help. Its entirely ̶p̶o̶s̶s̶i̶b̶l̶e̶ probable I’m doing something wrong, but I’ve had to resort to commenting out the populated fields when I want to test locally.
{
//"MicrosoftAppId": "",
//"MicrosoftAppPassword": "",
"MicrosoftAppId": "xxYourAppIdxx",
"MicrosoftAppPassword": "xxYourSecretxx",
}
Jumping through the hoops required to manually load the bot into Teams
I found this bit the most painful part of the entire exercise, for 2 reasons.
- The JSON schema required for the manifest is absolutely enormous and trying to find out the absolute minimum required info took a lot of trial and error. Full schema here
- You cannot publish your bot without having 2 images attached which fit the guidelines as published here
I’m going to try to solve both of these complications for anyone who stumbles across this article by providing the most stripped down valid schema I could make and providing some icons anyone is free to use for your own projects.
Add a folder called “AppManifest” to your folder structure. Add the two icons I’ve made available on github here to your folder.
Use the following JSON to create a file called ‘manifest.json’ and make sure to put your values into the fields where indicated. Yes, you do need to put the BotId/AppId from earlier into the file twice.
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
"manifestVersion": "1.8",
"version": "1.0.0",
"id": "xxYOURMSAPPIDxx",
"packageName": "com.microsoft.teams.xxYOURBOTNAMExx",
"developer": {
"name": "xxWhateverNameFloatsYourBoatxx",
"websiteUrl": "https://website.com/privacy",
"privacyUrl": "https://website.com/privacy",
"termsOfUseUrl": "https://website.com/app-tos"
},
"name": {
"short": "xxBotNamexx",
"full": ""
},
"description": {
"short": "A Bot Description",
"full": "A longer Bot Description."
},
"icons": {
"outline": "outline.png",
"color": "color.jpg"
},
"accentColor": "#000000",
"bots": [
{
"botId": "xxYOURMSAPPIDxx",
"scopes": [
"team",
"personal",
"groupchat"
],
"supportsFiles": false,
"isNotificationOnly": false
}
],
"permissions": [
"identity",
"messageTeamMembers"
],
"validDomains": []
}Finally, add the 3 files to a zipped file called “AppManifest.zip”. You should have something like this.
Finally go to Teams, click on “Apps” and find the link “Upload a custom app” and select the .zip file you created. This should then ask you where you want to install your bot. I created test team in order to be able to babble on to the bot in private.
And it should work!
After much setting up, and using many more technologies that I initially thought would be required it works!
The advantages of this setup are obvious, you can have a fully fledged(ish) bot running in teams, interacting with yourself or users and be able to debug the requests locally.
To wrap up, I quite enjoyed getting this sample to work. Given the number of interacting technologies, frameworks and settings I’m very glad I didn’t also have to come up with all the code to get the Echo Bot itself up and running, so that’s a good job from Microsoft.
In the next article, which I will link here after I’ve written it, Ill dive deep into the vagaries of the public holidays in the three office locations, and do code gymnastics to fit that to a free API I find.
Resources
Articles and videos I went through to get this far.
I followed along on this excellent Pluralsight course by Matthew Kruczek to get an idea of how to get a bot to hang together and respond to user interaction. I highly recommend this if you want to go more into the other areas of Bot building for Teams Im not planning on touching on.
These Microsoft samples were fantastic for getting up and running with a bot using samples which (mostly) work out of the box. You can get quite far using these.
There are also more samples here on github which in some cases are quite complex and fully featured.
