Crash Course for Building Your First Bot on Microsoft Teams

(Click here for Korean Version)

Have you ever heard of Microsoft Teams?

Nowadays, a lot of businesses and schools use Microsoft Teams to support communication and collaboration within their organization. But what is it?

What is Microsoft Teams?

Microsoft Teams is a chat-based collaboration platform where you can use many useful tools for collaboration with other people. It has rich features in document sharing, communication, and online meetings.

Microsoft Teams itself provides these features and it also provides APIs to support other third-party applications integrated into the platform to make the collaboration experience better. These apps can have a set of capabilities that Microsoft Teams Platform allows: Tabs, Bots, Message Extensions, and Connectors.

Each app can have a subset of these capabilities or just a single capability. Today, I am going to show you how to build an app only with the bot capability (a.k.a bot) and install it on Microsoft Teams.

The goal of this article is to share how to build a very simple functional bot on the platform so you can build smarter bots based on this experience. Hope it can be a useful starting point for some of you!

The Target Audience of this article

• Anyone who has not used Microsoft Teams, but want to play with this platform.
• Anyone who wants to learn how to build a bot on Microsoft Teams Platform.

What are you going to have after following the steps in this article?

At the end of this post, you will have a working bot that echoes back your message!

Development Environment for this Article.

• Set-Up:
  • Windows 10, Visual Studio*
  • *Visual Studio Version: You need ASP.NET Core Runtime 3.1 which comes with the latest Visual studio 2019. But if you are using the old version of Visual Studio, please install ASP.NET Core Runtime 3.1 from here.
  • You can check which version contains what version of ASP.NET Core Runtime from the same website as well.
• Ngrok(or any other tunneling tool)
  • Please install ngrok, if you don’t have one. There are several ways you can install ngrok. I personally prefer using Chocolatey Package Manager on windows. You can find different ways to install ngrok properly here
• .Net/C#
  • Here I am going to show you building the bot using .Net and C# using the latest Bot Framework SDK, Bot Framework SDK V4.
  • You can certainly build bots with other frameworks and languages as well. You can see examples for other options here

Step 1: Sign up for Teams Free

If you haven’t used Teams before, let’s sign up for Teams.

Microsoft Teams provides a free version that allows you to enjoy the fundamental functionalities of the product. (You can see the difference between the free and the paid version here).

You can sign up for Microsoft Teams Free by going through the instructions here: Sign up for Teams free

If you already have Microsoft 365 Developer Subscription, you have two choices.
(1) You can use your existing Team for this activity. Or
(2) You can create a testing tenant and use a testing team.
- The instruction to do so is here: Create an Office 365 Test Tenant (Check Creating a test tenant section)

Note: if you want to remove your testing team after this exercise, you certainly can. You can find the instructions to do so here.

Step 2: (optional) Set up a team in Teams

After you sign up for a team, now it is time for you to create a team in Teams! To make my post focus on creating a bot, I will not go over details about how to create a team in Teams from scratch. Instead, please check this post out Create a team from scratch

After you set up your team, you will see something similar to this:

Now let’s leave Teams Client open and work on something in Visual Studio. We will come back to the Teams Client after we are done with setting up our local bot service with Visual Studio.

Step 3: Install Bot Framework v4 SDK Template Visual Studio Extension

Now let’s get the Bot Framework (BF) v4 SDK template by installing Bot Framework v4 SDK Template Visual Studio Extension. This extension will allow you to set up the bot quickly by providing a skeleton of the structure of required files to build a bot.
You can download the template extension here.

Step 4: Once the installation is complete, open your Visual Studio -> click Create a new project -> search for `Echo Bot (Bot Framework v4- .Net Core 3.1).

Step 5: Open appsettings.json file.

When the project is created, you will see something like this:

I highlighted appsettings.json file as that's the file that we will need to update with the MicrosoftAppId and MicrosoftAppPassword soon.

Step 6: Run ngrok to point to port 3978 by running ngrok http -host-header=rewrite 3978 on your command prompt.

When you run the above command, you will see a corresponding public url is returned.

We will need this publicly accessible URL later.

Note: We are using port 3978 as that’s the default port that comes with the template. You can check this value in launchSettings.json file under Properties folder.

If you want to change this port value, feel free to modify this launchSettings.json file.

If you want to change this port value, feel free to modify this launchSettings.json file.

Step 7: Then go back to your Teams client and install an app called App Studio.

This app is very useful to start creating or integrating your own Microsoft Teams apps. So I personally think it is worth to pin it on your bar. (More information about App Studio can be found here)

Step 8: Then go to app studio app -> go to 'Manifest' tab -> click 'create a new app'

Step 9: Then you will see 'App Details' page. Please fill out this page.

A few things to note:

• The sections that have the asterisk sign(*) must be filled out.
• App ID is not the one that we need to copy and paste it to appsettings.json. So don't need to copy that value.
• You don't need to put actual values for testing purpose.Fill free to follow placeholder values. (ex: https://www.teams.com/privacy)
• If this 'App Details` page is not properly filled out, you will see some error messages in Test and Distribute section. For instance,

