Step 1: Connecting to Azure

Our first step is to log into the Azure Portal. If you have an Azure account, excellent. Skip ahead to step 2 if you have an Azure subscription already. If you do not, you are able to create a free developer account with a $200 30-day credit by going to https://azure.microsoft.com/en-us/free/ .

Click “Start free.” You will need to log in using a Microsoft or work account. If you have neither, you can easily create a Microsoft account at https://account.microsoft.com/account . Once you’re authenticated, you will see a page like in Figure 5-7. This page will collect your personal information and verify your identity via a text message and a valid credit card. Don’t be alarmed. The credit card is necessary to verify your identity. Chances are, you will not come even close to using the $200 credit, and if you do, you will not be charged; you will just not be able to use the services further. Much of what we use Azure for in this book can be accommodated via a free tier of the various Azure services.

Once the process is done, you will be able to go into the Azure Portal at https://portal.azure.com . It looks something like Figure 5-8. On the top right, you will see the email address you signed up with and your directory name. For example, if my email were szymon.rozga@aol.com (it’s not), then my directory name would be SZYMONROZGAAOL. If you were added into other directories, that menu would be a drop-down for you to select to which directory you are navigating.

An Azure account contains subscriptions. A subscription is a billing entity. If we navigate to https://portal.azure.com/#blade/Microsoft_Azure_Billing/SubscriptionsBlade , or the Subscriptions service in the portal, and we had just created the $200 trial account, we should see one subscription with the name Free Trial. Each Azure subscription can also contain one or more resource groups. A resource group is a logical container for resources, which are individual Azure services. All costs associated with resources in each resource group are charged against the payment method associated with the containing subscription. With the $200 trial account, services are automatically shut down when the combined costs reach the spending limit. If desired, the free account can be converted to a paid account that will accrue additional charges to your credit card (or alternative payment options).

Step 2: Creating the Bot Registration

In the Azure Portal, click the “Create a resource” button in the top-left pane. In the Search the Marketplace text field, enter azure bot. You will get many results, but we are interested in the top three (Figure 5-9).

For our purposes, we will create a Bot Channels Registration bot, as we will keep on running the bot locally on our laptop. Click Bot Channels Registration and then click Create. As per Figure 5-10, enter a bot name, the name for the resource group that will contain this registration, and the resource location, namely, the Azure region that will host the registration. For Pricing Tier, select F0; this is the free option and sufficient for our needs. Leave the messaging endpoint empty for now and leave Application Insights selected to On. Application Insights is one of Microsoft’s cloud telemetry and logging services. The Bot Framework uses this to store data and analytics on your bot registration usage. By default, this will create the basic and free tier of Application Insights. Select as close a location to the Bot Channels Registration location as possible. Click Create when ready.

There is a progress indicator across the top of the portal, and we will receive a notification when the registration is ready. We can also navigate into the resource group by using the Resource Groups button on the left pane (Figure 5-11).

Navigate into the bot channel registration and then navigate to the Settings blade (Figure 5-12). Note that Azure automatically populated the Application Insights identifiers and keys. These will be used to track analytics data for our bot. We will see one of the resulting analytics dashboards in Chapter 13.

We will also be shown the Microsoft App ID. Take note of this value. Click the Manage link directly above it to navigate to the Microsoft Application Portal. This may ask for our login information once again because it is a separate site from Azure. Once we locate the newly created bot in the list of applications, click Generate New Password (in the Application Secrets section) and save the value; you will see it once only! Recall that we were seeing warnings that our bot was not secure in the bot console output? We will now fix that.

Step 3: Securing Our Bot

In the directory containing the echo bot code, create a file called .env and provide the Microsoft App ID and the password:

Shut down and restart the bot (npm start).

If we try to connect from the emulator now, the emulator will show the following log messages:

The bot console output will contain the following message:

It seems a bit more secure now, right? We must enter the same app ID and password on the emulator side. Click the “Edit our bot’s MSA (Microsoft Account) info” link, and enter the data into the emulator. If we try to connect using the emulator now, it will work fine. Send a message to the bot to confirm before continuing.

