Crash Course for Building Your First Bot on Microsoft Teams 
Tags: microsoftteams, bot
Published: 2021-02-06 05:59:34

(Click here for [Korean Version](https://velog.io/@yunicorn/%EB%A7%88%EC%9D%B4%ED%81%AC%EB%A1%9C%EC%86%8C%ED%94%84%ED%8A%B8-%ED%8C%80%EC%A6%88-%EB%B4%87-%EB%A7%8C%EB%93%A4%EA%B8%B0-101))

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!
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/ejhubpj8lclq040a5kpp.png)

##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](https://dotnet.microsoft.com/download/dotnet-core/3.1).
  - You can check which version contains what version of ASP.NET Core Runtime from the same website as well. 
- [Ngrok](https://ngrok.com/)(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](https://www.twilio.com/docs/usage/tutorials/how-use-ngrok-windows-and-visual-studio-test-webhooks)
- .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](https://docs.microsoft.com/en-us/microsoftteams/platform/tutorials/code-samples)

###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](https://support.microsoft.com/en-us/office/differences-between-microsoft-teams-and-microsoft-teams-free-0b69cf39-eb52-49af-b255-60d46fdf8a9c)). 

You can sign up for Microsoft Teams Free by going through the instructions here: [Sign up for Teams free](https://support.microsoft.com/en-us/office/sign-up-for-teams-free-70aaf044-b872-4c32-ac47-362ab29ebbb1)

If you already have [Microsoft 365 Developer Subscription](https://docs.microsoft.com/en-us/office/developer-program/microsoft-365-developer-program-get-started), 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](https://teams-manager.com/create-an-office-365-test-tenant#:~:text=In%20this%20case%2C%20just%20open,content%20for%20your%20new%20tenant.) (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](https://support.microsoft.com/en-us/office/delete-your-teams-free-organization-2c28cfcf-3fbf-497c-938f-8815a8f6a6b9). 

###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](https://support.microsoft.com/en-us/office/create-a-team-from-scratch-174adf5f-846b-4780-b765-de1a0a737e2b)

After you set up your team, you will see something similar to this:
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/9jqazitlt034yddunnht.png)
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](https://marketplace.visualstudio.com/items?itemName=BotBuilder.botbuilderv4).  

###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). 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/m0mqpq7uqg7w1wekmw5h.png)

###Step 5: Open `appsettings.json` file. 
When the project is created, you will see something like this:
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/mrt8sfrel4nvvu4eogz6.png)
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. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/svyzxb45nwxzboa9qjc2.png)
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. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/85ebhb3u6b2petms4o3c.png)
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`. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/t2fye1g31l06unwke8dg.png)
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](https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/build-and-test/app-studio-overview))
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/b6svsfyz8wzuxjrr6p4t.png)

###Step 8: Then go to app studio app -> go to 'Manifest' tab -> click 'create a new app'
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/8daolzoyb2bepnepbv1d.png)

###Step 9:  Then you will see 'App Details' page. Please fill out this page. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/32ebenafirf84to3nsgt.png)
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, 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/jo62tn4nqxvi5t9ux4i9.png)

###Step 10: Now, this is the most important part for us. Click `Bots` and click `Set Up`.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/h49awx2psxvbpggvkb4z.png)

###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`. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/xjdmw1rigys0b06xi56w.png)

###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. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/s94p8qio3tfjx43mzag5.png)
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/5hr078ncmbm53wer0y9p.png)

###Step 13: Click `Generate New Password` to get the app password. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/l8n7tyh6geafc4nerndw.png)
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).
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/9z7159utbm8kmbhyvr51.png)

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. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/0cxx7x96mf4l5h3cdm1v.png)

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`.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/ddm23zaqgip9ajuzxg5a.png)
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](https://docs.microsoft.com/en-us/microsoftteams/manage-freemium) is also very limited so even if you log in as an admin account, you cannot allow users to install their custom apps. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/9xi48vat26xs6v3k6tyr.png)
This does not mean you cannot install the app. What we are going to do is downloading the [Microsoft Teams manifest]( https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) 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. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/a6yorjtgt72dq3vmpri6.png)

###Step 18: Go to `Apps` page and click `Upload a custom app`, and upload your manifest. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/wughgwz2lcsbpklxxled.png)

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. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/5hevskusfr13pheb2w2i.png)

###Step 19: Then click your testing bot, then you will see a popped out dialogue. Click `Add`. 
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/sod2nq9wi6bx5ucxqt7u.png)

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](https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages?tabs=dotnet). 

###Step 20: Congratulations! You officially built your own bot and installed it on Teams Platform!
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/8od2lxs2im0i1sdeiy74.png)
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](https://docs.microsoft.com/en-us/microsoftteams/platform/overview): a good place to get an overview of Teams Platform development ecosystem
- [Microsoft Teams developer documentation]( https://docs.microsoft.com/en-us/microsoftteams/platform/#pivot=sdk-tools): 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](https://docs.microsoft.com/en-us/dotnet/api/?view=botbuilder-dotnet-stable). 

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](https://careers.microsoft.com/us/en).