Create a bot with the Bot Framework SDK

APPLIES TO: SDK v4

In this quickstart, you'll learn how to build your first bot with the Bot Framework SDK for C#, Java, JavaScript or Python, and how to test your bot with the Bot Framework Emulator.

Creating your first bot doesn't require an Azure subscription or an Azure Bot Service resource. This quickstart focuses on creating your first bot locally. If you'd like to learn how to create a bot in Azure, see Create an Azure Bot resource.

Prerequisites

C#

• ASP.NET Core Runtime 3.1
• Bot Framework Emulator
• Knowledge of ASP.NET Core and asynchronous programming in C#

Templates

Visual Studio

• Visual Studio 2019 or later
• Bot Framework v4 SDK Templates for Visual Studio

To add the bot templates to Visual Studio, download and install the Bot Framework v4 SDK Templates for Visual Studio VSIX file.

Note

The VSIX package includes both .NET Core 2.1 and .NET Core 3.1 versions of the C# templates. When creating new bots in Visual Studio 2019 or later, you should use the .NET Core 3.1 templates. The current bot samples use .NET Core 3.1 templates. You can find the samples that use .NET Core 2.1 templates in the 4.7-archive branch of the BotBuilder-Samples repository.

To install the templates in Visual Studio, in the top menu bar, navigate to Extensions > Manage Extensions. Then search for and install Bot Framework v4 SDK for Visual Studio.

For information about deploying .NET Core 3.1 bots to Azure, see how to deploy your bot to Azure.

VS Code / CLI

.NET Core Templates will help you to quickly build new conversational AI bots using Bot Framework v4. As of May 2020, these templates and the code they generate require .NET Core 3.1.

To install the Bot Framework templates:

1. Open a console window.

2. Download and install .NET Core SDK download version 3.1 or later.

3. You can use this command to determine which version of the .NET Core command-line interface you have installed.

   dotnet --version
   

4. Install the three Bot Framework C# templates: the echo, core, and empty bot templates.

   dotnet new -i Microsoft.Bot.Framework.CSharp.EchoBot
   dotnet new -i Microsoft.Bot.Framework.CSharp.CoreBot
   dotnet new -i Microsoft.Bot.Framework.CSharp.EmptyBot
   

5. Verify the templates have been installed correctly.

   dotnet new --list
   

Note

The above installation steps will install all three Bot Framework templates. You don't need to install all the templates and can install just the ones you will use. This article makes use of the echo bot template.

Java

• Java 1.8 or later
• Bot Framework Emulator
• Visual Studio Code or your favorite IDE, if you want to edit the bot code.
• Install Maven
• Install node.js version 12.10 or later.
• An Azure account if you want to deploy to Azure.

Templates

Use the Yeoman generator to quickly set up a conversational AI bot using core AI capabilities in the Bot Framework v4. For more information, see yeoman.io.

The generator supports three different template options as shown below.

Template	Description
Echo Bot	A good template if you want a little more than "Hello World!", but not much more. This template handles the very basics of sending messages to a bot, and having the bot process the messages by repeating them back to the user. This template produces a bot that simply "echoes" back to the user anything the user says to the bot.
Empty Bot	A good template if you are familiar with Bot Framework v4, and simply want a basic skeleton project. Also a good option if you want to take sample code from the documentation and paste it into a minimal bot in order to learn.
Core Bot	A good template if you want to create advanced bots, as it uses multi-turn dialogs and LUIS, an AI based cognitive service, to implement language understanding. This template creates a bot that can extract places and dates to book a flight.

Install Yeoman

1. Assure that you have installed node.js version 12.10 or later.

2. Install latest npm.

   npm install -g npm
   

3. Install Yeoman. Make sure to install globally.

   npm install -g yo
   

4. Install generator-botbuilder-java. Make sure to install globally.

   npm install -g generator-botbuilder-java
   

5. Verify that Yeoman and generator-botbuilder-java have been installed correctly.

   yo botbuilder-java --help
   

JavaScript

