Microsoft Bot Framework – part 2

Short introduction

Microsoft Bot Framework enables developers to create intelligent applications to communicate with users. In the first part I described some key concepts connected with Bot Framework and in this article I would like to discuss the source code of created Bot.

Basic bot source code

During Bot creation in Microsft Azure portal (described in part 1) I chose “Basic C#” template for Bot. Now lets discover how source code of such Bot looks like.

 

Download source code of your Bot from Azure Portal:

Open project in Visual Studio:

 

First class we will review is called “MessagesController” and its located in “Controllers” folder:

 [BotAuthentication]
    public class MessagesController : ApiController
    {
        /// 
<summary>
        /// POST: api/Messages
        /// receive a message from a user and send replies
        /// </summary>

        /// <param name="activity"></param>
        [ResponseType(typeof(void))]
        public virtual async Task<HttpResponseMessage> Post([FromBody] Activity activity)
        {
            // check if activity is of type message
            if (activity != null && activity.GetActivityType() == ActivityTypes.Message)
            {
                await Conversation.SendAsync(activity, () => new EchoDialog());
            }
            else
            {
                HandleSystemMessage(activity);
            }
            return new HttpResponseMessage(System.Net.HttpStatusCode.Accepted);
        }

        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;
        }
    }

BotAuthentication

It is important to secure access to the Bot. To prevent unauthorized access “MessagesController” class has “BotAuthentication” attribute. To access Bot you have to provide “MicrosoftAppId” and “MicrosoftAppPassword”. You can find them in Azure portal in your Bot settings:

Now with AppId and Password you can test connection to your Bot from Bot Emulator:

You have to paste AppId and Password in “Web.config” file:

Activity

An Activity is the basic communication type for the Bot Framework 3.0 protocol. Activity object is used to pass information back and forth between bot and channel (user). The most popular Activity is message (which represents a communication between Bot and user) but there are others like typing (when user or bot is typing the response). You can read more here.

Conversation

Conversation represents channel between Bot and user through which new activities (like messages) are reported. You can model conversation flow

EchoDialog

Second class we will review is called “EchoDialog” and its located in “Dialogs” folder:


  [Serializable]
    public class EchoDialog : IDialog<object>
    {
        protected int count = 1;

        public async Task StartAsync(IDialogContext context)
        {
            context.Wait(MessageReceivedAsync);
        }

        public async Task MessageReceivedAsync(IDialogContext context, IAwaitable<IMessageActivity> argument)
        {
            var message = await argument;

            if (message.Text == "reset")
            {
                PromptDialog.Confirm(
                    context,
                    AfterResetAsync,
                    "Are you sure you want to reset the count?",
                    "Didn't get that!",
                    promptStyle: PromptStyle.Auto);
            }
            else
            {
                await context.PostAsync($"{this.count++}: You said {message.Text}");
                context.Wait(MessageReceivedAsync);
            }
        }

        public async Task AfterResetAsync(IDialogContext context, IAwaitable<bool> argument)
        {
            var confirm = await argument;
            if (confirm)
            {
                this.count = 1;
                await context.PostAsync("Reset count.");
            }
            else
            {
                await context.PostAsync("Did not reset count.");
            }
            context.Wait(MessageReceivedAsync);
        }
    }

IDialog

Interface from Microsoft.Bot.Builder.Dialogs namespace. Each C# class which extends this interface is an abstraction that encapsulates its own state. Use dialogs to model a conversation and manage conversation flow.

It is worth to say few more words about Dialogs here.

Like apps and websites, bots have a UI, but it is made up of dialogs, rather than screens. Dialogs may or may not have graphical interfaces. They may contain buttons, text, and other elements, or be entirely speech-based. Dialogs also contain actions to perform tasks such as invoking other dialogs or processing user input.

Below there is a diagram to show comparsion between the screen flow of a traditional application compared to the dialog flow of a bot:

When one dialog invokes another, the Bot Builder adds the new dialog to the top of the dialog stack. The dialog that is on top of the stack is in control of the conversation.

IDialogContext

IDialogContext interface represents context of current conversation between user and Bot. Below you can see inheritance diagram for IDialogContext:

Please note that “MessageReceivedAsync” method has two parameters: context and argument. It means that for each new message sent to Bot there is specific context and argument assigned.

 

Wrapping up

Microsoft Bot Framework enables creating smart applications which can communicate with users with natural conversation flow. Developers are able to write specific functionality of bots using Bot Builder SDK available for NET C# and Node.js and host their bots on Microsoft Azure platform. If you would like to read more please refer to official documentation.

In the next part I will show how to connect Bot to different channels like Skype and how to communicate with created Bot from Xamarin application.

Advertisements