Step 4: Setting Up Remote Access

We could deploy the bot to Azure, connect the Facebook connector to that endpoint, and call it a day. But how do we develop or debug Facebook-specific features? The Bot Framework way is to run a local instance of the bot and connect a test Facebook page to the local bot for development.

To achieve this, run ngrok from the command line.

We will be presented with the data in Figure 5-13. By default, ngrok assigns a random subdomain (paid ngrok versions allow you to specify a domain name). In this case, my URL is https://cc6c5d5f.ngrok.io . Note that the free version of ngrok provides a random subdomain each time we run it. We can get around this by either upgrading to a paid version or simply leaving the ngrok session up for as long as possible.

Let’s see if this works. In the emulator, enter the ngrok URL followed by /api/messages. For instance, for the previous URL, the correct messaging endpoint is https://cc6c5d5f.ngrok.io/api/messages . Add the app ID and app password information into the emulator. Once you click Connect, the emulator should successfully connect to and chat with the bot.

Now, assign the same messaging endpoint URL in the Bot Channels Registration Settings blade, Figure 5-12. Next, navigate to the Test with Web Chat blade and try to send a message to the bot. It should work. You’ve connected your first channel to your bot (Figure 5-14)!

Step 5: Connecting to Facebook Messenger

Pretty cool, right? The Bot Framework is almost completely integrated with our bot. We will now proceed to integrate our bot with Facebook Messenger. The Channels blade on the Bot Channels Registration gives us an ability to connect to the Microsoft-supported channels (Figure 5-15).

Click the Facebook Messenger button to go into the Messenger configuration screen (Figure 5-16). We are going to need to get four pieces of data from Facebook: page ID, app ID, app secret, and page access token. Lastly, we should take note of the callback URL and verify token. We will need these to set up connectivity between Facebook and the Bot Framework.

Let’s now set up the necessary Facebook assets. We must have a Facebook account to complete the following tasks. Navigate to Facebook.com and use the top-right drop-down menu to create a new page (Figure 5-17). Facebook will ask for the type of page. For the purposes of this example, we can select the Brand/Product type and App Page subcategory.

I created a page called Szymon Test Page. We can find the page ID by clicking to the About link on the left navigation pane (Figure 5-18). On the very bottom we will find the page ID. We need to copy that value into the Bot Framework Facebook Messenger channel configuration form (Figure 5-16).

Next, in a new browser tab or window, navigate to https://developers.facebook.com . If you have not yet done so, register for a developer account. Create a new app (Figure 5-19). Give it any name you like.

Once you do, navigate to the Settings ➤ Basic page via the left sidebar menu and copy the Facebook app ID and app secret into the Bot Framework form (Figure 5-20).

Next, navigate to the Dashboard (from the link on the left sidebar) and set up the Messenger product. Scroll down the page until you get to the Token Generation section. Generate a page access token by selecting the page in the Token Generation section (Figure 5-21). Copy the token into the Bot Framework form within the Azure Portal.

Next, scroll to the Webhooks section (just below the Token Generation section of the Facebook App Dashboard) and click Setup Webhooks. You will see a pop-up that asks you for a callback URL and the verify token. Copy and paste both of those from the Configure Facebook Messenger form in the Azure Portal.

Click Verify and Save. Lastly, select the page you would like your bot to subscribe to from the drop-down and click Subscribe. Your setup page should look as shown in Figure 5-22.

Make sure to save the Bot Framework configuration. That’s it! You can find the page in your Messenger contacts. You can send it a message, and you should get it echoed back (Figure 5-23).

Step 6: Deploying to Azure

It would not be a complete tutorial if we did not deploy the code into the cloud. We will create a web app and deploy our Node.js app using Kudu ZipDeploy. Lastly, we will point the bot channel registration to the web app.

Go into your Azure resource group that we created in step 2 and create a new resource. Search for web app. Select Web App and not Web App Bot. The Web App Bot is a combination of a bot channel registration and an app service. We have no need for this combination since we have already created a bot channel registration.

