node

In four lines of code, here is why you should stop using JavaScript, and write every project in TypeScript:

1
2
3
4
5
6
7

interface Message {
    text: string;
}

let message: Message = {
    text: 'Hello, world!!'
};

Really, that’s it. There’s so much power in just those four lines of code.

TypeScript defined

Before we breakdown the above code, it’s probably worthwhile to talk a little bit about TypeScript and what it is. More importantly, let’s talk about what TypeScript isn’t.

TypeScript is not a replacement for JavaScript or ECMAScript (from here forward I’ll simply call this JavaScript), or another attempt to redefine either of those. Instead, TypeScript is a syntactical superset of JavaScript, and is transcompiled down to the version of JavaScript you desire. You use TypeScript to write JavaScript. Because TypeScript is a superset of JavaScript, you already know a large percentage of the syntax for TypeScript, as TypeScript builds upon JavaScript’s syntax.

Why use TypeScript

There are several reasons to use TypeScript. One of the biggest is to handle all the various versions of JavaScript, and features that are supported. For example, I love using async/await when writing code. However, that’s only supported in more recent versions of JavaScript, which doesn’t share wide adoption quite yet. The transcompiler for TypeScript handles down-leveling the code as appropriate, so I can write what I want, taking advantage of new features and syntax, knowing that TypeScript will manage the versioning for me behind the scenes.

More importantly to me on a day-to-day basis, though, is type checking and the ability to describe data structures. Keep in mind, of course, that TypeScript transcompiles to JavaScript, so the type checking doesn’t actually wind up in the JavaScript, and does not impact the performance. But it does make creating code much easier.

Breaking down the four lines

Creating interfaces

Let’s start with the first line:

1

interface Message { ... }

Interfaces in any programming language of course allow you to describe the structure of data or some other object. It’s a contract, and when something is declared as a type of that interface you as the developer knows what’s there. In addition, because the IDE, such as Visual Studio Code, you can get autocomplete and IntelliSense when using variables declared as the interface type.

Many JavaScript solutions call various REST services, each with their own structure for JSON documents. The ability to declare an interface can speed development by reminding you what properties are required, and ensuring they’ve all been provided.

Declaring types

Let’s bring back the entire code block:

1
2
3
4
5
6
7

interface Message {
    text: string;
}

let message: Message = {
    text: 'Hello, world!!'
};

You’ll notice the declarations of text: string and message: Message. By using variableName: type, we’ve told TypeScript what type we want the variable to be. This brings a couple of great advantages. The first is pretty obvious - that your IDE will let you know when you’re using it wrong. The second is by indicating the data type, your IDE can offer autocomplete or, in the case of Visual Studio Code, IntelliSense.

Don’t underestimate how important IntelliSense is. While through use and repetition, you absolutely will start to remember various property and method names. But for those edge cases where you need to call something you don’t often reach for, being able to simply hit “dot” and scroll through the list of options (often with documentation) is much more efficient than opening the docs or searching Stack Overflow.

A bit more about types and introducing Typings

In our little application, we created our own interface, so it seems only logical that VS Code would know what to do with that. But what about other packages, such as Express, Restify, or Mongoose?

For packages that are created in TypeScript, you’re covered. But for other packages, such as those listed above, which are created in some form of JavaScript, VS Code won’t be able to automatically figure out what’s available to you, thus you won’t get IntelliSense. Enter Definitely Typed.

Definitely Typed is a community that creates package.d.ts files, which contain the list of interfaces and structures provided by a particular package. These types are installable via NPM, and are almost always solely needed as dev dependencies. To install a package’s types, simply prepend the name of the package with @types/. Note that while not every package has types created, I think you’ll be pleasantly surprised at how many have been done.

As an example, here’s how you’d install the types for Restify.

1

npm install --save-dev @types/restify

Variable declaration

1

let message: Message = { ... }

When declaring our message variable, we used the keyword let. Let helps fix some of JavaScript’s odd scoping rules. In JavaScript, variables aren’t scoped to blocks, meaning the code below works, and would print the number 42. There is absolutely no reason this should work, but yet here we are…

1
2
3
4
5

if(1 === 1) {
    var x = 42;
}
// WHY DOES THIS WORK?!?!
console.log(x);

By using let in TypeScript, the variable x in the above scenario would not be available outside of the if block.

The transcompiled JavaScript

In order to run our code, we will need to transcompile it into JavaScript. This is done by using tsc, which is available after installing TypeScript (which can be done via NPM).

1

tsc app.ts

The final JavaScript will look as follows:

1
2
3

var message = {
    text: 'Hello, world!!'
};

All of the syntactical candy provided by TypeScript, such as the type declarations and interfaces, has been omitted. At the end of the day, when you’re using TypeScript, you’re writing JavaScript. But you’re doing so at a higher level, with a better language.

Bring it back around again

There are numerous reasons to use TypeScript. Not having to worry about versioning issues, being able to take advantage of the latest technologies, and many other features, make creating projects in TypeScript rather compelling. For me, the chief is the ability to have typed objects. It makes me a more efficient developer, and helps me spot bugs that much faster.

If you’re looking to get started, TypeScriptLang.org offers quite a bit in the way of documentation, and is well structured. It may take a little bit of getting used to the structure of TypeScript, like learning any new language, but in the long run you will find it’s a much better way of creating JavaScript.

