Build your first conversational bot for Microsoft Teams
A bot acts as an intermediary between a Teams user and a web service. Users can chat with a bot to quickly get information, initiate workflows, or anything else your web service can do. In this tutorial, you will learn how to build, run, and deploy a Teams bot app.
Before you begin
Make sure your development environment is set up by installing the Prerequisites
Create your project
Use the Teams Toolkit to create your first project:
Open Visual Studio code.
Open the Teams Toolkit by selecting the Teams icon in the sidebar:
Select Create New Project.
Select Create a new Teams app.
On the Select capabilities step, select Bot and deselect Tab. Press OK.
On the Bot registration step, select Create a new bot registration.
Select a workspace folder. A folder will be created within your workspace folder for the project you are creating.
Enter a suitable name for your app, like
helloworld. The name of the app must consist only of alphanumeric characters. Press Enter to continue.
Your Teams app will be created within a few seconds.
Take a tour of the source code
If you wish to skip this section for now, you can run your app locally.
A messaging extension uses the Bot Framework to allow the user to interact with your service via a conversation. After scaffolding, your project will look like this:
The bot code is stored in the
bot directory. The
bot/teamsBot.js is the main entry point for the bot, and the dialogs are stored in the
Familiarize yourself with bots outside of Teams before you integrate your first bot within Teams. You can find more information about bots by reviewing the Azure Bot Service tutorials.
Run your app locally
Teams Toolkit allows you to host your app locally. To do this:
- An Azure Active Directory Application is registered within the M365 tenant.
- An app manifest is submitted to the Developer Center for Teams.
- An API is run locally using Azure Functions Core Tools to support your app.
- ngrok is installed and used to provide a tunnel between Teams and your bot code.
To build and run your app locally:
From Visual Studio Code, press F5 to run your application in debug mode.
When you run the app for the first time, all dependencies are downloaded and the app is built. A browser window automatically opens when the build is complete. This can take 3-5 minutes to complete.
Your web browser starts to run the app. If prompted to open Teams desktop, select Cancel to remain in the browser. You may also be prompted to switch to Teams desktop at other times; select the Teams web app when this happens.
You may be prompted to sign in. If so, sign in with your M365 account.
When prompted to install the app onto Teams, press Add.
Once the app is loaded, you will be taken directly to a chat session with the bot. You can type
intro to show an introduction card, and
show to show your details from Microsoft Graph. (This will require an additional permissions approval).
Debugging works as you normally would expect - try it yourself! Open the
bot/dialogs/rootDialog.js file and locate the
triggerCommand(...) method. Set a breakpoint on the default case. Then type some text.
Learn what happens when you run your app locally in the debugger.
When you pressed F5, the Teams Toolkit:
- Registered your application with Azure Active Directory.
- Registered your application for "side loading" in Microsoft Teams.
- Started your application backend running locally using Azure Function Core Tools.
- Started an ngrok tunnel so Teams can communicate with your app.
- Started Microsoft Teams with a command to instruct Teams to sideload the application.
Learn how to troubleshoot common issues when running your app locally.
To successfully run your app in Teams, you must have a Microsoft 365 development account that allows app sideloading. For more information on account opening, see Prerequisites.
Check for issues before sideloading your app, using the app validation tool, which is included in the toolkit. Fix the errors to successfully sideload the app.
Deploy your app to Azure
Deployment consists of two steps. First, necessary cloud resources are created (also known as provisioning), then the code that makes up your app is copied into the created cloud resources.
Open Visual Studio Code.
Select the Teams Toolkit from the sidebar by selecting the Teams icon.
Select Provision in the Cloud.
If required, select a subscription to use for the Azure resources.
There are always some Azure resources used for hosting your app.
A dialog warns you that costs may be incurred when running resources in Azure. Press Provision.
The provisioning process creates resources in the Azure cloud. This takes some time. You can monitor the progress by watching the dialogs in the bottom right corner. After a few minutes, you see the following notice:
Once provisioning is complete, select Deploy to the Cloud. As with provisioning, this process takes some time. You can monitor the process by watching the dialogs in the bottom right corner. After a few minutes, you see a completion notice.
What's the difference between Provision and Deploy?
Once the provisioning and deployment steps are finished:
- From Visual Studio Code, open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run)
- Select Launch Remote (Edge) from the launch configuration drop-down.
- Press the Play button to launch your app - now running remotely from Azure!
Learn what happens when you deployed your app to Azure
Before deployment, the application has been running locally:
- The backend runs using Azure Functions Core Tools.
- The application HTTP endpoint, where Microsoft Teams loads the application, runs locally.
Deployment involves provisioning resources on an active Azure subscription and deploying (uploading) the backend and frontend code for the application to Azure. The backend uses a variety of Azure services, including Azure App Service and Azure Bot Service.
- Create a Teams app with React
- Create a Teams app with Blazor
- Create a Teams app as a SharePoint Web Part (Azure not required)