How to create your first Teams bot and deploy it to Azure

Things are always easy when you know how to do them, right? Creating a Teams bot is not a complex process, but figuring out all the different things that are required for the first time can seem like a challenging feat to accomplish. If this is the first time you are creating a Teams bot — or if it has been a while since you did it last time and need a reminder — this blog post is for you!

In this guide, I’ll give you step-by-step instructions on:

1. How to create and configure the required resources for a bot via Azure Portal
2. How to create a Teams bot code project using the Yeoman generator
3. How to test and debug the bot code locally, and
4. How to deploy your bot to Azure (and finalize the resource configurations)

If you run into any issues while following the written instructions or prefer to learn things by watching videos, below is also a demo video containing all of the same steps.

How to create and configure the required resources for a bot via Azure Portal

Even though Teams offers the user interface for us to use the bot, it does not serve as a place for hosting the actual bot logic. Because of this, the code always needs to live somewhere else, and Azure is a natural choice for this purpose.

You’ll need to create and configure four different resources for the bot in Azure: an Azure Bot, a Key Vault, a Web App, and an App Service Plan. In addition, you’ll need an Azure AD application registration for authentication. So let’s make all of that happen!

Creating a new resource group for your bot

Let’s start by creating a brand new resource group in our subscription, where we will later deploy the resources required by our bot.

1. Open Azure Portal in your browser
2. On the left, click on Resource groups and then Create.
   • Select the subscription you wish to use.
   • Give the resource group a name according to your organization’s naming conventions (e.g., projectname-rg)
   • Select a region near your users (e.g. West Europe if your users are in Europe)

Create the Azure Bot (and Key Vault) resources

After the resource group has been created, navigate to it, and create the Azure Bot and Key Vault resources according to the steps below (the vault gets created automatically when you create the bot resource). The Azure Bot resource is required for handling the communication between the bot code hosted in Azure and the client application (Microsoft Teams, in this case). The Key Vault is used for storing the client secret required for authentication.

1. Inside the newly created resource group, click on the big blue Create resources button. You get directed to the Marketplace.
2. Search for Azure Bot.
3. Click on Create
   
4. On the Basics tab, as the first thing, give the bot a unique name as it’s “handle” (e.g., projectname-bot). You can specify the display name for your bot separately; the handle is purely a unique identifier for your bot.
5. The correct subscription and the resource group should already be selected.
6. The default pricing tier is Standard but by clicking on Change plan you can downgrade it to Free if you don’t require premium channels.
7. Select Multi Tenant as the Type of App.
8. Leave the Creation type to its default setting (Create new Microsoft App ID).
   
9. Optionally, you can add tags to the Azure Bot resource as per your organization’s tagging conventions.
10. Finally, go to the Review + create tab and click on Create.
11. After the bot resource has been created, click on Go to resource.

Configuring the bot credentials and channels

Now that our bot resource has been created, we can proceed with configurations. First, let’s note down the bot app ID and secret for later.

1. In the bot resource settings, go to the Configuration blade.
2. Copy the Microsoft App ID to e.g. Notepad. You’ll need to set this later in your bot code project.
   
3. Click on the Manage link right above the field containing the GUID you just copied. This will direct you to the Azure AD app registration that was created at the same time with your bot resource.
4. You’ll find yourself on the Certificates and secrets blade. Create a brand new client secret (duration: 24 months) and copy its value to Notepad for later.

Now that we have the information required for authentication let’s enable our bot to communicate with our client application. Here, I’m creating a bot for Teams, but similarly, you can also select some other platform as the bot channel.

1. Go back to the bot resource, and go to the Channels blade.
2. In the list of channels, click on Microsoft Teams (or your other preferred platform)
   
3. Agree to the terms of service if prompted.
4. For this particular Teams bot example, I’m leaving the channel settings to their default values (Microsoft Teams Commercial, calling not enabled), but you can absolutely change these settings if you are developing your bot for a GCC environment, or want your bot to have calling capabilities.
5. Finally, click on Apply (and Close).

Creating the web app and the app service plan

The previously created Azure Bot only handles the communication between our bot logic and the client application (in this example, Teams). We still need to host the actual bot code somewhere, and for that purpose, we’ll create a Web App resource in Azure. Web apps also require an app service plan, which allows us to select the hardware computation resources for our bot, which again heavily influences our bot’s overall running costs.

