How to Setup an Chatbot Development Environment for Microsoft Bot Framework Version 4 — Part 1 3

A chatbot is an emerging application of AI (Artificial Intelligence) that is becoming more common nowadays. Maybe you used one and thought it was useful and want to try to build one yourself. Maybe your company wants to have a chatbot to answer some of the commonly asked questions. Regardless of the reason, you want to venture into developing a chatbot.

The first step and most important step to development are to set up the development environment. It is also one of the most painful parts of the process. So, to save you some pain, in this post, I am going to share with you how to set up a development environment for the bot framework v4.

Note: As of writing this post, bot framework v4 got recently released. Things are always changing and the content in this post may not 100% reflect on the development experience later down the line.

What You Need

• Visual Studio 2017 (Mac or Windows)
• Bot Framework Emulator
• An Azure account
• MSBot command line tool
• Microsoft sample bot projects — you’ll need them for reference

So, if you thought “What? Developing Microsoft technology on a Mac?”. Guess what? You heard (read) that right. Chatbot development uses .Net Core, which is multiplatform unlike .Net Framework.

Note: As of writing this post, version 4 of the Bot Framework Emulator has a bug in Mac, where it may not open the chat with a bot running locally. If you are running into issues talking to the bot, use version 3. Version 4.1.0 of the Bot Framework Emulator is out now and the bug on mac is fixed. You can use either version 3 or 4, the post have instructions to use both versions.

Start the Fast and Easy Way

One of the biggest headaches you’ll face with developing a bot using the bot framework is the configurations because documentations are always behind the actual changes to the technology. So, to get around this problem, you’ll have Azure generate a working bot for you, which includes all the proper configurations.

Use Azure to Create a Working Chatbot

To create a bot on Azure, please follow the instructions by Microsoft. For the bot template, choose the Basic Bot C# project instead of the echo bot. The instructions to create a web app bot on Azure is at https://docs.microsoft.com/en-us/azure/bot-service/bot-service-quickstart?view=azure-bot-service-4.0.

At this point, I assume you have created a web app bot on Azure. If you haven’t, do go and do it now and come back.

Natural Language Processing Service

Alright, so now you have a basic bot that uses NLP (natural language processing) to understand what is being said. As a side note, Microsoft calls their NLP service LUIS (Language Understanding). A LUIS app got generated when you created your web app bot on Azure. To see your LUIS app, go to https://www.luis.ai. It will have the same name as your chatbot with some random alphanumeric value added to the end.

Get the Source Code for Your Bot on Azure

In the Azure portal, go to your web app bot. In the Bot Management section, select Build and click on the Download Source Code button. This will generate the source code for the bot and download it to your local machine.

You may want to keep a copy of it because once you deploy to this bot after making some changes locally and things break you can’t have access to the original source code.

Run the Bot Locally

Setting up the bot to run locally with the generated source code consists of two main steps. Updating a settings file and connecting the bot to the bot framework emulator.

Update Settings

Before you can run the bot locally, you need to update the file “appsettings.json”. You need to add the bot file path and the bot file secret into the file. To find the bot file path and bot file secret, go to your Azure web app bot then go to App Service Settings > Application Settings.

The values will be hidden so you need to click the Show Values button then copy and paste them into your appsettings.json file.

Here is how your appsettings.json file should look like afterward:

{
  "botFilePath" : "PUT YOUR BOT PATH FROM AZURE HERE", 
  "botFileSecret" : "PUT YOUR BOT SECRET FROM AZURE HERE"
}

Now it’s time to run your bot locally. Build it and run in Visual Studio. If your bot successfully initializes then you will get a web page popup that says your bot is ready.

At this point, the bot is running locally and you can connect to the bot with the bot framework emulator to talk with the bot.

Connecting to Bot with Bot Framework Emulator

The steps will vary based on if you’re using version 3 or 4 of the emulator. In either case, you need to have your bot running locally already.

Version 4

• Open the bot framework emulator and choose to open a bot file.
• Navigate to the root of the bot source code and select the .bot file
• The bot framework will ask you to input the bot secret (use the one in the appsettings.json)
• Start chatting with the bot

Version 3

• Connect to the bot through URL endpoint — read through this section first
• In the bot framework emulator enter in the endpoint and set your locale (no id or password is needed)
• The endpoint is the URL in the webpage that says your bot is ready plus “/api/messages/”
• For example, an endpoint will be like http://localhost:5000/api/messages

• Press connect
• Talk with the bot

Deploy to Azure

Deploying your local changes to your Azure web app bot is simple with Visual Studio. In Visual Studio, right click on your root project in the solution explorer and there is an option to publish.

Select the publish option and you’ll be prompted to log in to your Azure account if you are not logged in. You’ll be presented with a list of web app bots to deploy your local changes to. Select the bot you want to deploy your changes to and let Visual Studio handle the rest.

Once publishing is complete, you’ll get a web page popup notifying you publishing was successful and that your bot is ready. To test the bot, on Azure go to the web app bot then Bot Management > Test in Web Chat. Chat with the bot to see the changes you made and verify you still have a working bot.

Gotchas and Troubleshooting

How Do I Add a New Service to the Bot Configuration File?

The configurations are probably one of the most confusing parts of the bot development process — at least as of the writing of this post. There is a command line tool to do the modifications for you. It is called, “MsBot” and can be found at the MsBot GitHub. It adds the services for you and encrypts the bot file so that it does not cause the bot to throw an error when you run your bot.

I Added a New Service to the Bot Configuration File and Now There Is an Error About Bot File Not Valid

You probably added the service manually. This doesn’t work if your bot file is encrypted with a secret key. To properly add a service to the configuration file, use the MSBot command line tool.

The Bot Is Running, but I Can’t Connect to It Locally with Bot Framework Emulator on Mac

As of writing this post, Bot Framework v4 doesn’t work so well on Mac. You should use v3 and then enter the endpoint URL with the locale of your bot to talk to it locally. Please refer to the section Connecting to Bot With Bot Framework Emulator of the post if you need help.

I hope this post was helpful to you. If you found this post helpful, share it with others so they can benefit too.

What are your experiences working with the bot framework?

To get in touch, you can follow me on Twitter, leave a comment, or send me an email at steven@brightdevelopers.com.