Build your first bot app using JavaScript

Article
Developer (Beginner)
6 minutes to complete

Start Microsoft Teams app development with your first Teams app. You can create a bot app with Teams using Javascript.

Your app has a capability, which comes with its own UI and UX:

Diagram shows that this app has three features.

In this tutorial, you'll learn:

How to set up a new project with Teams Toolkit.
How to build a bot app.
How to deploy your app.

Prerequisites

5 minutes remaining

Ensure you install the following tools for building and deploying your apps.

	Install	For using...
Required
	Teams Toolkit	A Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use the latest version.
	Microsoft Teams	Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and call-all in one place.
	Node.js	Back-end JavaScript runtime environment. For more information, see Node.js version compatibility table for project type.
	Microsoft Edge (recommended) or Google Chrome	A browser with developer tools.
	Visual Studio Code	JavaScript, TypeScript, or SharePoint Framework (SPFx) build environments. Use the latest version.
Optional
	Azure Tools for Visual Studio Code and Azure CLI	Azure tools to access stored data or to deploy a cloud-based backend for your Teams app in Azure.
	React Developer Tools for Chrome OR React Developer Tools for Microsoft Edge	A browser DevTools extension for the open-source React JavaScript library.
	Microsoft Graph Explorer	Microsoft Graph Explorer, a browser-based tool that lets you run a query from Microsoft Graph data.
	Developer Portal for Teams	Web-based portal to configure, manage, and distribute your Teams app including to your organization or the Teams store.

Tip

If you work with Microsoft Graph data, you should learn about and bookmark the Microsoft Graph Explorer. This browser-based tool allows you to query Microsoft Graph outside of an app.

Prepare development environment

After you've installed the required tools, set up the development environment.

Install the Teams Toolkit

The Teams Toolkit helps simplify the development process with tools to provision and deploy cloud resources for your app, publish to the Teams store, and more.

You can use the toolkit with Visual Studio Code, or CLI (command-line interface), called TeamsFx.

Visual Studio Code
Command line

Open Visual Studio Code and select the Extensions view (Ctrl+Shift+X / ⌘⇧-X or View > Extensions).
In the search box, enter Teams Toolkit.
Select Install next to the Teams Toolkit.

The Teams Toolkit icon appears in the Visual Studio Code Activity Bar after it's installed.

You can also find the Teams Toolkit on the Visual Studio Code Marketplace.

To install the TeamsFx CLI, use the npm package manager:

npm install -g @microsoft/teamsfx-cli

Depending on your configuration, you may need to use sudo to install the CLI:

sudo npm install -g --unsafe-perm @microsoft/teamsfx-cli

This condition is more common on Linux and macOS systems.

Ensure you add the npm global cache to your PATH. This step is normally done as part of the Node.js installer.

You can use the CLI with the teamsfx command. Verify that the command is working by running teamsfx -h.

Caution

Before you can run TeamsFx in PowerShell terminals, you must enable the "remote signed" execution policy for PowerShell.

Set up your Teams development tenant

A tenant is like a space, or a container for your organization in Teams, where you chat, share files, and run meetings. This space is also where your sideload and test your app. Let's verify if you're ready to develop with the tenant.

Check for sideloading option

After creating the app, you must load your app in Teams without distributing it. This process is known as sideloading. Sign in to your Microsoft 365 account to view this option.

Note

Sideloading is necessary for previewing and testing apps in Teams local environment. If it isn't enabled, you won't be able to preview and test your app in Teams local environment.

Do you already have a tenant, and do you have the admin access? Let's check if you really do!

Verify if you can sideload apps in Teams:

In the Teams client, select the Apps icon.
Select Manage your apps.
Select Upload an app.
Look for the option to Upload a custom app. If you see the option, sideloading apps is enabled.

Note

Contact your Teams administrator, if you don't find the option to upload a custom app.

Create a free Teams developer tenant (optional)

If you don't have a Teams developer account, you can get it free. Join the Microsoft 365 developer program!