When creating the web app, we will need to give it a name. Also ensure the correct resource group is selected (Figure 5-24). Azure will add it to our existing resource group and create a new app service plan for us. An app service plan is a container for web apps and similar compute resources; it defines the hardware on which our apps run as well as the costs. In Figure 5-24, we create a new app service plan and choose the Free pricing tier. Free is good.

Before we deploy our echo bot, we need to add two things. First, we add a response to the base URL endpoint to validate our bot was deployed. Add this code to the end of the app.js file:

Second, for a Windows-based Azure setup, we also need to include a custom web.config file to tell Internet Information Services (IIS)² how to run a Node app.³

Next, we visit our bot web app via the browser. In my case, I navigate to https://srozga-test-bot-23.azurewebsites.net . There will be a default “Your App Service app is up and running” page. Before we deploy, we must zip the echo bot for transfer to Azure. We zip all the application files, including the node-modules directory. We can use the following commands:

Now that we have a zip file, we have two options as to how we deploy. In option 1, we use a command line to deploy the bot by using the Kudu⁴ endpoint at https://{WEB_APP_NAME}.scm.azurewebsites.net. To enable this, we must first visit the Deployment Credentials blade in the app service (Figure 5-25) to set up a deployment username and password combination.

Once done, we are ready to roll. Running the following curl command will kick off the deployment process:

Once you run this, curl will ask for the password that was provided in Figure 5-25. It will upload the zip and set up the app on the app service. Once done, make a request to your app’s base URL, and you should see a 200 response with success set to true.

The alternative way to deploy is to use the Kudu interface on the SCM website: https://srozga-test-bot-23.scm.azurewebsites.net/ZipDeploy . You can simply drag and drop your zip file on the file listing in Figure 5-26.

There’s one more step. Go into the Settings blade in the Bot Channels Registration entry and set the messages endpoint setting to your new app service (Figure 5-27). Make sure to click the Save button.

Save and test on Web Chat and Messenger to your heart’s content. Congratulations! We accomplished a lot! We now have a bot running on Azure using Node.js and the Microsoft Bot Framework talking to Web Chat and Facebook Messenger. Up next, we will dive into a description of what we just accomplished.

Microsoft Azure

Microsoft Azure is Microsoft’s cloud platform. There are many types of resources ranging from infrastructure-as-a-service to platform-as-a-service and even software-as-a-service. We can provision new virtual machines as easily as creating new application services. We can create, modify, and edit resources using Azure PowerShell, Azure CLI (or the Cloud Shell), the Azure Portal (as we did in the example), or the Azure Resource Manager. The details of these are outside the scope of this book, and we refer you to the Microsoft online documentation for more information.

Bot Channels Registration Entry

When we create the bot channels registration, we are creating a global registration that can be used by all of the channel connectors to identify, authenticate, and communicate with our bot. Each connector, whether it communicates to Messenger, Slack, Web Chat, or Skype, knows about our bot, its Microsoft app ID/password, the messages endpoint, and other settings (Figure 5-28). The bot channels registration is the starting point for Bot Framework bots.

We skipped the other two types of bot resources in Azure: Web App Bot and Functions Bot. A Web App Bot is exactly what we just set up; we provision a server to run bot app. Azure Functions is one of Azure’s approaches to serverless computing. It allows us to host different code, or functions, in a cloud environment to be run on demand. We pay only for the resources we use. Azure scales the infrastructure dynamically based on load. Functions is a perfectly valid approach to bot development. For more complex scenarios, we need to be careful about architecting the function code for scale-out and multiserver deployment. For the purposes of this book, we do not utilize Functions Bots. However, we suggest you experiment with the topic as serverless computing is becoming more and more prominent.

Authentication

How do we ensure that only authorized channel connectors or applications can communicate with our bot? That’s where the Microsoft app ID and app password come in. When a connector sends a message to our bot, it will include a token in the HTTP authorization header. Our bot must validate this token. When our bot sends outgoing messages to the connector, our bot must retrieve a valid token from Azure or the connector will reject the message.

