11 The Conversation Designer

The Conversation Designer (accessed by clicking This is an image of the the Conversation Designer icon in the left navbar. in the left navbar) enables you to quickly build a functioning skill by writing a typical user-skill conversation.

You don't need to create intents, entities, or write a dialog flow definition in OBotML when you use the Conversation Designer. In fact, you don't even need to be a skill designer. Your focus is not on the inner workings of the skill. Instead, it's on the user experience.

Because you can realize your concept as a working skill, and not as a static flow chart or slide deck, you can achieve stakeholder buy-in. You can also test the skill with target users for further feedback. While the skill itself functions as a demo (you can't build such features as Q&A or agent integration, for example), it can provide the basis for further development.


The Conversation Designer is in Beta release.

Get Started with Your Mockup

Before you build your bot, create the various use cases that you want your bot to support. Some of these are main use cases (Order a Pizza for a pizza bot, for example). Others are secondary use cases that provide supporting functions. For example, they enable the conversation to transition from one main use case to another. In terms of the Conversation Designer, main use cases are tasks and the secondary use cases are subtasks.

After you've formulated your tasks and subtasks, think of how users will typically ask the bot to complete them and how your bot replies and prompts for more input using text messages, lists of options, and carousels. Once you've done this, you can assemble your mockup by performing cycles of the following steps:
  1. Add the tasks and subtasks.
  2. For each task, build a conversation flow by adding user and bot messages. The Conversation Designer classifies these messages in various ways, including Output, Confirmation, Choice, and Intent Utterance.
  3. Preview the tasks. At any point, you verify conversation flow by previewing it. The Conversation Designer’s preview mode replays the messaging sequence.
  4. Generate the bot from the mockup, train it, and then chat with it using the Skill Tester.
  5. Build out the starter bot into a production-level bot.


Your mockup begins with a new bot. You can’t extend an existing bot with the Conversation Designer.

Add Tasks and Subtasks

A task (This is an image of the Task icon.) represents your main use case (Order Pizza, Check Balance). When you generate the bot, the Conversation Designer derives intents from the tasks.

A subtask (This is an image of the subtask icon.) performs a supporting function, an action that users don’t explicitly ask the bot to perform.

Add Messages to Tasks

To create a task flow, first select a task or subtask and then add messages using the Bot Speaks (This is an image of the Bot Speaks icon.) and Person Speaks (This is an image of the User Speaks icon.) icons. Clicking these icons opens the Add Message dialog. The options in this dialog depend on the speaker. You can edit, delete, or reorder messages using the context menu. You can add message from within the editor as well. The Conversation Designer generates execution paths for intents from the message that you assemble in a task. In addition to the execution paths (which you can review in the Skill Tester after you generate the bot), the Conversation Designer derives entities from the user messages.

User Messages

You can add text or, if the bot user needs to upload a form, an attachment message. The Conversation Designer classifies the text messages as:
  • Greeting Utterance
  • Intent Utterance
  • Entity
  • Choice
  • Yes/No
  • An attachment (such as an uploaded expense report)
User Messages for Tasks
Typically, the first message that you’d add for a task should be a user message, one that’s imperative in tone and clearly expresses the selected task. For example, use I want to order a pizza instead of I’m hungry. To ensure that the Conversation Designer classifies this message correctly as an Intent Utterance, end the message with a noun. The Conversation Designer might not classify messages without a noun in the predicate correctly. It would classify I want as Unclassified Utterance, for example.


Be selective in your word choices to avoid nouns that can be interpreted as verbs (use “sabbatical” or “time off” in place of “leave”, for example).
User Messages for Subtasks

Because subtasks perform auxiliary functions (and therefore aren’t associated with the Intent Utterance-type messages that begin tasks), you don’t need to start a subtask flow with a user message. Begin the subtask with a bot message instead.

When you start a subtask flow with a user message, the Conversation Designer it as Unrecognized (This is an image of the message error icon.). A user message won’t prevent you from running the task in the preview mode, but the message itself will appear out of context for the actions that you’re demonstrating in the preview mode.


The Conversation Designer converts the message from UNRECOGNIZED to INTENT UTTERANCE when you clear the Sub-Task option.

Bot Messages

For the bot, you can create messages that are text (prompts), actions (a list of options), a carousel of horizontally or vertically scrolling cards that have images and actions, or various attachment messages for downloading images, audio files or documents.


Add actions for each card.
The card and action messages let you branch the dialog to other tasks or sub tasks. These actions can open a task or subtask, or a URL.
Default Actions

By default, the Conversation Designer designates the first card or action as the default choice (designated with a check mark) for the preview.

A default action specifies the task’s message flow in the Preview Mode. You don’t need to add a user reply for the default cards or actions.

The checkmarks designate the default actions that execute when you preview your task flows. They’re selected in the preview. If you add a user message that specifies a different option, then the preview goes with that instead. For example, if the default choice in an action message is set to Pizzas, but the user response message is Pastas instead, then the conversation will branch to the pasta menu rather than the pizza menu that was specified by default.

Preview Tasks

At any point, you can preview a task or subtask by clicking Preview Your Task! (located at the upper left). You can use the preview mode to test an individual task, or when you've connected your tasks through actions, you can preview an entire flow.

The preview mode is a story board presentation, one in which the messages are replayed in the same sequence that you entered them. The flows branch according to the default actions. Whenever the conversation calls for user input (for example, at the start of task), click Enter or tap the Send Message icon (This is an image of the Send Message icon) that’s located within the chat window.

While you prompt the presentation along by clicking Enter or the Send Message icon, that’s where your interaction ends. You can’t enter new messages, scroll through a carousel, click non-defualt actions, or upload attachments. You can’t execute the tasks with new messages until after you’ve generated your bot.


Test each action that you’ve added to an Action or Card message to ensure that the intended URL, task, or subtask opens.

Generate the Bot

Throughout your development process, you can generate a bot from your mockup and then chat with it using the Skill Tester (This is an image of the Skill Tester icon.). This bot, one created by first clicking Generate (This is an image of the Generate icon.) and then Train, is a starter bot, a skeleton. It has a greeting intent, intents derived from the tasks (each with a small set of utterances), a composite bag entity, and a dialog flow definition with variable declarations, error handling, and a System.CommonResponse component.

This bot is not production-ready, but as you're a bot developer, you can use this skeleton as the basis for further development. You can refine the composite bag entity, expand the corpus, and update the dialog flow. You can also add user-scoped variables, configure multi-value entities, and add features like Q&A, user agent integration, OAuth, webviews, and translation.


You can update the dialog flow directly, but until you finalize the mockup, any changes made to the OBotML will get overwritten when you update your mockup in the Conversation Designer and regenerate the bot.

The Mockup Definition

In addition to the bot artifacts, the Conversation Designer also generates the mockup definition as a JSON object (located at the top of the dialog definition). This object preserves the initial concept of bot even as it evolves through different versions.


You shouldn’t edit this definition because doing so might break the mockup. Instead of editing it directly, update the mockup in the Conversation Designer and regenerate the bot.
Editing the dialog flow definition directly causes the bot to get out of step with the mockup. And any changes that you make in the YAML will get overwritten when you regenerate the bot.
#!  "mockup": [
#!    {
#!      "name": "default",
#!      "tasks": [
#!        {
#!          "name": "Order Pizza",
#!          "type": "task",
#!          "description": "",
#!          "conversation": [
#!            {
#!              "actor": "user",
#!              "component": "text",
#!              "properties": {
#!                "message": "I want that pizza"
#!              }
#!            },
#!            {
#!              "actor": "bot",
#!              "component": "actions",
#!              "properties": {
#!                "message": "We don't have any.",
#!                "actions": [
#!                  {
#!                    "text": "not this",
#!                    "isDefault": true
#!                  },
#!                  {
#!                    "text": "not that"
#!                  }
#!                ]
#!              }
#!            }
#!          ]
#!        }
#!      ]
#!    }
#!  ]

Best Practices

  • Start each flow with a user message that’s imperative in tone and ends with a noun, like I want to order a pizza or Check my balance. This sentence structure enables the Conversation Designer to classify the message as an Intent Utterance.
  • Cards, whether they exist singly or as part of a carousel, all need actions. You can add global actions and/or individual actions for each card.
  • Test each action in preview mode to make sure that it opens the intended flow or URL.
  • After you generate the bot, do not edit the mockup definition in the dialog flow definition directly. Doing this might render the mockup unusable in the Conversation Designer.
  • After you generate the bot, avoid updating the dialog flow definition (or entities) until you have finalized your mockup. The bot will become out of sync with the mockup because of these interim changes. They will also be overwritten when you regenerate the bot.


  • Attachment: A file that can be downloaded or uploaded.
  • Card: A bot message type that displays an image and has actions that branch the conversation flow to a task or subtask, or open a URL. Each card needs an action.
  • Entity: A key word from the message. The Conversation Designer classifies messages as Entity, or Entity (Multiple).
  • Intent Utterance: An imperative user message that ends with a noun.
  • Subtask: A an ancillary task. You don’t need to begin a subtask with a user message.
  • Task: The bot’s primary use case. Typically, the message flows for a task begin with an Intent Utterance.