Microsoft Bot Framework: Let’s Get Chatty!

Bots are exploding in popularity as the new frontier in user experience. Instead of logging in to a Web site or launching an app, users can interact with your company in FaceBook, Slack, and more. They can use natural language to ask for assistance or information and get answers to their pressing questions without ever leaving these popular environments.

All of the platforms that allow bots have their own SDK that can allow you to build custom bots on those platforms. Unfortunately, if you do that, you’ll find yourself locked into that platform or, worse yet, coding slightly different copies of your bot for each platform.

To solve the problem, Microsoft introduced the Bot Framework. The Bot Framework allows you to create a single bot that can connect to email, GroupMe, Kik, Skype, Telegram, Slack, SMS Text Messaging, and even into your Web site’s chat function. The Bot Framework provides the basic infrastructure and model to pass messages to and from your users in all of these channels.


A Microsoft Bot is composed of Bot endpoint created using the SDK that you can host anywhere you like and the Microsoft Bot Framework that is hosted by Azure. The Azure Microsoft Bot Connector handles the passing of messages to and from the various channels it supports and routes them to your bot wherever you elect to host it.

Getting Started

Download the Bot Application template and copy it into your “%USERPROFILE%\Documents\Visual Studio 2015\Templates\ProjectTemplates\Visual C#” folder. If you have Visual Studio open, close it and relaunch it.

Now, when you create a new project, you should have the “Bot Application” project template available in the new project dialog. After you create a new project using this template, also use the Nuget package manager to install “Microsoft.Bot.Builder” into your project. This will update all of your dependencies to the latest version because the exemplar template Microsoft provides has some out-of-date references.

Exploring the Bot Application Template

The Bot Application template creates a single controller in the Controllers folder, called “MessagesController.cs”, which contains two methods. The “Post” method is called any time the remote user sends you a message and the “HandleSystemMessage” method is called any time there is an event between the user and the server like user added/removed from conversation, pings, and conversation termination.

The example “Post” method, below, gives a single static reply from any message with the number of characters the user entered. What’s notable here is the if statement around the message.Type. This statement splits out the difference between messages that the user typed and system messages.

public async Task<Message> Post([FromBody]Message message)
   if (message.Type == "Message")
      int length = (message.Text ?? string.Empty).Length;
      return message.CreateReplyMessage($"You sent {length}
      return HandleSystemMessage(message);

The web.config file contains an AppId and an AppSecret. You will need to change these values to some other random jumble of numbers and characters before publishing your app.

To test your app, download the Bot Emulator.

Debugging is as simple as clicking “Play” in Visual Studio, which will launch your Web browser and then launch the bot emulator outside of Visual Studio. At the top of the Bot Framework Emulator is a URL, AppId, and AppSecret. You will need to change this URL to match the port number that Visual Studio launched in your Web browser and you will need to take the AppId and AppSecret from your web.config file and paste them into the app emulator.

Once you have updated these values, you can use the chat window to start chatting with your bot, as seen in Figure 1. When you send a message to the bot, the pane on the right side of the dialog shows the JSON response that was sent back from your bot. This response contains a lot of meta-data in addition to the message including the channelMessageId and a full list of the participants in the message thread.

Figure 1: The chat bot in action

Connecting to the Bot Connector

Before you can connect your bot to the Bot Connector, you will need to publish it on the Internet. You can do this on any IIS Web server or publish it to Azure the same way you would publish any Web site. To publish it to Azure, right-click the project root and choose “publish”. Set the publish target to “Microsoft Azure App Service” and create a new app for your service. Make note of the destination URL for your service; you will need this URL later on when you register your bot with the Bot Connector.

If Visual Studio freezes on the “Create App Service” dialog, you will need to log into the Azure hosting Web portal and create the app service in-browser.

To register your bot, go to and choose “Register” at the top of the page. When you create your bot, the key values to note are the “Endpoint URL”, which should be “”, and the AppID, which should match the AppID in your web.config file.

Now that your connector has been created, you will need to get the app secret it assigned your app from the left side of the screen and paste it into your web.config’s AppSecret key, then re-publish it to Azure. You now can use the emulator to connect to your published service by updating the URL to your hosted end point. It’s worth noting that you will need to connect via HTTPS or it will error.

Connecting Your Bot Connectors to Channels

Each connector contains a specialized configuration that you will need to do to enable your bot to work in that channel. For email, you can connect it to an Office365 email account. For SMS, you can create a Twilio account and configure it. Most of the channels require you to sign up for a developer account and embed the appropriate AppIDs and Secrets to connect your bot to those services.

The only connector configured by default is Web Chat, which will require some additional configuration to work. Click “Edit” next to Web Chat and choose “Generate Web Chat Secret”. Take the embed code provided and create a simple Web page that embeds this IFRAME code. Modify “YOUR_SECRET_HERE” to include the Secret from the Web Chat configuration page. You should now be able to view this site in a browser and be able to chat with your chat bot.

Next Steps

The Microsoft Bot Framework provides the common infrastructure necessary to pass messages between many common chat interfaces and your server. Although this can be good enough if your bot just needs to respond to basic commands like a command line interface (Press 1 to order coffee), it does not perform the natural language recognition to make sense of free form human language (“Can I get a coffee?”). To do that, you’ll need to tap into Microsoft’s Cognitive API that includes the Language Understanding Intelligent Service (LUIS) that can parse natural human language and disassemble it into an easy-to-program format for actions.

In the next article in this series, we’ll take a look at how LUIS can parse the meaning of what the user is saying and how the bot framework’s Dialog (a conversation, not a dialog window!) objects can build a conversation.

More by Author

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Must Read