The Bot Builder SDK provides all the code so that this process is transparent to the developer. The Bot Framework documentation describes the steps in both flows in detail: https://docs.microsoft.com/en-us/bot-framework/rest-api/bot-framework-rest-connector-authentication .

Connectivity and Ngrok

Although ngrok is not part of the Bot Framework, it is an indispensable part of our toolset. Ngrok is a reverse proxy that tunnels all requests through an externally accessible subdomain on ngrok.io to a port on our computer. The free version creates a new random subdomain each time we run it; the pro version allows us to have a static subdomain. Ngrok also exposes an HTTPS endpoint, which makes local development setup a breeze.

Typically, we will not typically experience any problems with Ngrok. If our ngrok is correctly configured, any issues could be narrowed down to either an external service or our bot.

Deploying to Facebook Messenger

Every platform is different, but we learned a bit about the intricacies of bots on Facebook. First, Facebook users interact with brands and companies using Facebook Pages. User requests on a page are typically responded to by a human who has enough access to the page to view and respond via the page’s inbox. There are many enterprise live chat systems that connect to Facebook Pages and allow a team of customer service representatives to respond to users’ queries in real time. With the Bot Framework’s Facebook Messenger connector, we can now have a bot respond to those queries. We will discuss the idea of a bot handing a conversation over to an agent, known as human handover, in Chapter 13.

A bot on Facebook is a Facebook app that subscribes to messages coming into a Facebook page via web hooks. We registered the Bot Framework web hook endpoint that is called by Facebook when a message comes into our Facebook page. The bot channels registration page also provided the verify token that Facebook uses to make sure it is connecting to the right web hook. Azure’s Bot Connectors need to know the Facebook app ID and app secret to verify the signature of each incoming message. We need the page access token to send a message back to a user in a chat with a page. We can find more details about Facebook’s SendAPI and Messenger Webhooks in Facebook’s documentation pages: https://developers.facebook.com/docs/messenger-platform/reference/send-api/ and https://developers.facebook.com/docs/messenger-platform/webhook/ .

Once all these things are in place, messages easily flow between Facebook and our bot. Although Facebook has some unique concepts like the page access tokens and specific names for webhook types, the overall idea behind what we did is similar to other channels. Generally, we will be creating an app on the platform and establishing a tie between that app and the Bot Framework endpoints. It is the Bot Framework’s role to forward the messages to us.

Deploying to Azure

There are many approaches to deploying code to Azure. Kudu, the tool we used, allows us to deploy via a REST API. Kudu can also be configured to deploy from a git repo or other locations. There are also other tools that make deployment easier. If we were to write a bot using Microsoft’s Visual Studio or Visual Studio Code, there are extensions that allow us to easily deploy our code into Azure. Again, this is a topic beyond the scope of this book. For our purposes of running a Node.js bot on a Linux app service, using the ZipDeploy REST API is sufficient.

Because we can develop our bot locally by use of the emulator and test a local bot on various channels by running ngrok, we do not deploy to Azure anymore throughout the rest of this book. If necessary, take down the web app instance so the subscription is not charged. Make sure to delete the app service plan; simply stopping the web app will not work.

Sessions and Messages

Session is an object that represents the current conversation and the operations that can be invoked on it. At the most basic level, we can use the Session object to send messages.

Messages can include images, videos, files, and custom attachment types. Figure 5-29 shows the resulting message.

session => {

    session.send({

        text: 'hello',

        attachments: [{

            contentType: 'image/png',

            contentUrl: 'https://upload.wikimedia.org/wikipedia/commons/b/ba/New_York-Style_Pizza.png',

            name: 'image'

        }]

    });

}

We also can send a hero card. Hero cards are stand-alone containers that include an image, title, subtitle, and text plus an optional list of buttons. Figure 5-30 shows the resulting exchange.

let msg = new builder.Message(session);

msg.text = 'Pizzas!';