1. Navigate back to the resource group level.
2. Click on Create, and create a new Web app resource.
3. Select the same subscription and resource group for the web app you used when creating the bot resource.
4. Give your web app a unique name which will also serve as the URL prefix (e.g., projectname-wa).
5. Choose to publish your solution as Code.
6. Select the same runtime stack you are using to develop your custom bot. In the case of our Teams bot here, that’d be Node, and at the time of this writing, the version I’ll be using when generating the project with yo teams is LTS 14.
7. Select the operating system. In this Teams example, I selected Linux.
8. Select the same region you chose for your resource group.
9. Select the app service plan from the dropdown. If you are creating a new one (which you probably are) and want to specify a different name than the one generated for you, click on the Create new link. That’ll allow you to specify a name of your choosing (e.g., projectname-asp).
10. Selecting a correct SKU and size (pricing tier) is critical because it heavily impacts how much it costs to run your bot in Azure. You can select the Free tier for development and test/demo purposes. For a bot with a relatively light load, the B1 tier should be sufficient for production use — even though it is also under the Dev/Test category. For performance-critical or heavy use, consider the premium tiers.
    
11. Optionally, on the next three tabs, you can enable continuous deployment and Application Insights for your bot, and tag your web app resource according to your organization’s tagging conventions.
12. When all the settings have been set, go to the Review + create tab and click on Create.
13. After the web app resource has been created, navigate to it, and copy its URL from the Overview blade.
14. Go to the Azure Bot resource Configuration blade, and add the Azure web app URL we copied earlier to the Messaging endpoint field, followed by /api/messages. Click on Apply at the bottom.

That’s all of the Azure resource configurations done! Now, all you need to do is implement and deploy your bot code to the web app.

How to create a Teams bot code project using the Yeoman generator

After setting up your development environment for yo teams, create a new bot project by following these steps:

1. Create a new folder for your project on your hard drive.
2. Start up Command Prompt, and navigate to the folder using the cd command (e.g., cd C:\path\teams-bot)
3. Type yo teams. It can take a little while for the “wizard” to launch.
4. You’ll need to answer the following questions. Press Enter to accept the default value or specify a different value and then press Enter.
   • What is your solution name? By default, this uses the folder name, which is usually fine.
   • Where do you want to place the files? Use the current folder.
   • Title of your Microsoft Teams App project? By default, this uses the folder name again, but you may want to specify a different display name for your bot.
   • Your (company) name? Either specify your name or the name of your organization.
   • Which manifest version would you like to use? Unless you want to use a specific manifest version, use the recommended version.
   • Quick scaffolding allows you to skip a bunch of questions that are otherwise presented for additional configurations. You can set all of the configurations later after the project has been created in the configuration file if needed. So, unless you know you wish to specify all of the configuration values already during the project generation, answer “Yes.”
   • What features do you want to add to your project? Use the arrow keys and the space bar to select only “A bot” from the list of different app types.
   • The URL where you will host this solution? Paste here the Azure web app URL we copied earlier.
   • Would you like to show a loading indicator when your app/tab loads? No
   • What type of bot would you like to use? A new Bot Framework bot
   • What is the name of your bot? Specify a nice looking display name.
   • What is the Microsoft App ID for the bot? Paste here the Microsoft App ID we copied earlier from the Azure Bot resource configurations.
   • Do you want to add a static tab to your bot? Select Yes or No based on your needs.
   • Do you want to support file upload to the bot? Select Yes or No based on your needs.
   • Do you want to include bot calling support? Select Yes or No based on your needs. If you select Yes, also remember to enable Teams calling support on the Azure Bot resource Channel configurations.

After answering all of the questions, all you need to do is wait for yo teams to finish generating the project. This can take several minutes, so go and grab a coffee while waiting.

When the generator has finished…

1. Open the project in Visual Studio Code by typing code . on the command line (notice the whitespace before the dot). Then, perform the following steps.
2. In Visual Studio Code, open the .env file, and set the following configurations.
   • MICROSOFT_APP_ID=The Microsoft App ID that you copied earlier from the Azure Bot resource configurations (this should already be filled if you provided it during the project setup)
   • MICROSOFT_APP_PASSWORD=The Azure AD app registration client secret that you created and copied earlier.