• Node.js
• Bot Framework Emulator
• Knowledge of restify and asynchronous programming in JavaScript
• Visual Studio Code or your favorite IDE, if you want to edit the bot code.

Templates

To install Yeoman and the Yeoman generator for Bot Framework v4:

1. Open a terminal or elevated command prompt.

2. Switch to the directory for your JavaScript bots. Create it first if you don't already have one.

   mkdir myJsBots
   cd myJsBots
   

3. Make sure you have the latest versions of npm and Yeoman.

   npm install -g npm
   npm install -g yo
   

4. Install the Yeoman generator. Yeoman is a tool for creating applications. For more information, see yeoman.io.

   npm install -g generator-botbuilder
   

   Note

   The install of Windows build tools listed below is only required if you use Windows as your development operating system. For some installations, the install step for restify is giving an error related to node-gyp. If this is the case you can try running this command with elevated permissions. This call may also hang without exiting if Python is already installed on your system:

   Only run this command if you are on Windows.

   npm install -g windows-build-tools
   

Python

• Python 3.8.3
• Bot Framework Emulator
• Knowledge of asynchronous programming in Python

Create and enable a virtual environment

A virtual environment is a combination of a specific Python interpreter and libraries that are different from your global settings. The virtual environment is specific to a project and is maintained in the project folder. A benefit to using a virtual environment is that as you develop a project over time, the virtual environment always reflects the project's exact dependencies. To learn more about virtual environments, see Creation of virtual environments.

Navigate to the directory where you want to create your bot. Then run the following commands for your preferred platform. After you activate your virtual environment, your command line/terminal should be prefaced with (venv). This lets you know that the virtual environment is active. You can deactivate your virtual environment at any time by typing: deactivate.

macOS/Linux

python3 -m venv venv
source venv/bin/activate

Windows

python -m venv venv
venv\Scripts\activate.bat

Templates

Install the necessary packages by running the following pip install commands:

pip install botbuilder-core
pip install asyncio
pip install aiohttp
pip install cookiecutter==1.7.0

Important

If you're using a 32-bit version of Python, make sure you also run pip install cryptography==2.8.

Create a bot

C#

Visual Studio

In Visual Studio, create a new bot project using the Echo Bot (Bot Framework v4 - .NET Core 3.1) template. To see only bot templates, choose AI Bots from the project types.

Thanks to the template, your project contains all the necessary code to create the bot in this quickstart. You don't need any additional code to test your bot.

VS Code

Make sure that .NET Core 3.1 is installed.

1. In Visual Studio Code, open a new terminal window.

2. Navigate to the directory in which you want to create your bot project.

3. Create a new echo bot project using the following command. Replace <your-bot-name> with the name to use for your bot project.

   dotnet new echobot -n <your-bot-name>
   

CLI

1. Open a new terminal window.

2. Navigate to the directory in which you want to create your bot project.

3. Create a new echo bot project using the following command. Replace <your-bot-name> with the name to use for your bot project.

   dotnet new echobot -n <your-bot-name>
   

Tip

If you create a Core bot:

• Only the solution directory receives the bot name.
• You'll need a LUIS language model. You can create a language model at luis.ai. After creating the model, update the configuration file.

I created an echo bot I ran into an issue

Java

Run the following command to create an echo bot from templates. The command uses default options for its parameters.

yo botbuilder-java -T "echo"

Yeoman prompts you for some information with which to create your bot. For this tutorial, use the default values.

? What's the name of your bot? (echo)
? What's the fully qualified package name of your bot? (com.mycompany.echo)
? Which template would you like to start with? (Use arrow keys) Select "Echo Bot"
? Looking good.  Shall I go ahead and create your new bot? (Y/n) Enter "y"

The generator supports a number of command line options that can be used to change the generator's default options or to pre-seed a prompt. The options are case-sensitive.