Step 10: Now, this is the most important part for us. Click Bots and click Set Up.

Step 11: Fill out the form that pops up when you click Set up.

For your testing convenience, allow your bot to be installable in persona chat, team, and group chat (see highlighted part). Then click Create Bot.

Step 12: Copy the value of bot id and paste it as the value of MicrosoftAppId in appsettings.json (second screenshot).

As soon as you click Create bot, you will see the bot id (highlighted part) generated. This is the id of the bot that we care about.

Step 13: Click Generate New Password to get the app password.

This value is only shown once, so make sure you copy it after the password is generated. After you copy it, go to your visual studio and paste it as MicrosoftAppPassword value in appsettings.json as we did in Step 12.

Step 14: Now, you are all set with building your bot service for the Echobot. Let’s run the service locally (F5 or just click start in Visual Studio).

If everything is compiled properly and running, you will see the localhost 3978 page open in your browser.

Step 15: Coming back to the App details page on App Studio, fill out Messaging endpoint with <ngrok url>/api/messages.

In Step 6, we got the public url from ngrok. Copy that value and paste it to the Bot endpoint address. Then please make sure to add /api/messages as that’s the endpoint that a bot can understand.

Now we are done with setting up the bot on Teams Platform! Now we need to add your bot to Teams so you can interact with it.

Step 16: Go to Test and distribute section, and make sure there is nothing under Description.

If you don't see anything on the Description side, it means the information you put is all in the correct format. If you see something, please make sure to address the issues. If everything is good, click install.

Step 17: Click Download instead of Install.

Generally, you would be able to install your bot by clicking ‘Install’. But for Teams Free, you won’t have a permission to install the custom app directly this way. If you click Install, you will see the following warning.

The admin privilege in Teams Free is also very limited so even if you log in as an admin account, you cannot allow users to install their custom apps.

This does not mean you cannot install the app. What we are going to do is downloading the Microsoft Teams manifest of your app, and we are going to upload the manifest itself to your team.
If you click Download on Test and Distribute, you will see a zip file downloaded to your local Downloads folder.

If you click Download on Test and Distribute, you will see a zip file downloaded to your local Downloads folder.

Step 18: Go to Apps page and click Upload a custom app, and upload your manifest.

When you click Upload a custom app, you will see File Explorer Dialogue pops up. Click your zip file to upload it. After the upload is done, you will see your custom app on the App page.

Step 19: Then click your testing bot, then you will see a popped out dialogue. Click Add.

For our testing purpose, installing the bot in a personal chat (you:bot) is enough. If you click the top-down arrow, you can also add a bot to a different scope (ex: team, a group chat).

When you click Add, your bot is going to create a 1:1 chat between you and itself by sending a proactive welcome message.

Step 20: Congratulations! You officially built your own bot and installed it on Teams Platform!

The bot should echo back whatever you type on the chat.

In this post, I shared the complete guide to build your own bot and install in on Teams Platform. I hope this guidance can be a great starting point for you to build many different apps on Teams platform.

Teams provides many rich APIs for developers to develop amazing applications on its platform. You can learn more about how to build different capabilities of apps on Teams here:

• Build apps for Microsoft Teams: a good place to get an overview of Teams Platform development ecosystem
• Microsoft Teams developer documentation: the centralized place for all documentation and resources for development on Teams Platform.

If you are looking for more bot APIs that you can use for Teams bot, please check out here.

There are a few APIs that I contributed to as well 😊

P.S: If you would like to work on a product that makes an impact on millions of users and you love working with amazing and cool people, my org, Microsoft Teams Platform, is hiring!

Please find positions listed at Careers at Microsoft.