Creating bots in the real world brings additional challenges with versioning and user behavior. Obviously, when you update your bot, you want to make sure you seemlessly migrate users over to the new bot, often allowing them to complete the conversation they’re currently having before showing them the new bot. Also, because Bot Framework does not time out users, you can also run into a situation where a user has left for a sizeable amount of time, and either state has changed or you simply want to offer the user the chance to start over.

Let’s break this down by first talking about how things work behind the scenes inside of Bot Framework, introduce middleware, and then put forth a couple of patterns you can implement to handle these situations.

Well, one quick note before we get started - this is a 300 level concept, so I’m making the assumption you’re already familiar with Bot Framework, and have created a few bots. If not, you can check out the Bot Framework MVA.

Bot Framework behind the scenes

A bot is, at the end of the day, simply a web service. Web services, of course, are stateless, meaning that after the message is sent from the user, and a reply returned, the connection is broken down, and all data is lost. When working with a bot, however, this poses a problem, because an operation will typically take place across multiple round trips from the user to the bot.

To handle this, Bot Framework “dehydrates” or serializes the current state of the bot for each user. When the user returns by sending a new message, the user state is “rehydrated” or reloaded, the bot determines where the user left off, and the next function is then run. You can see this happening behind the scenes when tracking your bot in the console, seeing the waterfall in action, and which step the bot is about to call. In a simple “Hello, world” bot, the user would send hello, the bot sends the prompt for the name, the user replies, and then the bot runs the next function - in this case, sending the hello message.

1
2
3
4
5
6
7
8
9
10
11

const bot = new builder.UniversalBot(
    connector,
    [
        (session) => {
            builder.Prompts.text(session, 'What is your name?');
        },
        (session, results) => {
            session.endConversation(`Hello, ${results.response}.`);
        }
    ]
);

No timeout

Because we’re dealing with humans, who may take some time to respond back to the bot, there is no timeout for a session^[1]. If a user leaves for a couple of hours, and then replies to the What is your name? question, the bot simply picks up where it left off, as if the user replied instantly.

The first challenge here is state may have modified - the price for an item may have changed, a reservation time may no longer be available, or the operation may simply no longer be valid. In addition, this might confuse the user in general - if you didn’t talk to a bot for a couple of days, and potentially had the chat history on your client cleared, you might not expect the bot to pick up, or even know, where you left off.

The second challenge is when updating the bot. If you modified a dialog, the bot might not be able to pick up where it left off seamlessly. You may have removed a step from a waterfall, meaning the bot will error, now knowing what to run. Or, if a step changed, it may ask the user a question that simply doesn’t make sense for the current flow.

Addressing these issues doesn’isn’t necessarily difficult, but it does take a little bit of forethought and planning. With a little bit of middleware, you can transition as needed.

Middleware

Middleware allows you to intercept messages before they’re passed into the dialog flow, where the bot processes them as normal. This is useful for logging, rerouting messages (say for bot to human handoff), or, in our case, managing how a user is directed through the dialogs offered by the bot.

To implement middleware, you call use, passing in an object that implements at least one of three methods:

• receive, which fires when a event is received by the bot
• send, which fires when an event is sent by the bot
• botbuilder, which executes after receive and the message is bound to a session

The last part of botbuilder is key in our case, because it’s going to allow us to open up where the user currently sits in the flow of the dialog(s), and determine the next step.

Strategies

Let’s walk through a few strategies for managing timeouts and updating your bot. I’m not going to walk through every possibility, but rather show off a few representative solutions that will hopefully illustrate how to approach the problem, and provide enough information for you to implement what’s needed.

Adding a timeout

As mentioned above, a bot doesn’t timeout. As a result, if it’s been even a few days since the user last replied, the bot is going to attempt to pick up where it left off. This can either confuse the user, or operate on bad information, neither of which is a good thing.

Reset the conversation

The first potential solution, and the easiest to implement, is to simply reset the conversation. We’ll do this by adding a lastAccess property to userData. We’ll then query this to see how long it’s been since the user last talked to the bot, and, if necessary, reset the conversation.

We determine if the user is currently in a conversation by taking a look at the dialogStack and determining if there is at least one dialog there. Our threshold is 10 seconds, which is obviously artificially small, but I want you to be able to easily test the implementation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

bot.use(
    {
        botbuilder: (session, next) => {
            // grab the current time
            const currentTime = Date.now();
            // see how long it's been (in milliseconds) since the user last 
            // accessed the bot
            const lastAccessGap = currentTime - session.userData.lastAccess;
            // update the last access
            session.userData.lastAccess = currentTime;
            // see if there is a dialog and it's been greater than 10 seconds
            // since the user last talked to the bot
            if(session.dialogStack().length > 0 && lastAccessGap > 10000) {
                // a couple of friendly messages
                session.send(`Hey there! It looks like it's been a while since you were last here.`);
                session.send(`Let's start over to make sure we're both on the same page.`);
                // reset the conversation, sending the user to the root dialog
                session.reset('/');
            } else {
                // allow the flow to continue as normal
                next();
            }
        },
    }
)

Ask the user what they want to do

The next possibility, and slightly more advanced, is to ask the user what they want to do. We’ll use the same timestamp technique as above, but this time we’ll route the user to a confirmation dialog. If they say yes, we’ll end the dialog, which will reprompt the user. If they say no, we’ll reset the dialog like before. Again, the threshold is artificially small for testing purposes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

