Best Practices: Collaborative Approach to ChatBot Design using Bot Framework Tools

Share on facebook
Share on twitter
Share on linkedin

There are already many articles and documents that have been created on how to develop a ChatBot using the Microsoft Bot Framework and how they can easily be integrated with many of the Cognitive Services that Microsoft provides. Matter of fact, you will see links to many of them listed below in the Additional Information section. However, I have not seen much in the way of best practices for the actual design of the Bot, specifically the conversation flows and what actions should the user be able to perform as well as how.

For the more traditional type of application, be it a Native, Mobile or Web based application, there are many tools out there to help with the design process, such as UI mock-up and API stubbing tools and let’s not forget about the the all important process flow and entity relationship diagrams. All of these items can be used by application designers and architects when working with the business owner to make sure that the application is going to meet all of the user’s needs and the business’s requirements.

In the world of Bot Applications, because the technology is still so new, there aren’t quite as many options, but Microsoft has done a great job in putting together some simple Command Line tools that can provide a great design mechanism for working out how a Bot should be developed.

  • ChatDown
  • LuisDown
  • QnAMaker
  • BotMaker
  • Bot Emulator

I am bringing this up, because I have been working with a great customer (Genex) to help them build out the first of what I hope will be many ChatBot applications. We have been using these tools in a very collaborative way directly with the business owners to make sure that the design aligns with exactly what they are looking for.

The Collaborative Approach

The title for this section might sound a little counter intuitive and it certainly does not fit with the design and development methodology for more traditional applications. When we kicked off this project with the customer, I made sure to let the business owners know as well the technical lead at Genex that we would be working together to help drive the success of this Bot application. What I meant by that is we would be collaborating on the design while I still did the majority of the actual NodeJS development.

In traditional software development the software designer or architect would perform the following steps pretty much on his/her own:

  • interviews with business owners and key stakeholders to gather requirements
  • write everything up into a requirements document
  • create the necessary diagrams and mockups
  • submit them for approval and review

NOTE: Before anyone starts writing up nasty comments on the Blog Posting, I do understand that the best software companies and developers are always asking for and accepting customer and user feedback, but that is usually a one-way street with the exception of a very limited set of beta testers and even then it is much later in the development process.

In the case of this Genex ChatBot, right from the beginning, I made sure that the Technical Lead at Genex was in constant talks with the business owners and was getting approval for each conversation that we created. In addition, using the tools that I mentioned above, the business owners themselves could review and make changes to the proposed mockups or integrations on their own without worrying about how to develop anything themselves.

Now you might be asking, how that is possible and why would you ever want a business owner to be that deeply engaged in the design and development process? One very simple answer: “Application Success”

Getting Started – Conversation Flows

We started by designing what conversations or dialogs would actually be available to the user and what actions would the user be able to perform using those conversations. In this application’s case, there were four distinct conversation paths:

  • User Profile Updates
  • Predictive Analytics Response
  • Knowledge Base Search
  • Claim Management System Status Check

The first and last ones are pretty straight forward in that they are just integrations with the Genex Claim Management system, but we are providing integration against it using this ChatBot application. The first is making updates to that system and the last is making information requests from the system.

The second item is performing a request of a Azure Machine Learning model that has already been created and made available as a web service. The Knowledge Base search is something that is completely homegrown, but can be easily developed using the QnA Maker capabilities within Azure.

Conversation Flow Design

Now that we know what types of conversation the user will be having with this Bot application, we need to figure out how the conversations should flow. This can be done in a very collaborative way using the ChatDown tool.

We started with the easiest one to understand, which was the User Profile updates. In this case, we focused on the ability for the user to make Phone, Email, or Address changes to their User Profile within the Claim Management system. The ChatDown tool uses Markdown language to show a simple conversation between a User and the Bot. This can then be converted to a “transcript” file that can be read by the Bot Emulator so that the business owners can see what the conversation would look like in a Chat window without any development having even been done yet.

The process that we used to make this as collaborative as possible was the following:

  1. I created the first ChatDown file to correspond to the updating of a User’s Phone number
  2. I converted the first file to a transcript
  3. I then taught the tech lead at Genex about the anatomy of the Chatdown file and how the Chatdown tool works
  4. I then showed the transcript within the Bot Emulator so that he could see what the conversation would look like
  5. I then gave the Tech Lead homework to create the remaining Chatdown files and convert them to transcripts
  6. Lastly, the Tech Lead sat down with the business owners and showed them how to use the Bot Emulator to view the transcripts themselves so that they could provide feedback so that changes could be made prior to development

One additional step that could be used and I will probably be introducing in the future is to actually give the business owners access to the ChatDown files before they are converted so that ownership of the conversation design is completely on them rather than the developers. An example straight from the Genex Bot application can be found below showing the ChatDown file.

Remaining Conversation Patterns

Remember that I mentioned a much longer list of tools above that would be available for use, other than just ChatDown. The ChatDown tool should always be the first place you start when designing each of the conversation flows. However, what happens when you want to use the QnA Maker or LUIS to help define the conversation flow in a more dynamic and user friendly way?

That is then when you look at the LuisDown tool or the QnA maker tool. Both of these tools also use markdown language to help describe either Questions and Answers for a FAQ and/or possible language based intents. Because the markdown language is so easy to understand, you can use the exact same collaborative process that I listed above just replacing ChatDown with one of the other tools.

This gives the business owners more responsibility during the design process for your ChatBot and makes them feel more involved there by making the application more successful.


In conclusion, there are some very collaborative ways to build and design a great Bot application making sure that all of the right people are actually helping to drive the success of the application. This collaborative process is made much easier because of all the great CLI tools that the Azure Bot Framework team have made available. To close this out, I want to show you how easy it is to work with these tools, by showing a video of some work that I did with Genex on their application using the ChatDown, LUISDown, LUIS APIs and Bot Emulator tools.

Lastly, in addition to all that I have discussed and shown, please take a look at all of the links below that can help you find out even more information about the Azure Bot Framework and the Framework tools that are available.

Additional Information

Share on facebook
Share on twitter
Share on linkedin

You may aso like

Cloud Architect – Gamer – Instructor