8 minute read

You should read this first.

Adaptive cards in bots

What are dialogs in BotFramework SDK

Dialogs are a highlight of BotFramework SDK and they are at it’s center. Through them, you can write comprehensive conversations that the bot will engage in with users. Rather than having a bot that just responds to user with a predefined message to a specific keyword. With botframework dialogs, bots can give you real “dialog” experience. For example:

  • Hey, I’m Boty, your virtual assistant today, can I have your name ?

  • John Doe

  • Nice to meet you John Doe, need any help?

  • Yes

  • I can help you with: Our services, payment methods and customer feedback.

  • Alternatively I can patch you to our customer support.

  • Customer feedback

  • Great, how would you rate us from 1 do 10?

  • 9

  • Write your feedback.

  • I’m very satisfied with the service, but it could be improved.

  • Thank you for your feedback. Would you like to get notifications on new products, discounts and similar stuff?

  • Yes

  • Please provide your e-mail.


  • Thank you very much, anything else I can help you with?

You get the idea, basically the bot keeps talking to you as long as you reply. If the user told “no” to the first question about help, the bot would jump to the question about e-mail notifications. That’s the default question after ending any branch of the dialog. The branches here would be:

  • Services
  • Payment methods
  • Customer feedback
  • Customer service

Something to think about when writing a dialog

Bot dialog has many benefits and can be great when used correctly, however, it’s best to keep it simple sometimes. You don’t need to create a dialog if you can achieve the same results with a simpler method. Let’s say that you want to collect a few user inputs, and let’s say that they are dynamic, so you’ll have as many prompts as many inputs there are. In that scenario, you might want to send an adaptive card with input fields and pass the data where needed. Don’t over complicate things if there’s no need for it. But it all depends on your use cases. A dialog can be more compelling and have a better appeal to people, but in a company or school, you need speed, efficiency and reliability. Great thing is, botframework SDK offers you many options to optimize your bot for your use cases.

Types of dialogs

There are 9 different types of dialogs in BotFramework SDK according to Microsoft’s official documentation.

  • Waterfall dialog

  • Adaptive dialog

  • Component dialog

  • Container dialog

  • Prompt dialog

  • Action dialog

  • Input dialog

  • Skill dialog

  • QnA Maker dialog

There are quite a few, but some are a part of others and can’t be used without them. Like input and action dialog, it can only be used in adaptive dialog. You should read about dialogs a bit more in the official documentation before you start using them.

How to write a dialog

This will be explained in detail in our next article. We’ll just do a little introduction here.

First you need to plan out your conversation and decide what type of dialog you will use. Dialogs, like bots, are written in the same way in a separate JS file. So, you need to make one and create your class, constructor and module exports with the name of your dialog. It’s recommended that the keyword “dialog” be in the name of the file to differentiate it better from other files. For example: helpDialog.js.

We need to create new files and add some code to the existing ones in order to get ready to write dialogs. This includes importing some new classes and include them where needed. Mainly you’ll import classes, that you want to use, from botbuilder-dialogs. Once you have that ready, you should start writing your dialog. We’ll now tell you  what to add to which existing file in order to have your dialog template.


Copy to Clipboard

Above, you can see a few lines that you need to add to your existing index.js file in order for your dialog to work. We need to import some new classes that we’ll use to write a dialog. We also need to include them where needed.  Then, we need to import our dialog file and pass it to our bot when starting it. We also need a memory storage to store our conversation state. We need that state to know where we are in our conversation. Without conversation state, a bot might always repeat the first dialog step because it doesn’t know that we already answered it. We also need to update “onTurnErrorHandler” function so it deletes “conversationState” when an error occurs to clear the dialog so it can start from the beginning next time it launches.

You can already see that dialogs are a bit more complex than, for example, keyword scripts or adaptive cards.


Copy to Clipboard

This chunk of code goes in the constructor, that’s why we wrote it this way. The “…” means that there is a chunk of code in that place. The 3 if statements aren’t necessary, but they are here to make the debug easier. Actually the only thing that we need to do is to define our properties.


Copy to Clipboard

This is pretty much how our dialog template would look like. We should note that we’re gonna be writing a waterfall dialog. But, regardless of which dialog you write, you have to include it in a bot and use it from there. There’s a few thing that you need to do for that.

Waterfall dialog

Since we’re writing a waterfall dialog, let’s describe waterfall dialogs a bit more to better understand what’s going on.

Waterfall botframework dialogs are linear set of steps that the use is guided through. Think of it like filling a form. They are designed to work with the context of component dialog and consist of a set of defined steps. Those steps are considered prompts. And in the code you can see we included some prompts like “choice prompt”, “name prompt” and so on. That’s because not all prompts are the same.

Uses for a dialog

  • Taking user data like name, last name, age, etc.

  • Showing products, special offers and offering subscription

  • Offering coupons and discounts

  • Quizes

  • Taking inputs for a remote script/action

Up next.

Writing bot dialogs