bot.use(
    {
        botbuilder: (session, next) => {
            // grab the current time
            const currentTime = Date.now();
            // see how long it's been (in milliseconds) since the user last 
            // accessed the bot
            const lastAccessGap = currentTime - session.userData.lastAccess;
            // update the last access
            session.userData.lastAccess = currentTime;
            // see if there is a dialog and it's been greater than 10 seconds
            // since the user last talked to the bot
            if(session.dialogStack().length > 0 && lastAccessGap > 10000) {
                // begin the confirmation dialog
                session.beginDialog('confirm-continue');
            } else {
                // allow the user to continue as normal
                next();
            }
        },
    }
)

bot.dialog('confirm-continue', [
    (session, args) => {
        // prompt the user
        builder.Prompts.confirm(session, `It looks like you've been gone for a little while. Do you want to continue where you left off?`);
    },
    (session, results) => {
        if(results.response) {
            // redirect back to the original dialog
            // the last active prompt will be re-run
            session.endDialog(`Sounds good. Here's the last question I asked you:`);
        } else {
            // reset the conversation
            session.send(`Sounds good. Let's start over.`);
            session.reset('/');
        }
    }
]);

Some thoughts on timeouts

It’s really up to you to decide how to best manage timeouts and what works best for your bot. You might decide to time the user out after twenty minutes, or maybe a couple of hours. You might automatially reset, especially in simpler two or three turn dialogs, or to prompt the user for more complex bots. You might even go a couple steps further, detecting which dialog the user is in, and make the decision based on that.

Managing versions

Versioning a live bot is a little trickier. You want to get users onto the new bot as quickly as possible, but you probably don’t want to interrupt the current flow of a user already in the middle of a dialog. If nothing else, when you version your bot, you need to handle the fact that a user in the middle of a dialog might be returning to a dialog step that doesn’t exist, or a dialog that’s changed profoundly, meaning the message the user sent might not make sense in the flow you deployed.

Reloading an older version

If you do want to transition the user, you will need to pay a little bit of attention to how you update your bot. In theory, you could do this on a dialog by dialog basis, but the code becomes trickier as you need to figure out where the user is, and swap out the dialog. I find it much easier to simply swap out the entire bot. To help manage this, I’ll put the bot, and its associated dialogs, into a folder. When it comes time to update it, I’ll copy the entire folder structure, update the copy, and then update app.js to call the updated (new) bot.

When you need to send a user to the old bot, you simply update the library property of the session, which sets the bot that will run for the incoming message. In the code snippet below, I have both an updated and original bot in the same file for simplicity’s sake. I hope you can see from here how you would implement this with multiple folders.

In the sample below, I’m going to transition the user once their current conversation completes. You could, if you so desire, update this code to always reset the conversation, with a message of course, which would cause the user to be rerouted to the new bot. Also, the code could be streamlined a little bit, but breaking it apart like I’ve done makes it (I think) a little easier to explain with comments.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

const connector = new builder.ChatConnector();
const bot = new builder.UniversalBot(
    // this is the updated bot
    connector,
    [
        (session) => {
            builder.Prompts.text(session, 'What is your name?');
        },
        (session, results) => {
            session.endConversation(`Hello, ${results.response}, from the updated bot`);
        }
    ]
);
// set a version number using duck typing
bot.version = 2;

const getOriginalBot = (connector) =>{
    // this will return the original bot
    const originalBot = new builder.UniversalBot(
        connector,
        [
            (session) => {
                builder.Prompts.text(session, 'What is your name?');
            },
            (session, results) => {
                session.endConversation(`Hello, ${results.response}, from the original bot`);
            }
        ]
    );
    // set a version number by using duck typing
    originalBot.version = 1;
    return originalBot;
};

bot.use(
    {
        botbuilder: (session, next) => {
            if(!session.userData.version) {
                // new user. set the version
                session.userData.version = bot.version;
            }

            // check if user is in conversation and
            // if the user is on the prior version
            if(session.dialogStack().length > 0 && session.userData.version < bot.version) {
                // load the original bot
                session.library = getOriginalBot(connector);
                // pass control to the original bot
                // the correc step and dialog will be executed
                next();
            } else {
                // update the version in userData
                session.userData.version = bot.version;
                // pass control to the new bot
                next();
            }
        },
    }
);

If you wanted to test this, start by making the new bot version 1 and sending a message to get yourself into the dialog. Then update the version to 2, rerun the application while not restarting the conversation in Bot Emulator, and sending the second message. You should see the original bot message.

Some thoughts on versioning

Versioning is tricky, especially if you’re in a CI/CD environment where you expect to make multiple updates to the bot. Bot Framework (unfortunately?) doesn’t automatically handle transitions for you, so you will need to decide what pattern will work best for you. This is also important when developing and testing your bot in a channel such as Skype or Slack, where how to reset the state from the client isn’t overly obvious. In dev you could certainly skip the transition, but in production you’ll likely want to implement a mechanism for doing so.

Final thoughts

Once you introduce your bot to the “real world”, things change. Management of the experience becomes much more important, and dealing with timeouts and versioning allows you to ensure a good experience for your users. This is something you should thing about early on, as it’s easier to introduce this at the beginning than to an existing, complex bot.

There are numerous ways you could handle this. Hopefully I’ve provided enough of a foundation for you to create an implementation that’s right for your bot.

^[1] I am referring to session in general, not to the session object in Bot Framework.

If I’ve said anything about bots, it’s that they’re apps. They’re just apps with a conversational interface. This style of interface can be extremely powerful, as it allows the user to better express themselves, or “skip to the end” if they already know what it is they’re trying to accomplish. The problem, though, is without a bit of forethought to the design of the bot it’s easy to wind up back in this scenario, where the user isn’t sure what to do next:

