Introduction to Microsoft Bot Framework

The Microsoft Bot Framework, is an SDK for building bots. A Bot is an application that automates a response, based on input from an external source such as a person typing. This information comes to the Bot from a Channel. The Bot performs any operations, as instructed, and returns a response. The Azure Bot Service, is an Azure service, where you can host your Bot, and plug in many existing Channels. For this post, we will only be focusing on the Microsoft Bot Framework. Hosting your bot application will come in another post.


Creating a Bot Application

First download the BotApplication template. You can then copy the file into your templates directory.

%USERPROFILE%\Documents\Visual Studio 2017\Templates\ProjectTemplates\Visual C#\

Then create a new Bot Application.

The Bot Application is basically a WebAPI as you will see below. Make sure you open your Nuget Package Manger, to restore the packages needed by this template.

public class MessagesController : ApiController
    /// <summary>
    /// POST: api/Messages
    /// Receive a message from a user and reply to it
    /// </summary>
    public async Task<HttpResponseMessage> Post([FromBody]Activity activity)
        if (activity.Type == ActivityTypes.Message)
            await Conversation.SendAsync(activity, () => new Dialogs.RootDialog());
        var response = Request.CreateResponse(HttpStatusCode.OK);
        return response;

     private Activity HandleSystemMessage(Activity message)
         if (message.Type == ActivityTypes.DeleteUserData)
             // Implement user deletion here
             // If we handle user deletion, return a real message
         else if (message.Type == ActivityTypes.ConversationUpdate)
             // Handle conversation state changes, like members being added and removed
             // Use Activity.MembersAdded and Activity.MembersRemoved and Activity.Action for info
             // Not available in all channels
         else if (message.Type == ActivityTypes.ContactRelationUpdate)
             // Handle add/remove from contact lists
             // Activity.From + Activity.Action represent what happened
         else if (message.Type == ActivityTypes.Typing)
             // Handle knowing tha the user is typing
         else if (message.Type == ActivityTypes.Ping)

         return null;

You can run this application, and call it via https://localhost:XXXXX/api/messages. Its just a WebAPI, but structured specifically for the bot framework. As you can see in this code example, an activity will come into the Post method, and in this sample, will just call the RootDialog, to send back the message you sent, along with how many characters you typed.

This is all a bot it. Accepts input, and returns information. It can connect up to Channels such as Facebook and Slack for input, and what it outputs is all up to you. It can call upon other Azure services such as LUIS or anything you want, its just like an ordinary API at this point.

Activities have a few more functions that I will go into next.

Note: For this example, comment out the [BotAuthentication] to remove any authentication requirements. This is just for testing it locally. You will want to re-enable this, once you deploy.


Activites are the main object that drives the Bot. As you saw, an Activity arrives at the API, and its instructions are derived. The most common type of Activity is a message activity. This is when someone or something has sent a message, but there are other main types of activities.

  • DeleteUserData
  • ConversationUpdate
  • ContactRelationUpdate
  • Typing
  • Ping

If you want to know what each does, just read the comments in the code from the template, it explains each one. They are mostly self explanatory. However, there are even more types, and these may be expanded in the future.

  • EndOfConversation
  • Trigger
  • Event
  • Invoke
  • InstallationUpdate

Keeping to these conventions, will help your bot interact with more services in the future.

Bot Emulator

If you want to test out the application, you can download the Bot Emulator.

Once installed, run the desktop application. Make sure you enter the url at the top, and press the connect button. Pressing the connect button is essential. You don’t need to enter any AppId or Password, at this stage.

Once connected, you can type in Hi, and it will respond as per the code above.

If the log, shows text in red at the side, it means there is an error and it didn’t connect correctly.

Learn More

There are many places you can learn more about the Bot Framework. I will continue blogging about it here, but other places you can find more information include, the Bot Framework Documentation, Azure Bot Services and Building a Chat Bot with Azure Bot Service, if you want a Video walk through, along with LUIS and Slack integration examples.