msg.attachmentLayout(builder.AttachmentLayout.carousel);

msg.attachments([

    new builder.HeroCard(session)

        .title('New York Style Pizza')

        .subtitle('the best')

        .text("Really, the best pizza in the world.")

        .images([builder.CardImage.create(session, 'https://upload.wikimedia.org/wikipedia/commons/b/ba/New_York-Style_Pizza.png')])

        .buttons([

            builder.CardAction.imBack(session, "I love New York Style Pizza!", "LOVE THIS")

        ]),

    new builder.HeroCard(session)

        .title('Chicago Style Pizza')

        .subtitle('not bad')

        .text("some people don't believe this is pizza.")

        .images([builder.CardImage.create(session, 'https://upload.wikimedia.org/wikipedia/commons/3/33/Ginoseastdeepdish.jpg')])

        .buttons([

            builder.CardAction.imBack(session, "I love Chicago Style Pizza!", "LOVE THIS")

        ]),

]);

session.send(msg);

Another interesting point is the attachment layout. By default, attachments are sent in a vertical list. We chose to use the carousel, a scrollable horizontal list, to provide a better experience for the user.

We can also use the Session object to send speech consent in channels that support both written and spoken responses. We can either build a message object like we did in the carousel hero card sample or use a convenience method on the session. The input hint in the following code snippet tells the user interface whether the bot is expecting a response, accepting input, or not accepting input at all. For developers who have a background in voice assistant skill development, like for Amazon’s Alexa, this should be a familiar concept.

Session is also the object that helps us access relevant user conversation data. For example, we can store the last message the user sent to the bot inside the session’s privateConversationData and utilize it later in the conversation as shown in the following sample (Figure 5-31):

session => {

    var lastMsg = session.privateConversationData.last;

    session.privateConversationData.last = session.message.text;

    if(lastMsg) {

        session.send(lastMsg);

    } else {

        session.send('i am memorizing what you are saying');

    }

}

By default, these objects are all stored in memory, but we can easily provide an alternate storage service implementation. We will see an example in Chapter 6.

Waterfalls and Prompts

A waterfall is a sequence of functions that process incoming messages on a bot. The Universal Bot constructor takes an array of functions as a parameter. This is the waterfall. The Bot Builder SDK calls each function in succession, passing the result of the previous step into the current step. The most common use of this approach is to query the user for more information using a prompt. In the following code, we use a text prompt, but the Bot Builder SDK supports inputs such as numbers, dates, or multiple choice (Figure 5-32).

const bot = new builder.UniversalBot(connector, [

    session => {

        session.send('echo 1: ' + session.message.text);

        builder.Prompts.text(session, 'enter for another echo!');

    },

    (session, results) => {

        session.send('echo 2: ' + results.response);

    }

]);

We can also advance the waterfall manually, using the next function, in which case the bot would not wait for additional input (Figure 5-33). This is useful in cases where the first step may conditionally ask for additional input. We will use this in our calendar bot code.

const bot = new builder.UniversalBot(connector, [

    (session, args, next) => {

        session.send('echo 1: ' + session.message.text);

        next({response: 'again!'});

    },

    (session, results, next) => {

        session.send('echo 2: ' + results.response);

    }

]);

The following is an even more complex data-gathering waterfall:

In this sample, we use a couple more types of prompts: Choice and Time. The Choice prompt asks the user to select an option. The prompt can render the choice using inline text (relevant in SMS scenarios for example) or buttons. The Time prompt uses the chronos Node.js library to parse a string representation of a datetime into a datetime object. An input like “tomorrow at 5pm” can resolve to a value that a computer can use.

Note that we use logic to skip certain waterfall steps. Specifically, if we are in the delete appointment branch, we do not need the event location. As such, we do not even ask for it. We take advantage of the privateConversationData object to the store action object, which represents the operation we will want to invoke against an API. Lastly, we use the session.endConversation method to finalize the conversation. This method will clear the user’s state so that the next time the user interacts with the bot, it is as if the bot is seeing a new user.

Figure 5-34 shows the resulting conversation.