If you’re well versed in the set of commands you can quickly perform any operation you desire. But there is no guidance provided by the system. Just as they’re no guidance provided here:

Buttons are a good thing

We need to guide the user.

Buttons exist for a reason. They succinctly show the user what options are available, and can guide the user towards what they’re looking for. In addition, they help reduce the amount of typing required, which is especially important when talking about someone accessing a bot on a mobile device with a tiny keyboard.

Providing choices

The most obvious place where buttons shine is when providing a list of choices for a user to select from. This might be a shipping method, a category for filtering, or, really, any other set of options. To support a list of choices, BotBuilder provides a choice prompt. The choice prompt, as you might expect, provides the user a list of options for them to choose from, and then provides access to that in the next step of the dialog.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// sample waterfall dialog for a choice
(session, args, next) => {
    builder.Prompts.choice(
        session, 
        `What color do you want?`,
        ['Red', 'Green', 'Blue'],
        { 
            listStyle: builder.ListStyle.button,
            retryPrompt: `Please choose from the list of options`,
            maxRetries: 2,
        }
    );
},
(session, results, next) => {
    if(results.response && results.response.entity)
        session.endConversation(`You chose ${results.response.entity}`);
    else
        session.endConversation(`Sorry, I didn't understand your choice.`);
}

The choice prompt limits the user’s response to just the list of options you provide. You can limit the number of times the bot will ask the user for a response before moving onto the next step in the waterfall.

While choice is certainly nice for providing a simple list of options, it does force the user into choosing one of those options. As a result, it’s not as easy to use choice when trying to guide the user with a list of options while also allowing them to type free-form, which is what you’ll want to do when the user first starts a session with the bot. In addition, you don’t get control over the interface provided.

Customizing the list of prompts

If you wish to customize the list of prompts, you need to set up a card. This can be an Adaptive Card, or one of the built-in cards such as thumbnail or hero. By using a card you can provide a bit more guidance to the channel on how you’d like your list of options to provide.

To allow the user to select from a list of options, you will add buttons to the card. Buttons can be set to either imBack, meaning the client will send the message back to the bot just as if the user typed it, or postBack, meaning the client will send the message to the bot without displaying it inside the client. Generally speaking, imBack is a better choice, as it makes it clear to the user something has happened, and can give the user a clue as to what to type in the future, should they so decide.

WARNING!!!

The code below is the wrong way to use buttons to provide a list of options, but it’s the most common mistake I see people make when using buttons with Bot Framework.

In the code snippet below, I want you to notice the addition of the buttons using builder.CardAction.imBack, and the call to session.send (where the mistake is).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

(session, args, next) => {
    const card = new builder.ThumbnailCard(session)
        .text('Please choose from the list of colors')
        .title('Colors')
        .buttons([
            new builder.CardAction.imBack(session, 'Red', 'Red'),
            new builder.CardAction.imBack(session, 'Blue', 'Blue'),
            new builder.CardAction.imBack(session, 'Green', 'Green'),
        ]);
    const message = new builder.Message(session)
        .addAttachment(card);
    session.send(message);
},
(session, results, next) => {
    if(results.response && results.response.entity)
        session.endConversation(`You chose ${results.response.entity}`);
    else
        session.endConversation(`Sorry, I didn't understand your choice.`);
}

If you added this dialog to a bot and ran it, you’d see the following output:

The mistake, as I mentioned above, is at session.send. When using session.send in the middle of a waterfall dialog, the bot is left in a state where it’s not expecting the user to respond. As a result, when the user does respond by clicking on Blue, the bot simply returns back to the current step in the waterfall, and not to the next one. You can click the buttons as long as you’d like, and you’ll see them continuing to pop up.

The correct way to do it

In order for the bot to be in a state that expects user input and continues to the next step of a waterfall, you must use a prompt. When using buttons inside of a card, you can choose either a text or choice prompt. When using a text prompt, the bot can accept any input in addition to the buttons you provided. This can allow the user to be more free-form as needed. choice prompts, however, will limit the user to the list of choices, just as if you created it the traditional way mentioned earlier.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// Using a choice prompt with custom buttons
// For simplicity, I removed the retry prompts, but you can continue to use them

// If you wanted to use a text prompt, you'd simply use:
// builder.Prompts.text(session, message);
(session, args, next) => {
    const choices = ['Red', 'Blue', 'Green']
    const card = new builder.ThumbnailCard(session)
        .text('Please choose from the list of colors')
        .title('Colors')
        .buttons(choices.map(choice => new builder.CardAction.imBack(session, choice, choice)));
    const message = new builder.Message(session)
        .addAttachment(card);
    builder.Prompts.choice(session, message, choices);
},
(session, results, next) => {
    if(results.response && results.response.entity)
        session.endConversation(`You chose ${results.response.entity}`);
    else
        session.endConversation(`Sorry, I didn't understand your choice.`);
}

Providing a menu

As I mentioned at the beginning of this post^[1], one of the keys to a good user experience in a bot is to provide guidance to the user, otherwise you’re just giving them a C-prompt.Again, the easiest way to do this is via buttons.

We’ve already seen that imBack behaves just as if the user typed the value manually. We can take advantage of this fact by providing the list of options, and ensuring the values match the intents provided in the bot.