Command-line option	Description
--help, -h	List help text for all supported command-line options
--botName, -N	The name given to the bot project
--packageName, -P	The Java package name to use for the bot
--template, -T	The template used to generate the project. Options are echo, empty, core. See https://github.com/Microsoft/BotBuilder-Samples/tree/main/generators for additional information regarding the different template options their functional differences.
--noprompt	The generator will not prompt for confirmation before creating a new bot. Any requirement options not passed on the command line will use a reasonable default value. This option is intended to enable automated bot generation for testing purposes.

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

Note

If you create a Core bot, you'll need a LUIS language model. You can create a language model at luis.ai. After creating the model, update the configuration file.

I created an echo bot I ran into an issue

JavaScript

1. Use the generator to create an echo bot.

   yo botbuilder
   

   Yeoman prompts you for some information with which to create your bot. For this tutorial, use the default values.

   ? What's the name of your bot? my-chat-bot
   ? What will your bot do? Demonstrate the core capabilities of the Microsoft Bot Framework
   ? What programming language do you want to use? JavaScript
   ? Which template would you like to start with? Echo Bot - https://aka.ms/bot-template-echo
   ? Looking good.  Shall I go ahead and create your new bot? Yes
   

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

Note

If you create a Core bot, you'll need a LUIS language model. You can create a language model at luis.ai. After creating the model, update the configuration file.

I created an echo bot I ran into an issue

Python

1. From your working directory, run the following command to download the echo bot template and its dependencies:

   cookiecutter https://github.com/microsoft/BotBuilder-Samples/releases/download/Templates/echo.zip
   

2. You'll be prompted to give your bot a name and description. Enter the following values:

   • bot_name: echo_bot
   • bot_description: A bot that echoes back user response.

   

I created an echo bot I ran into an issue

Start your bot

C#

Visual Studio

In Visual Studio

1. Open your bot project.
2. Run the project without debugging.

This 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 on port 3978.

VS Code

To run your bot from VS Code:

1. Open your bot project folder.

   If you're prompted to select a project, select the one for the bot you just created.

2. Go to Run, and then select Run Without Debugging.

   

   • Select the .Net Core environment.

   

   • If this command updated your launch settings, save the changes and rerun the command.

This 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 on port 3978.

CLI

To run your bot locally in a command prompt or terminal:

1. Change directories to the project folder for your bot.

2. Use dotnet run to start the bot.

   dotnet run
   

This will build the application and deploy it to localhost. The application's default web page will not display, but at this point, your bot is running locally on port 3978.

I started the echo bot I ran into an issue

Java

1. From a terminal, navigate to the directory where you saved your bot, then execute the commands listed below.

2. Build the Maven project and packages it into a .jar file (archive).

   mvn package
   

3. Run the bot locally. Replace the archive-name with the actual name from the previous command.

   java -jar .\target\<archive-name>.jar
   

You are now ready to start the Emulator.

I started the echo bot I ran into an issue

JavaScript

In a terminal or command prompt change directories to the one created for your bot, and start it with npm start.

cd my-chat-bot
npm start

At this point, your bot is running locally on port 3978.

I started the echo bot I ran into an issue

Python

1. From the command line/terminal, change directories to echo_bot.

   cd echo_bot
   

2. Install the dependencies for the echo bot template.

   pip install -r requirements.txt 
   

3. After the dependencies are installed, run the following command to start your bot:

   python app.py
   

   You will know your bot is ready to test when you see the last line shown in the screenshot below:

   

4. Copy the http address in the last line. You will need it when you use the Emulator to interact with your bot.

I started the echo bot I ran into an issue

Start the Emulator and connect your bot

1. Start the Bot Framework Emulator.

2. Select Open Bot on the Emulator's Welcome tab.

3. Enter your bot's URL, which is your local host and port, with /api/messages added to the path. The address is usually: http://localhost:3978/api/messages.

   

4. Then select Connect.

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

   

I started the Emulator and connected to my bot I ran into an issue

Additional Resources

• See Debug a bot for how to debug using Visual Studio or Visual Studio Code and the Bot Framework Emulator.
• See Tunneling (ngrok) for information on how to install ngrok.

Next steps

Deploy your bot to Azure