Go to the Microsoft 365 developer program.
Select Join Now and follow the onscreen instructions.
In the welcome screen, select Set up E5 subscription.
Set up your administrator account. After you finish, the following screen appears.
Sign in to Teams using the administrator account you just set up. Verify that you have the Upload a custom app option in Teams.

Get a free Azure account

If you wish to host your app or access resources in Azure, you must have an Azure subscription. Create a free account before you begin.

Now you’ve got all the tools to set up your account. Next, let's set up your development environment and start building! Select the app you want to create first.

Create project workspace for your bot app

4 minutes remaining

Let's create your first bot app.

The bot capability of a Teams app creates a chatbot or a conversational bot. You use it to run simple and automated tasks, like providing customer service. A bot talks with a web service and helps you use its offerings. You can get weather forecast, make reservations, or any other service offered using a conversational bot.

Diagram showing this app has three features. Bot is highlighted.

As you've already prepared for creating these apps, you can set up a new Teams project for creating the bot app.

In this tutorial, you learn:

How to set up a new bot project with Teams Toolkit.
About the directory structure of your app project.

Important

Bots are available in Government Community Cloud (GCC), GCC-High, and Department of Defense (DOD) environments.

Create your bot project workspace

If the prerequisites are in place, let's begin!

Note

The Visual Studio Code UI shown is from Mac. It may differ depending on your operating system, Teams Toolkit version, and environment.

Visual Studio Code
Command line

Open Visual Studio Code.
Select the Teams Toolkit icon in the Visual Studio Code Activity Bar.
Select Create a New App.
Select Bot to create a new bot project.
Ensure that Basic Bot is selected as the app feature that you want to build in your app.
Select JavaScript as the programming language.
Select Default folder to store your project root folder in default location.

You can also change the default location by the following steps:
1. Select Browse.
2. Select the location for project workspace.
3. Select the Select Folder.
Enter a suitable name for your app and then select Enter.

A dialog appears, where you would be required to choose yes or no to trust the authors of the files in this folder.

Your Teams app with a bot capability is created in few seconds.

After your app is created, the Teams Toolkit displays the following message:

Select Local debug to preview your project.

A quick recap of creating a Teams app.

Watch this short recap for creating a Teams app.

Create a Teams app

Use the teamsfx CLI to create your first project. Start from the folder where you want to create the project folder.

teamsfx new

You can use the CLI to create a new Teams app. The CLI leads you through a series of questions. Every question includes an instruction on answering it.

For example, use arrow keys to select an option. After you make the choice, select Enter to confirm it.

Select Create a new Teams app.
Select Bot and deselect Tab.
Select JavaScript as the programming language.
Select Enter to select the default workspace folder.
Enter a suitable name for your app, like HelloBot. The name of the app must consist only of alphanumeric characters.

After you've answered all questions, your project is created.

Take a tour of the bot app source code

After scaffolding is completed, view the project directories and files in the Explorer in the Visual Studio Code.

Screenshot shows the folder structure.

Folder / File	Contents
`teamsapp.yml`	Main project file describes your application configuration and defines the set of actions to run in each lifecycle stages.
`teamsapp.local.yml`	This overrides `teamsapp.yml` with actions that enable local execution and debugging.
`.vscode/`	VSCode files for local debug.
`appPackage/`	Templates for the Teams application manifest.
`adaptiveCards/`	The adaptive cards sent back by bot.
`infra/`	Templates for provisioning Azure resources.
`index.js`	Application entry point and `restify` handler.
`teamsBot.js`	Teams activity handler.

Tip

Familiarize yourself with bots outside of Teams before you integrate your first bot within Teams.

Build and run your first bot app

3 minutes remaining

After you set up your project workspace with Teams Toolkit, build your bot project. You need to sign in to your Microsoft 365 account.

Use this account to sign in to Teams. If you're using a Microsoft 365 developer program tenant, the admin account you set up while registering is your Microsoft 365 account.