You’ll notice in the code sample below I created a bot with two simple dialogs, and the default dialog sends down the buttons inside of a card. By calling endConversation, the bot sends down the card and closes off the conversation. When the user clicks on a button it’s just as if the user typed in the value, and the bot will then route the request to the appropriate dialog. The user is free at this point to either click one of the provided buttons, or type in whatever command they desire.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

const bot = new builder.UniversalBot(
    new builder.ChatConnector({
        appId: process.env.MICROSOFT_APP_ID,
        appPassword: process.env.MICROSOFT_APP_PASSWORD
    }), 
    (session) => {
        const card = new builder.ThumbnailCard(session)
            .title('Sample bot')
            .text(`Hi there! I'm the sample bot. 
                    You can choose one of the options below
                    or type in a command of your own
                    (assuming I support it)`)
            .buttons([
                builder.CardAction.imBack(session, 'Hello', 'Hello'),
                builder.CardAction.imBack(session, 'Greetings', 'Greetings'),
            ]);
        const message = new builder.Message(session)
            .addAttachment(card);
        session.endConversation(message);
    }
);

bot.dialog('Hello', (session) => {
    session.endConversation(`The Hello Dialog`)
}).triggerAction( { matches: /Hello/ } );

bot.dialog('Greetings', (session) => {
    session.endConversation(`The Greetings Dialog`)
}).triggerAction( { matches: /Greetings/ } );

The updated bot now performs as displayed below. In the dialog I started by typing test to trigger the bot. I then clicked on Hello, which displayed the Hello Dialog message. I completed the exchange by typing Hello, which, as you see, sent the same Hello Dialog message.

Conclusion

I’ve said it before, and I’ll certainly say it again - buttons exist for a reason. Buttons can help you provide a good UI/UX for users in any type of application, and bots are no exception. You can use buttons to both limit the amount of typing required, and to help guide the user’s experience with the bot.

^[1] This exceedingly long post?

Note: this blog assumes you have used Azure to create services in the past

The problem

One of the the most compelling scenarios for a bot is to add it to Facebook. A Facebook page is rather static. Finding information about a business on a Facebook page can be a bit of a challenge. And while users can comment, or send a message, the only replies they’ll ever receive is from a human, meaning the owner of the small business needs to monitor Facebook.

Of course, if it’s a small business that the page is representing, there’s a good chance the business doesn’t have the resources to create a bot on their own. Or, even if the business is of a size where they have access to developers, the developers aren’t the domain experts - that’s the salespeople, managers, or other coworkers.

To make a long story short, developers are often required to create the bot, and build the knowledge base the bot will be using to provide answers. This is not an ideal situation.

The solution

Enter QnA Maker.

QnA Maker is a service that can look at an existing, structured, FAQ document, and extract a set of question and answers into a knowledge base. The knowledge base is editable through an interface designed for information workers, and is exposed via an easy to call REST endpoint for developers.

Getting started

To get started with QnA Maker, head on over to https://qnamaker.ai/. You can create a new service by clicking on New Service. From there, you’ll be able to give your service a name, and point to one or more FAQ pages on the web, or a document - Word, PDF, etc. - containing the questions and answers. After clicking create, the service will do its thing, creating a knowledge base that can be accessed via the endpoint.

Managing the knowledge base

The knowledge base is a set of questions and answers. After creating it, you can manage it much in the same way you edit a spreadsheet. You can add new pairs by clicking on Add new QnA pair. You can also edit existing pairs in the table directly. Finally, if you wish to add a new question to an existing answer, you can hover over the question on the left side, click the ellipsis, and choose Add alternate phrasing.

One important thing to note about the knowledge base, is each question and answer is an individual entity; there is no parent/child relationship between multiple questions and a single answer. As a result, if you need to provide additional ways to ask a particular question with the same answer, you will need to have multiple copies of the same answer.

Testing and further tweaking the knowledge base

Once you’re happy with the first version of your knowledge base, click Save and retrain to ensure it’s up to date. Then, click Test on the left bar, which will present you with a familiar bot interface. From this interface, you can start testing your bot by typing in questions and seeing the various answers.

You’re also able to update the knowledge base from this interface. For example, if you type a question that’s a little ambiguous, the interface will show you multiple answers on the left side. You can simply click the answer you like the most to update the knowledge base to use that answer for the question you provided.

In addition, after asking a question, and being provided an answer, you can add additional phrasings of the same question on the right side.

Some design notes

First and foremost, remember the eventual user experience for this knowledge base is via a bot. Bots should typically have personality, so don’t be afraid to modify some of the answers from their original form to make it read a bit more like a human typed it out, rather than a straight statement of facts. In addition, make sure you add multiple questions related to hello, hi, help, etc., to introduce your bot and help guide your user to understand the types of questions your knowledge base can answer. Finally, remember that while a single form of a question works well on a FAQ page, users can type the same question in multiple forms. It’s not a bad idea to ask other people to test your knowledge base to ensure you’re able to answer the same question in multiple forms.

And, once you’re ready to make the service available to a bot, click Save and retrain, and then Publish.

Using the knowledge base in a bot

QnA Maker exposes your knowledge base as a simple REST endpoint. You can access it via POST, passing a JSON object with a single property of question. The reply will be a JSON object with two properties - answer, which contains the answer, and score, which is a 0-100 integer of how sure the service is it has the right answer. In fact, you can use this endpoint in non-bot services as well.