3. Save the file by hitting CTRL+S

Now, the bot code project is ready to be extended with your custom logic! While at it, you most likely also want to debug your code, so let’s see how we can make that happen next.

How to test and debug the bot code locally

When you have ngrok on your machine, you can debug and test your bot locally with these steps.

1. In Visual Studio Code, open the Terminal window.
2. Type gulp ngrok-serve. The command will start the ngrok tunneling service, and build and package our bot project for deployment.
3. When ngrok starts, it displays a URL address in the terminal after text PUBLIC_HOSTNAME (https://**GUID**.ngrok.io). Copy that to clipboard.
   
4. In your browser, navigate back to the Azure Bot resource Configuration blade, and paste the URL to the Messaging endpoint field (precede the address with https:// and include /api/messages at the end). Remember to click on Apply at the bottom.
5. Open your Teams client and click on Apps in the bottom-left corner, and then Manage your apps.
6. Click on Upload a custom app (for testing purposes). By the way, this process is also referred to as sideloading.
7. Navigate to the project folder and open the packages subfolder. Inside, you find a zip file which you should select. It contains the manifest file (json) with our bot configurations and two logo images to use in the Teams UI.
8. After uploading the zip file, click on Add to start testing your bot! You can see me testing my bot and extending it with further functionality in the demo video.

Bonus tips for debugging and development

Here are some additional tips for your debugging journey while extending your bot with custom logic. Otherwise, you are ready for the next step: deployment!

• Check out Microsoft documentation about bot development for things like activity handlers.
• If you make changes to your bot code while debugging, you simply need to save the changes (CTRL+S) and wait a few seconds while gulp recompiles the code for you. Then you can immediately test the new code changes.
• To stop debugging, click on CTRL+C
• To restart the debugger, follow the steps 2-4 again.
• If you make changes to the bot configuration (manifest), you need to uninstall and then reinstall the app in Teams (steps 5-7). Uninstallation happens by right-clicking on the bot icon in the side navigation, and selecting Uninstall.

How to deploy your bot to Azure

Ok, so you are now finished developing your bot and are ready to deploy the code to Azure. However, before we do that, let’s first set up the Teams client side of things to work with Azure rather than ngrok, which we previously used for debugging.

1. Run command gulp manifest in the Terminal window of Visual Studio Code to package your bot manifest and logo files for deployment.
2. Go to the Azure Bot resource Configuration blade on Azure Portal, and add the Azure web app URL back to the Messaging endpoint field (make sure to keep the /api/messages bit at the end).
3. Uninstall the bot app from Teams that was previously sideloaded only for you and your teams.
4. Click on Apps at the bottom-left corner of the Teams client, and then Manage your apps.
5. Click on Upload an app to your org’s app catalog. Note: If you later need to uninstall the app, you can’t currently do it via the Teams client. It must be done via the Teams admin center (Go to Manage apps, select an app, click on the three dots, and delete).
6. Navigate to the project folder and open the packages subfolder. Select the bot app package (zip).

You can already Add the bot for yourself, but it will not work yet. This is because we need to deploy our code to Azure first.

Ideally, you should use a CI/CD pipeline to deploy your code projects to Azure. However, sometimes, you might want to deploy the code directly from the code editor for quick testing and demo purposes.

1. Click on the Azure (A) icon in the left-hand navigation. Expand App Service and find your web app resource. Then right-click on the resource and select Deploy to Web App…
2. A small dropdown opens at the top. It should already display your project (and its directory path). Simply click on that (or hit Enter) to start the deployment.
3. It can take quite a while for the code to get deployed, so now is a good time to stretch a bit.

After the deployment has completed and you’ve tested the bot to work as expected, it is time to pat yourself on the back. You’ve successfully created and deployed your first Teams bot to Azure!

Afterword

This blog post covered the basics of creating a bot project using yo teams, debugging the bot locally while developing it, and finally deploying the bot code to Azure directly from Visual Studio code. I hope you found this guide helpful and feel more ready to do Teams development! Remember to take advantage of the official documentation and the code samples on Github.

If you enjoyed reading this article and would like to consume more content from me, follow me on social media (links on the sidebar and at the bottom for mobile), and sign up for my newsletter to keep you posted of timely matters. Otherwise, thanks for visiting, and until next time!

Laura