9 minute read

You should read this first.

Bot Framework Dialogs

How to start writing bot dialogs

First you have to plan out your conversation and see how it should go. This is important to choose the best type of dialog to use because not all of them are suitable for everything.

  • Is your conversation gonna be linear or is it gonna have multiple branches
  • Will it be a long or short dialog
  • Is there a better way to achieve the same goal, maybe an adaptive card or a keyword script

It’s important that you read the previous article before reading this one because we covered a lot of preparations there.

Managing dialog

When you’re running a bot, it’s “idling” if not called to do or answer something. When it’s called to do something, it does it and goes back to idling. Doesn’t matter how many scripts you run, it’s gonna execute them and go back to idling. On the other hand, if you’re running a dialog, you’ll have to manage some things. Let’s say that you want to run a command in the middle of a dialog and then get back to the conversation. If you haven’t covered that, your bot will take the keyword of the command as a step input in your dialog. If you account for interruptions and manage them, you have to have a way back in the running dialog at the exact same place you were before. You don’t want to reload the entire dialog, specially if the dialog is very long. Read more about managing state.

You should also put a timeout on a dialog so if you interrupt it or just don’t answer on a certain step, you don’t end up in the middle of the dialog again when you really don’t want to. Also, you don’t want your dialogs to stay active, specially if they’re looped.

We’ll show you how to manage that when, writing bot dialogs, in our next article, now we need to build our dialog first.

Our dialog

Finally, let’s describe our dialog. So it’ll be like a simple user profile creation where you have to provide your name, age and picture. Only the name will be requierd, and before entering age, you’ll be asked if want to give that information or not. If you choose to provide your age, it must be a number between 1 and 110, otherwise the bot will ask you to enter it again. It’ll also display the message explaining the age limit. The prompt will repeat until you get it right. When asked to upload a picture, you can just type anything to skip that step. At the end, you’ll be asked if you want to keep your data or not. If you choose to keep it, you’ll get the data displayed, if not, you’ll get the message saying that your data wasn’t kept.

Simple enough, let’s start.

User profile

We need a way and a place to save the answers that user is providing, specifically, his user profile that he’s creating through dialog. So this is our UserProfile class in a new userProfile.js file.

Copy to Clipboard

Dialog development

Writing bot dialog file structure

Here is our file structure. For now all files are in the same directory, but as bot gets more complex, dialogs should be in a separate folder, different bots in their folder, cards in a separate folder and so on.

Considering you have all the code from previous article, let’s start developing our dialog. Our userProfile.js and index.js won’t change through this development, we just write our dialog in dialog.js and run it in our bot.js file.

Defining steps

When writing bot dialogs, first, we define the prompts we’re gonna use, our dialog and it’s steps in dialog.js. You can see how we did it in the code bellow.

Copy to Clipboard

After creating properties to use our userProfile, we add our prompts to the dialog. After that we add our steps to our waterfall dialog in order we want them to execute. You can also see we are using 2 validators:

  • agePromptValidator
  • picturePromptValidator

Those are used to validate the input on the age and picture step because you want to limit those inputs to a picture and to a natural number lesser than 110. Otherwise, reprompt the steps. We’ll explain those validators in detail later.

Writing steps

Copy to Clipboard

Here’s a lot of code, so let’s break it down a bot. We have 6 asynchronous functions. Each for one prompt that bot sends us. So in a more laic term:

  • Name
  • Age yes / no
  • Age
  • Picture
  • Accept / discard profile
  • Summary
Steps explanation

In the nameStep, bot sends a prompt for the user to give his name. This prompt is required.

Right after that comes the giveAgeStep where we send a thank you messasge and prompt the user again. This time to ask him if he wants to give his age or not.

Then in the age step, the bot asks for our age if we said we want to give our age.

In the pictureStep, the bot first displays the message that the age is not given, if you said no to the question in giveAgeStep. After that the bot asks for the picture.

Finally, the bot asks us to keep or discard our profile in confirmStep.

If we decide to keep it, it show’s us our data, if we decide to discard it, it displays the message that the profile was not kept. That is done in summaryStep

Copy to Clipboard

Nothing to fancy here, we check if the age is between 0 and 110 and with the picture validator we actually enable to skip the prompt by typing something.

Running the dialog

Copy to Clipboard

Here we run the actual dialog that we wrote. It’s run by the keyword “dialog“, if there was no keyword to act as a trigger, the dialog would be always active and loop infinitely. Well, at least as long as you provide answers, obviously. But it’d still be active all the time and you wouldn’t be able to do anything else in the bot. This is also written in our dialog.js file. But now we need to run the dialog from our bot because bot.js is the file that contains bot logic.

We need to write this method in the constructor of out bot.js to run the dialog in onMessage activity so that our keyword can trigger the dialog.

Copy to Clipboard

We also need this function to store our conversationState and userState so our dialog can process normally, without this function, the dialog stops after the first step.

Copy to Clipboard

End result

New bot dialog

Up next.

Dialog interruptions and cancelation