Of course, the goal of this blog post is to show how you can deploy this without writing code. To achieve that goal, we’re going to use Azure Bot Services, which is built on top of Azure Functions. Azure Bot Services contains a set of prebuilt templates, including one for QnA Maker.

In the Azure Portal, click New, and then search for Bot Service (preview). The Azure Portal will walk you through creating the website and resource group. After it’s created, and you open the service, you will be prompted to create a bot in Bot Framework. This requires both an ID and a key, which you’ll create by clicking on Create Microsoft App ID and Password.

IMPORTANT: Make sure you copy the password after it’s created; it’s not displayed again! When you click on Finish and go back to Bot Framework, the ID will be copied automatically, but the key will not.

Once you’ve entered the ID and key, you can choose the language (C# or NodeJS), and then the template. The template you’ll want is Question and Answer. When you click Create bot, you’ll be prompted to select your knowledge base (or create a new one).

And you’re done!

And that’s it! Your bot is now on the Bot Framework, ready for testing, to be added to Skype, Facebook, etc. You now have a bot that can answer questions about your company, without having to write a single bit of code. In addition, you’ll be able to allow the domain experts update the knowledge base without any need for code updates - simply save and retrain, then publish, and your bot is updated.

A couple of last thoughts

While the focus has been on a no-code solution, you are absolutely free to incorporate a QnA Maker knowledge base into an existing bot, or to update the bot you just created to add your own custom code. And if you’re looking for somewhere to get started on creating bots, check out the Bots posts on this very blog, or the MVA I created with Ryan Volum.

One of the greatest advantages of the bot interface is it allows the user to type effectively whatever it is they want.

One of the greatest challenges of the bot interface is it allows the user to type effectively whatever it is they want.

We need to guide the user, and to make it easy for them to figure out what commands are available, and what information they’re able to send to the bot. There are a few ways that we can assist the user, including providing buttons and choices. But sometimes it’s just as easy as allowing the user to type help.

Adding a global commands

If you’re going to add a help command, you need to make sure the user can type it wherever they are, and trigger the block of code to inform the user what is available to them. Bot Framework allows you to do this by creating a DialogAction. But before we get into creating a DialogAction, let’s discuss the concept of dialogs and conversations in a bot.

Dialogs and conversations

Bots contain a hierarchy of conversations and dialogs, which you get to define.

A dialog is a collection of messages back and forth between the user and the bot to collect information and perform an action on their behalf. A dialog might be the appropriate messages to obtain the type of service the user is interested in, determine which location the user is referring to when asking for store information, or the time the user wants to make a reservation for.

A conversation is a collection of dialogs. The conversation might use a dialog to walk through the steps listed above - service type, location and time - to complete the process of creating an appointment. By using dialogs, you can simplify the bot’s code, and enable reuse.

We will talk more in future blog posts about how to manage dialogs, but for right now this will enable us to create a DialogAction.

What is a DialogAction?

At the end of the day a DialogAction is a global way of starting a dialog. Unlike a traditional dialog, where it will be started or stopped based on a flow you define, a DialogAction is started based on the user typing in a particular keyword, regardless of where in the flow the user currently is. DialogActions are perfect for adding commands such as help, cancel or representative.

Creating a DialogAction

You register a DialogAction by using the bot function beginDialogAction. beginDialogAction accepts three parameters, a name for the DialogAction, the name of the Dialog you wish to start, and a named parameter with the regular expression the bot should look for when starting the dialog.

1
2
3
4
5
6
7
8
9

bot.beginDialogAction('help', '/help', { matches: /^help/ });

bot.dialog('/help', [
    (session) => {
        // whatever you need the dialog to do,
        // such as sending a list of available commands 
        session.endDialog('in help');
    }
]);

The first line registers a DialogAction named help, calling a Dialog named help. The DialogAction will be launched when the user types anything that begins with the word help.

The next line registers a dialog, named help. This dialog is just like a normal dialog. You could prompt the user at this point for additional information about what they might like, query the message property from session to determine the full text of what the user typed in order to provide more specific help.

DialogAction flow

The next question is what happens when the help Dialog (what it’s called in our case) completes. When endDialog is called, where in the flow will the user be dropped? As it turns out, they’ll pick up right where they left off.

Imagine if we had the following bot:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

const builder = require('botbuilder');

const connector = new builder.ConsoleConnector();
const bot = new builder.UniversalBot(connector);

const dialog = new builder.IntentDialog()
    .matches(/^load$/i, [
        (session) => {
            builder.Prompts.text(session, 'Please enter the name');
        },
        (session, results) => {
            session.endConversation(`You're looking for ${results.response}`);
        }
    ])
    .onDefault((session) => {
        session.endConversation(`Hi there! I'm a GitHub bot. I can load user profile information if you send the command **load**.`);
    });

bot.dialog('/', dialog);

bot.beginDialogAction('help', '/help', { matches: /^help/ });

bot.dialog('/help', [
    (session) => {
        session.endDialog('This bot allows you to load GitHub data.');
    }
]);

connector.listen();

Notice we have have an IntentDialog built with a load “command”. This kicks of a simple waterfall dialog which will prompt the user for the name of the user they wish to load, and then echos it back. If you ran the bot, and sent the commands load, followed by help, you’d see the following flow:

1
2
3
4
5
6
7
8
9

User: load
Bot: Please enter the name

User: help
Bot: This bot allows you to load GitHub data.
Bot: Please enter the name

User: GeekTrainer
Bot: You're looking for GeekTrainer

Notice that after the help dialog completes the user is again prompted to enter the name, picking right up where you left off. This simplifies the injection of the global help command, as you don’t need to code in where the user left, and then returned. The Bot Framework handles that for you.

Summary

One of the biggest issues in creating a flow with a chat bot is the fact a user can say nearly anything, or could potentially get lost and not know what messages the bot is looking to receive. A DialogAction allows you to add global commands, such as help or cancel, which can create a more elegant flow to the dialog.

What did you say?

Bots give you the ability to allow users to interact with your app through communication. As a result, figuring out what the user is trying to say, or their intent, is core to all bots you write. There are numerous ways to do this, including regular expressions and external recognizers such as LUIS.

For purposes of this blog post, we’re going to focus our attention on regular expressions. This will give us the ability to focus on design and dialogs without having to worry about training an external service. Don’t worry, though, we’ll absolutely see how to use LUIS, just not in this post.

Dialogs

In Bot Framework, a dialog is the core component to interacting with a user. A dialog is a set of back and forth messages between your bot and the user. In this back and forth you’ll figure out what the user is trying to accomplish, and collect the necessary information to complete the operation on their behalf.

Every dialog you create will have a match. The match will kick off the set of questions you’ll ask the user, and start the user down the process of fulfilling their request.

As mentioned above, there are two ways to “match” or determine the user’s intent, regular expressions or LUIS. Regular expressions are perfect for bots that respond to explicit commands such as create, stop or load. They’re also a great way to offer the user help.

Design Note

One big thing to keep in mind when designing a bot is no natural language processor is perfect. When people create their first bot, the most common mistake is to allow the user to type almost anything. The challenge is this is almost guaranteed to frustrate the user, and lead to more complex code trying to detect the user’s intent, only to misunderstand a higher percentage of statements.

Generally speaking, you want to guide the user as much as possible, and encourage them to issue terse commands. Not only will this make it easier for your bot to understand what the user is trying to tell it, it actually makes it easier for the user.

Think about a mobile phone, which is one of the most common bot clients. Typing on a small keyboard is a challenge at best, and the user isn’t going to type “I would like to find the profile GeekTrainer” or the like. By using terse commands and utterances, you’ll not only increase the percentage of statements you understand without clarification, you’ll make it easier for the user to interact with your bot. That’s a win/win.

In turn, make it easy for your user to understand what commands are available. By guiding the user through a set of questions, in an almost wizard-like pattern, you’ll increase the chances of success.

Creating dialogs

To determine the user’s intent by using regular expressions or other external recognizers, you use the IntentDialog. IntentDialog effectively has a set of events exposed via matches which allow you to execute at least one function in response to the detected event.

Let’s say you wanted to respond to the user’s command of “load”, and send a message in response. You could create a dialog by using the following code:

1
2
3
4
5

// snippet
let dialog = new builder.IntentDialog()
    .matches(/load/i, (session) => {
        session.send('Load message detected.');
    });

matches takes two parameters - a regular expression which will be used to match the message sent by the user, and the function (or array of functions) to be called should there be a match. The function, or event handler if you will, takes three parameters, session, which we saw previously, args, which contains any additional information sent to the function, and next, which can be used to call the next function should we provide more than one in an array. For the moment, the only one that’s important, and the only one we’ve used thus far, is session.

To use this with a bot, you’ll create it and add the dialog like we did previously, only adding in the dialog object rather than a function.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// text.js
// full code

const builder = require('botbuilder');

const connector = new builder.ConsoleConnector();
const bot = new builder.UniversalBot(connector);

const dialog = new builder.IntentDialog()
    .matches(/load/i, (session) => {
        session.send('Load message detected.');
    });

bot.dialog('/', dialog);

connector.listen();

If you run the code, and send the word load, you’ll notice it sends the expected message.

1
2
3

node text.js
load
// output: Load message detected

Handling default

Over time you’ll add more intents. However, as we mentioned earlier, we want to make sure we are able to give the user a bit of guidance, especially if they send a message that we don’t understand at all. Dialogs support this through onDefault. onDefault, as you might suspect, executes as the default message when no matches are found. onDefault works just like any other handler, accepting one or more functions to execute in response to the user’s intent.

1
2
3
4
5
6
7
8
9
10
11

// existing code

const dialog = new builder.IntentDialog()
    .matches(/load/i, (session) => {
        session.send('Load message detected.');
    })
    .onDefault((session) => {
        session.endConversation(`Hi there! I'm a GitHub bot. I can load user profile information if you send the command **load**.`);
    });

// existing code

You’ll notice you don’t give onDefault a name because it’s of course also a name. You’ll also notice we used session.endConversation to send the message. endConversation ends the conversation, and the next message starts from the very top. In the case of our help message this is the perfect behavior. We’ve given the user the list of everything they can do. The next message they send, in theory anyway, will be one of those commands, and we’ll want to process it. The easiest way to handle it is to use the existing infrastructure we just created.

If you test the bot you just created, you should see the following:

1
2
3

node text.js
Hello
// output: Hi there! I'm a GitHub bot. I can load user profile information if you send the command load.

Summary

When creating a bot, the first thing you’ll do is determine what the user’s intent is; what are they trying to accomplish? This is done in a standard app by the user clicking on a button. Obviously, there are no buttons. When you get down to the basics, a bot is a text based application. Dialogs can make it easier to determine the user’s intent.

Introducing the Bot Framework

One of the most common phrases when I’m talking about technology for end users is “meet them where they’re at.” A big reason applications fail to be adopted is they require too large of a change in behavior from the users in question, having to open yet another tool, access another application, etc. We as humans have a tendency to revert to our previously learned behaviors. As a result, if we want to get our users using a new process or application we need to minimize the ask as much as possible.

This is one of the biggest places where bots can shine: they can be placed where our users already are. Users are already using Office, Slack, Skype, etc. A bot can then provide information to the user in the environment they’re already in, without having to open another application. Or, if they want to open an application, the bot can make that easier as well. In addition, the user can interact with the bot in a natural language, reducing the learning curve, making it seem more human, and maybe even fun.

At //build 2016 Microsoft announced the Microsoft Bot Framework, a set of APIs available for .NET and Node.js, to make it easier for you to create bots. In addition, we also announced Language Understanding Intelligent Service (LUIS), which helps break down natural speech into intents and parameters your bot can easily understand.

What I’d like to do over a handful of posts is help get you up and running with a bot of your own. We’ll use Node.js to create a simple “Hello, world!” bot, and then add functionality, allowing it to look up user information in GitHub, and then integrate it with various chat services.

Important notice

The Bot Framework is currently under development. As a result, things are changing. While many of the concepts we’ll talk about will likely remain the same, there may be breaking code changes in the future. You have been warned. ;-)