Visual Studio Code
Command line

Open Visual Studio Code.
Select the Teams Toolkit icon in the sidebar.
Select Sign in to M365 using your credentials.

Your default web browser opens to let you sign in to the account.
Close the browser when prompted and return to Visual Studio Code.
Return to Teams Toolkit within Visual Studio Code.

Use this account to sign in to Teams. If you're using a Microsoft 365 developer program tenant, the admin account you set up while registering is your Microsoft 365 account.

Now you're ready to build the app and run it locally!

Sign in to Microsoft 365 with the TeamsFx CLI:
```
teamsfx account login m365
```
Your default web browser opens to let you sign in to the account. Sign in to your Azure account using your credentials. Close the browser when you're prompted.
Sign in to Azure with the TeamsFx CLI:
```
teamsfx account login azure
```
Your default web browser opens to let you sign in to the account. Sign in to your Azure account using your credentials. Close the browser when you're prompted.

The account logins are shared between Visual Studio Code and the TeamsFx CLI.

Now that the development environment is configured, you can create, build, and deploy your first Teams app.

Build and run your first bot app locally

To build and run your app in the local environment:

Select F5 in Visual Studio Code to run your app in debug mode.

Note

If Teams Toolkit is unable to check a particular prerequisite, it prompts you to check.
Learn what happens when you run your app locally in the debugger.

In case you're wondering, when you press the F5 key, the Teams Toolkit:
1. Checks all the following prerequisites:
- You're logged in with a Microsoft 365 account.
- Sideloading is enabled for your Microsoft 365 account.
- Supported Node.js version is installed.
- Port required by bot app is available.
1. Install npm packages.
2. Starts Dev Tunnel to create a HTTP tunnel.
3. Registers the app in Azure AD and configures the app.
4. Registers the bot app in Bot Framework and configures the bot app.
5. Registers the app in Teams Developer Portal and configures the app.
6. Starts the bot app.
7. Starts Teams in a web browser and sideloads the bot app.
Note

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 process can take three to five minutes to complete.

Teams runs your app in a web browser.
Sign in with your Microsoft 365 account, if prompted.
Select Add when prompted to sideload the bot app onto Teams on your local machine or use the dropdown menu to add your bot app to a team, chat, or meeting.

Now the bot is successfully running on Teams! After the app is loaded, a chat session with the bot opens.

You can type welcome to show an introduction card, and type learn to go to adaptive card and bot command documentation.

You can do normal debugging activities, such as setting breakpoints, as with any other web application. Open the bot/teamsBot.js file and locate the onMessage() method. Set a breakpoint on any case. Then, type some text.

Learn how to troubleshoot if your app doesn't run locally.

To successfully run your app in Teams, ensure that you've enabled sideloading in your Teams account. You can learn more about sideloading in the Prerequisites section.

Important

Currently, sideloading apps are available in Government Community Cloud (GCC), GCC-High, and DOD.

Tip

Check for issues before sideloading your app, using the app validation tool. This tool is included in the toolkit. Fix the errors to sideload the app.

Deploy your first Teams app

2 minutes remaining

You've learned to create, build, and run Teams app with Bot capability. The final step is to deploy your app on Azure.

Let's deploy the first app with Bot capability on Azure using Teams Toolkit.

Use this account to access the Microsoft Azure portal and to provision new cloud resources to support your app.

Visual Studio Code
Command line

Open Visual Studio Code.
Open the project folder in which you created the bot app.
Select the Teams Toolkit icon in the sidebar.
Select Sign in to Azure using your credentials.

Tip

If you have the AZURE ACCOUNT extension installed and are using the same account, you can skip this step. Use the same account as you are using in other extensions.

Your default web browser opens to let you sign in to the account.
Close the browser when prompted and return to Visual Studio Code.

The ACCOUNTS section of the sidebar shows the two accounts separately. It also lists the number of usable Azure subscriptions available to you. Ensure you have at least one usable Azure subscription available. If not, sign out and use a different account.