Dialogs

Let’s bring this full circle with conversational design. In Chapter 4, we discussed how we can model a conversation using a graph of nodes we called dialogs. So far in this chapter, we have learned about waterfalls and how we can model a conversation in code.

We have also learned how we can utilize prompts to gather data from the user. Recall that prompts are simple mechanisms to collect data from users.

Prompts are interesting. We call a function (builder. Prompts.text), yielding the conversation to the prompt. Once a valid response is sent by the user, the next step in our waterfall can access the prompt’s result. Figure 5-35 shows the overall process. From our waterfall’s perspective, we don’t really know what the Prompts.choice call is doing, nor do we care. It is listening for user input, doing some validation, reprompting on bad input, and returning only a valid result, unless the user cancels. All that logic is hidden from us.

This interaction is the same model as a programming function call. The way a function call is typically implemented is using a stack. Examine Figure 5-36 and the following code:

When the function f is called, the function’s arguments are pushed on the top of the stack. The function’s code then processes the stack. In this example, the function adds the parameters. At the end, the only value left at the top of the stack is the function’s return value. The calling function can then do whatever it wants with the return value.

This is the way prompts work in a conversation. The generic concept in the Bot Builder SDK is a dialog. A prompt is a type of dialog. A dialog is nothing more than an encapsulation of conversation logic and is analogous to a function call. A dialog is initialized with some parameters. It receives input from the user, executing its own code or calling into other dialogs along the way, and can send responses back to the user. Once the dialog’s purpose is accomplished, it returns a value to the calling dialog. In short, a calling dialog pushes a child dialog to the top of the stack. When the child dialog is done, it pops itself from the stack.

Let’s go back to our Choice prompt example. In the dialog stack model, the Root dialog places the Prompt.Choice dialog on the top of the stack. After the dialog finishes executing, the resulting user input object is passed back down to the Root dialog. The Root dialog then does whatever it needs to do with the resulting object. The behavior over time is captured in Figure 5-37.

We could take this concept even further. We could imagine a flow in our calendar bot in which adding a new calendar entry invokes a new dialog. Let’s call it AddCalendarEntry. It then invokes a Prompt.Time dialog to gather the date and time of the event, and it invokes a Prompt.Text dialog to gather the event’s subject. The AddCalendarEntry packages the collected data and creates a new calendar entry by calling some calendar API. Control is then returned to the Root dialog. We illustrate this in Figure 5-32. We could even have AddCalendarEntry call another dialog that encapsulates the logic to call the API if there was enough complexity in that process and we wanted to reuse the logic from other dialogs (Figure 5-38).

Waterfalls and dialogs are the workhorses that translate a conversation design into actual working code. There are, of course, more details around them, and we’ll get into those during the next chapters, but this is the magic behind the Bot Builder SDK. Its key value is an engine that can drive a conversation using the dialog abstractions. At each point during the conversation, the dialog stack and the supporting user and conversation data are stored. This means that depending on the conversation’s storage implementation, the user may stop talking to the bot for days, come back, and the bot can pick up from where the user left off.

How do we apply some of these concepts? Revisiting the add and remove appointment waterfall sample, we can create a bot that, based on a Choice prompt, starts one of two dialogs: one to add a calendar entry or another to remove it. The dialogs have all the necessary logic to figure out which appointment to add or remove, resolve conflicts, prompt for user confirmation, and so forth.

We start a new dialog by calling the session.beginDialog method and pass in the dialog name. We may also pass an optional argument object, which would be accessible via the args parameter in the called dialog. We use the session.dialogData object to store dialog state. We’ve run into userData, privateConversationData, and conversationData before. Those are scoped to the entire conversation. DialogData, however, is scoped only to the lifetime of the current dialog instance. To end a dialog, we call session.endDialog. This returns control to the next step in the root waterfall. There is a method called session.endDialogWithResult that allows us to pass data back to the calling dialog.

The conversation in Messenger ends up looking like Figure 5-39.