Getting started

Couple of prerequisites to take care of right up front. We are going to be using Node.js, so you will need to be familiar with JavaScript, and have some understanding of Node. There is an MVA on Node if you’re interested. I’m going to assume knowledge of npm as well. Finally, I’ll be using ES6 syntax as appropriate.

With that in mind, let’s create a folder in which to store our code, and install botbuilder.

1
2

npm init
npm install --save botbuilder

As for the initialization, I’m not overly concerned with the settings you choose there, as we really just need the package.json file; you can just choose all of the defaults.

Hello, bot

Let’s start with the stock, standard, “Hello, world!”, or, in this case, “Hello, bot!”

Creating an interactive bot requires creating two items, the bot itself, which houses the logic, and the connector, which allows the bot to interact with users through various mechanisms, such as Skype, Slack and Facebook.

In regards to the connector, there’s two connectors provided in the framework - a ConsoleConnector, perfect for testing and proof of concept as you simply use a Windows console window to interact with your bot, and the ChatConnector, which allows for communication with other clients, such as Slack, Skype, etc. You’ll start with the console connector, as it doesn’t require any other client than the standard Windows console.

As for the bot, you’ll create a simple bot that will send “Hello, bot” as a message. To create the bot, you will pass in the connector you create.

Create a file named text.js, and add the following code:

1
2
3
4
5
6
7
8
9
10
11
12

// text.js

const builder = require('botbuilder');

const connector = new builder.ConsoleConnector();
const bot = new builder.UniversalBot(connector);

bot.dialog('/', (session) => {
    session.send('Hello');
});

connector.listen();

Let’s start from the top. The first line is the import of botbuilder, which will act as the factory for many objects we’ll be using, including ConsoleConnector, as you see in the second line.

To create a bot, you need to specify its connector, which is why you’ll create that to start. The connector is used to allow the bot to communicate with the outside world. In our case we’ll be interacting with the bot using the command line, thus ConsoleConnector. Once you’ve created the connector, you can then pass that into the bot’s constructor.

The design of a bot is to interactively communicate with a human through what are known as dialogs. The next line adds in a dialog named /. Dialogs are named similar to folders, so / will be our starting point or root dialog. You can of course add additional dialogs by calling dialog yet again, but more on that in a later post. The second parameter is the callback, which, for now, will accept session. session manages the discussions for the user, and knows the current state. You’ll either use session directly to communicate with the user, or pass it into helper functions to communicate on your behalf.

The simplest method on session is send which, as you might imagine, will send a message to the user. If you run text.js, and type in anything and hit enter (make sure you type something in to activate the bot!), you’ll see the message.

1
2
3
4

node text.js

// Type: Yo
// Output: Hello, bot!

Interaction note

You need to send a signal to the bot first in order to “wake it up.” When you’re using the command line for initial testing this can be a bit confusing, as you’ll run the application and notice that nothing is displayed on the screen. When you run your bot, just make sure you send it a message to get things started.

Retrieving user input

Obviously, displaying a static message isn’t much of a bot. We want to interact with our user. The first step to doing this is to retrieve the message the user sent us. Conveniently enough, the message is a property of session. The message will allow us to access where it was sent from, the type, and, key to what we’re doing, the text.

Let’s upgrade our simple bot to an echo bot, displaying the message the user sent to us.

1
2
3
4
5
6
7
8
9
10
11
12

// text.js (full code)

const builder = require('botbuilder');

const connector = new builder.ConsoleConnector();
const bot = new builder.UniversalBot(connector);

bot.dialog('/', (session) => {
    session.send(session.message.text);
});

connector.listen();

You’ll notice we updated the session.send call to retrieve text from message, which contains the user input. Now if we run it we’ll see the information the user typed in.

1
2
3

node text.js
Hello from the user
// Output: Message: Hello from the user

Wrapup

Bots are a way for users to interact with services in a language that’s natural, and in applications they’re already using. You can integrate a bot with an existing application, such as a web app, or with a tool users are already invested in, such as Slack or Skype. We got started in this blog post with bots by first obtaining the SDK, and then creating a simple bot echo service. From here we can continue to build on what we’ve learned to create truly interactive bots.