Congratulations, you have created a Teams app! Now let's go ahead and learn how to deploy one of the apps to Azure using the Teams Toolkit.

Sign in to Microsoft 365 with the TeamsFx CLI:
```
teamsfx account login m365
```
Your default web browser opens to let you sign in to the account. Sign in to your Azure account using your credentials. Close the browser when you're prompted.
Sign in to Azure with the TeamsFx CLI:
```
teamsfx account login azure
```
Your default web browser opens to let you sign in to the account. Sign in to your Azure account using your credentials. Close the browser when you're prompted.

The account logins are shared between Visual Studio Code and the TeamsFx CLI.

Congratulations, you have signed in your Azure account! Now let's go ahead and learn how to deploy one of the apps to Azure using the Teams Toolkit.

Deploy your app to Azure

Deployment consists of two steps. First, necessary cloud resources are created (also known as provisioning). Then, your app's code is copied into the created cloud resources. For this tutorial, you'll deploy the bot app.

What's the difference between Provision and Deploy?

The Provision step creates resources in Azure and Microsoft 365 for your app, but no code (HTML, CSS, JavaScript, etc.) is copied to the resources. The Deploy step copies the code for your app to the resources you created during the provision step. It's common to deploy multiple times without provisioning new resources. Since the provision step can take some time to complete, it's separate from the deployment step.

Visual Studio Code
Command Line

Select the Teams Toolkit icon in the Visual Studio Code sidebar.

Select Provision.
Select a subscription to use for the Azure resources.

Your app is hosted using Azure resources.

A dialog warns you that costs may be incurred when running resources in Azure.
Select Provision.

The provisioning process creates resources in the Azure cloud. It may take 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:

If you want, you can view the provisioned resources. For this tutorial, you don't need to view resources.

The provisioned resource appears in the ENVIRONMENT section.
Select Deploy from the LIFECYCLE panel after provisioning is complete.

As with provisioning, deployment 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.

Now, you can use the same process to deploy your Bot and Message Extension apps to Azure.

In your terminal window:

Run teamsfx provision.
```
teamsfx provision
```
When prompted, select an Azure subscription to use Azure resources.

Your app is hosted using Azure resources.
Run teamsfx deploy.
```
teamsfx deploy
```

Run the deployed app

Once the provisioning and deployment steps are complete:

Open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run) from Visual Studio Code.
Select Launch Remote (Edge) from the launch configuration drop-down.
Select the Start debugging (F5). You'll be prompted to sideload the bot app onto Teams.
Select Add or use the dropdown menu to add your bot app to a team, chat, or meeting.

You've successfully added your bot app to the Teams client.

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 is a two-step process. You provision the resources on an active Azure subscription, and then deploy or upload the backend and frontend code for the application to Azure.

The backend, if configured, uses various Azure services, including Azure App Service and Azure Storage.
The frontend application is deployed to an Azure Storage account configured for static web hosting.

Build your first bot app using JavaScript

Prerequisites

Prepare development environment

Install the Teams Toolkit

Set up your Teams development tenant

Check for sideloading option

Create a free Teams developer tenant (optional)

Get a free Azure account

Create project workspace for your bot app

Create your bot project workspace

Take a tour of the bot app source code

Build and run your first bot app

Build and run your first bot app locally

Deploy your first Teams app

Deploy your app to Azure

Run the deployed app

Congratulations!

Feedback

Build your first bot app using JavaScript

Prerequisites

Prepare development environment

Install the Teams Toolkit

Set up your Teams development tenant

Check for sideloading option

Create a free Teams developer tenant (optional)

Get a free Azure account

Create project workspace for your bot app

Create your bot project workspace

Take a tour of the bot app source code

Build and run your first bot app

Sign in to your Microsoft 365 account

Build and run your first bot app locally

Deploy your first Teams app

Sign in to your Azure account

Deploy your app to Azure

Run the deployed app

Congratulations!

Feedback