This code has a few shortcomings. First, if we want to cancel either adding or deleting an appointment, there’s no way to do that. Second, if we are the middle of adding an appointment and decide we want to delete an appointment, we cannot easily switch to the remove appointment dialog. We must finish the current dialog and then switch over. Third, but not essential, it would be nice to connect the bot to our LUIS model so users can interact with the bot using natural language. We’ll address the first two points next and then follow with connecting to our LUIS models to really build some intelligence into the bot.

Invoking Dialogs

Let’s continue with the following exercise. Say we want to allow the user to ask for help at any point in the conversation; this is a typical scenario. Sometimes the help will be contextual to the dialog. At other times, the help will be a global action, a bot behavior that can be accessed from anywhere within the conversation. The Bot Builder SDK allows us to insert both types of behaviors into our dialogs.

We introduce a simple help dialog.

This code defines a new dialog with a global action handler that matches the “help” input. TriggerAction defines a global action. We are saying that the help dialog will be triggered globally whenever the user’s input matches the regular expression ^help$. The ^ character denotes the start of a line, and the $ character denotes the end of a line. A problem arises, though. As we can see in Figure 5-40, it looks as if when we ask for help, our bot forgets we were in the add appointment dialog. In fact, the default behavior for global action matching is to replace the dialog on top of the stack. In other words, the add appointment dialog was removed and replaced with the help dialog.

We can override this behavior by implementing the onSelectAction callback.

This brings up an interesting question: how can we affect the dialog stack? When we are working on a dialog flow and want to transition control over to another dialog, we can use either beginDialog or replaceDialog. replaceDialog replaces the dialog on top of the stack, and beginDialog pushes a dialog to the top of the stack. The session also has a method called reset, which resets the entire dialog stack. The default behavior is to reset the stack and push the new dialog on top.

What if we wanted to include contextual help? Let’s create a new dialog to handle help for the add calendar entry dialog. We can use the beginDialogAction method on a dialog to define triggers that start new dialogs on top of the AddCalendarEntry dialog.

When we run this, we get the desired effect, as shown in Figure 5-41.

We will dive deeper into actions and their behavior in the following chapter.

Recognizers

Recall we defined that the help dialog will be triggered via a regular expression. How does the Bot Builder SDK implement this? This is where recognizers come in. A recognizer is a piece of code that accepts incoming messages and determines what the user’s intent was. A recognizer returns an intent name and a score. The intent and score can come from an NLU service like LUIS, but they do not have to.

By default, as seen in the previous examples, the only recognizer in our bot is a regular expression or plain-text matcher. It takes in a regular expression or a hard-coded string and matches it to the incoming message’s text. We could utilize an explicit version of this recognizer by adding a RegExpRecognizer to our bot’s list of recognizers. The following implementation states that if the user’s input matches the provided regular expression, an intent called HelpIntent is resolved with a score of 1.0. Otherwise, the score is 0.0.

Another thing that the recognizer model allows us to do is to create a custom recognizer that executes any code we want and resolves an intent with a score. Here’s an example:

Now this is quite a simple example, but our minds should be racing with the possibilities. For example, if the user’s input is nontext media such as an image or video, we can write a custom recognizer that validates the media and responds accordingly.

The Bot Builder SDK allows us to register multiple recognizers to our bot. Whenever a message comes into the bot, each recognizer is invoked, and the recognizer with the highest score is deemed the winner. If two or more recognizers result in the same score, the recognizer that was registered first wins.

Lastly, this same mechanism can be used to connect our bot to LUIS, and in fact the Bot Builder SDK includes a recognizer for this very case. To do this, we take the endpoint URL for our LUIS application (perhaps the one we created in Chapter 3) and use it as a parameter to the LuisRecognizer.

Once we set this up, we add a triggerAction call for each intent we would like to handle globally, as we did with the help dialog. The strings passed as the “matches” member must correspond to our LUIS intent names.

At this point, our bot conversation can navigate between the dialogs by using LUIS intents (Figure 5-42). LUIS’s intent and entity objects are passed into the dialogs.