Tutorial: Create and deploy a basic bot

APPLIES TO: yesSDK v4 no SDK v3

This tutorial walks you through creating a basic bot with the Bot Framework SDK and deploying it to Azure. If you've already created a basic bot and have it running locally, skip ahead to the Deploy your bot section.

In this tutorial, you learn how to:

  • Create a basic Echo bot
  • Run and interact with it locally
  • Publish your bot

If you don’t have an Azure subscription, create a free account before you begin.


Create a bot

Install BotBuilderVSIX.vsix template that you downloaded in the prerequisites section.

In Visual Studio, create a new bot project using the Echo Bot (Bot Framework v4) template.

Visual Studio project


If needed, change the project build type to .Net Core 2.1. Also if needed, update the Microsoft.Bot.Builder NuGet packages.

Thanks to the template, your project contains all the code that's necessary to create the bot in this quickstart. You won't actually need to write any additional code.

Start your bot in Visual Studio

When you click the run button, Visual Studio will build the application, deploy it to localhost, and launch the web browser to display the application's default.htm page. At this point, your bot is running locally.

Start the emulator and connect your bot

Next, start the emulator and then connect to your bot in the emulator:

  1. Click the Create a new bot configuration link in the emulator "Welcome" tab.
  2. Fill out the fields for your bot. Use your bot's welcome page address (typically http://localhost:3978) and append routing info '/api/messages' to this address.
  3. then click Save and connect.

Interact with your bot

Send a message to your bot, and the bot will respond back with a message.

Emulator running


If you see that the message cannot be sent, you might need to restart your machine as ngrok didn't get the needed privileges on your system yet (only needs to be done one time).

Deploy your bot


  • If you don't have an Azure subscription, create a free account before you begin.
  • The bot from above, running on your local machine.
  • Latest version of the Azure cli.

1. Prepare for deployment

When you create a bot using Visual Studio or Yeoman templates, the source code generated contains a deploymentTemplates folder with ARM templates. The deployment process documented here uses the ARM template to provision required resources for the bot in Azure by using the Azure CLI.

Login to Azure

You've already created and tested a bot locally, and now you want to deploy it to Azure. Open a command prompt to log in to the Azure portal.

az login

A browser window will open, allowing you to sign in.

Set the subscription

Set the default subscription to use.

az account set --subscription "azure-subscription"

If you are not sure which subscription to use for deploying the bot, you can view the list of subscriptions for your account by using az account list command. Navigate to the bot folder.

Create an App registration

Registering the application means that you can use Azure AD to authenticate users and request access to user resources. Your bot requires a Registered app in Azure that provides the bot access to the Bot Framework Service for sending and receiving authenticated messages. To create register an app via the Azure CLI, perform the following command:

az ad app create --display-name "displayName" --password "AtLeastSixteenCharacters_0" --available-to-other-tenants
Option Description
display-name The display name of the application.
password App password, aka 'client secret'. The password must be at least 16 characters long, contain at least 1 upper or lower case alphabetical character, and contain at least 1 special character.
available-to-other-tenants The application can be used from any Azure AD tenants. Allowed values: false, true. True by default. This will enable your bot to work with the Azure Bot Service channels

The above command outputs JSON with the key appId, save the value of this key for the ARM deployment, where it will be used for the appId parameter. The password provided will be used for the appSecret parameter.

You can deploy your bot in a new resource group or an existing resource group. Choose the option that works best for you.

Create Azure resources

You'll create a new resource group in Azure and then use the ARM template to create the resources specified in it. In this case, we are providing App Service Plan, Web App, and Bot Channels Registration.

az deployment create --name "name-of-deployment" --template-file "template-with-new-rg.json" --location "location-name" --parameters appId="msa-app-guid" appSecret="msa-app-password" botId="id-or-name-of-bot" botSku=F0 newAppServicePlanName="name-of-app-service-plan" newWebAppName="name-of-web-app" groupName="new-group-name" groupLocation="location" newAppServicePlanLocation="location"
Option Description
name Friendly name for the deployment.
template-file The path to the ARM template. You can use template-with-new-rg.json file provided in the deploymentTemplates folder of the project.
location Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.
parameters Provide deployment parameter values. appId value you got from running the az ad app create command. appSecret is the password you provided in the previous step. The botId parameter should be globally unique and is used as the immutable bot ID. It is also used to configure the display name of the bot, which is mutable. botSku is the pricing tier and can be F0 (Free) or S1 (Standard). newAppServicePlanName is the name of App Service Plan. newWebAppName is the name of the Web App you are creating. groupName is the name of the Azure resource group you are creating. groupLocation is the location of the Azure resource group. newAppServicePlanLocation is the location of the App Service Plan.

Retrieve or create necessary IIS/Kudu files

For C# bots

az bot prepare-deploy --lang Csharp --code-dir "." --proj-file-path "MyBot.csproj"

You must provide the path to the .csproj file relative to --code-dir. This can be performed via the --proj-file-path argument. The command would resolve --code-dir and --proj-file-path to "./MyBot.csproj"

For JavaScript bots

az bot prepare-deploy --code-dir "." --lang Javascript

This command will fetch a web.config which is needed for Node.js apps to work with IIS on Azure App Services. Make sure web.config is saved to the root of your bot.

Zip up the code directory manually

When using the non-configured zip deploy API to deploy your bot's code, Web App/Kudu's behavior is as follows:

Kudu assumes by default that deployments from zip files are ready to run and do not require additional build steps during deployment, such as npm install or dotnet restore/dotnet publish.

As such, it is important to include your built code and with all necessary dependencies in the zip file being deployed to the Web App, otherwise your bot will not work as intended.


Before zipping your project files, make sure that you are in the correct folder.

  • For C# bots, it is the folder that has the .csproj file.
  • For JS bots, it is the folder that has the app.js or index.js file.

Select all the files and zip them up while in that folder, then run the command while still in that folder.

If your root folder location is incorrect, the bot will fail to run in the Azure portal.

2. Deploy code to Azure

At this point we are ready to deploy the code to the Azure Web App. Run the following command from the command line to perform deployment using the kudu zip push deployment for a web app.

az webapp deployment source config-zip --resource-group "new-group-name" --name "name-of-web-app" --src "code.zip" 
Option Description
resource-group Resource group name in Azure that you created earlier.
name Name of the Web App you used earlier.
src The path to the zipped file you created.

3. Test in Web Chat

  • In the Azure portal, go to your Web App bot blade.
  • In the Bot Management section, click Test in Web Chat. Azure Bot Service will load the Web Chat control and connect to your bot.
  • Wait for a few seconds after a successful deployment and optionally restart your Web App to clear any cache. Go back to your Web App Bot blade and test using the Web Chat provided in the Azure portal.

Additional resources

When you deploy a bot, typically these resources are created in the Azure portal:

Resources Description
Web App Bot An Azure Bot Service bot that is deployed to an Azure App Service.
App Service Enables you to build and host web applications.
App Service plan Defines a set of compute resources for a web app to run.

If you create your bot through the Azure portal, you are able to provision additional resources, like Application Insights for telemetry.

To see documentation on az bot commands, see the reference topic.

If you are unfamiliar with Azure resource group, see this terminology topic.

Next steps