Oracle Cloud Infrastructure Documentation

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 just by writing a typical user-skill conversation. Using this design by example approach, you don't need to create intents, entities, or write a dialog flow definition in OBotML. The Conversation Designer generates these artifacts for you.

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

Get Started with Your Mockup

Your mockup begins with a new skill. You can’t extend an existing skill with the Conversation Designer. After you create a new skill, you create the mockup by iterating through the following tasks:
  1. Create tasks. A task represents one of your skill's use cases, like Order Pizza or Call support. Create a separate task for each use case.
  2. For each task, build a conversation flow by adding user and bot messages. Typically, conversations begin with a declarative user message ("I want to order a pizza").
  3. Preview the tasks. At any point, you verify conversation flow by previewing it.
  4. Generate the skill from the mockup, train it, and then chat with it using the Skill Tester.
The Conversation Designer creates a working skill by generating entities, intents, and execution paths in the dialog flows from the messages that you assemble in a task.

Create Tasks

Your first step in creating a mockup is creating a task. A task represents your main use case (Order Pizza, Check Balance, Buy TV). You can add other tasks as needed, but you need one to start developing your mockup. You can add 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. Conversations can't begin with the subtasks. Instead, the tasks, where you create the main flow of the conversation, branch off to subtasks.

You can add, update, or delete subtasks from the Tasks list, or convert a task to a subtask by choosing the Subtask option.
Description of add_subtask.png follows
Description of the illustration add_subtask.png

Build Conversations

Once you've created a task or a subtask, you can begin populating it with a sequence of bot and user messages that represent an interaction that's typical for that task.

To get started, first select a task or subtask from the Tasks list.
Description of select_task_from_list.png follows
Description of the illustration select_task_from_list.png

Next, create the back-and-forth messaging using the green Person Speaks (This is an image of the green Person Speaks icon.) and the blue Bot Speaks (This is an image of the Bot Speaks icon.) icons. Clicking these icons opens the Add Message dialog where you create the actual message content. The kind of messages that you can create differ depending on the speaker. User messages, for example, are text or upload messages.
Description of add_user_message.png follows
Description of the illustration add_user_message.png

Bot messages can also be text messages, but can also be messages that support user input, such as a list of options.
Description of add_bot_reply_message.png follows
Description of the illustration add_bot_reply_message.png

The Add Message dialogs have different options depending on the speaker. Like the Person Speaks and Bots Speaks icons that invoke them, they are color-coded as green and blue as an added reminder of the message's orginator.

The preview gets populated with the messages as you create them. The Conversation Designer highlights the keywords in these messages and indentifies the entity values that will be replaced by user input.
Description of highlighted_values.png follows
Description of the illustration highlighted_values.png

Tip:

By running your cursor over the messages in the preview, you can see the variables that hold the entity values.

You can edit, duplicate, delete, or move messages using the context menu, which you access by clicking on a message in the preview.
Description of context_menu.png follows
Description of the illustration context_menu.png

Conversation Patterns for Tasks

Typically, a task begins with an INTENT UTTERANCE message. To create a task:
  1. Select a task (This is an image of the Task icon.) from the Tasks list.
  2. Click the Person Speaks (This is an image of the User Speaks icon.) icon
  3. In the Add Message dialog, enter a request that's typical for the task. While you can begin a task with greeting-type message from either the user or the bot, to generate a functioning skill, the Conversation Designer must classify a user message at the start of the dialog flow as an INTENT UTTERANCE.

    For example, use "I want to order a pizza" instead of "I’m hungry." Keep the following in mind when composing an INTENT UTTERANCE message:
    • 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).
    • To ensure that the Conversation Designer classifies this message, 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 a Greeting. While this is valid message, an INTENT UTTERANCE classification is still required to generate an intent and an execution path in the dialog flow. Your task is not valid without one.
      The Error icon

  4. Click the Bot Speaks (This is an image of the Bot Speaks icon.) icon.
  5. Choose the bot message type to steer the conversation further by prompting input from the user, which can include values specific to your skill, or such built-in entity values as email addresses and numbers.
    Note

    To ensure your generated skill behaves as intended, use the Conversation Designer's classification to verify the message content for any text message, whether it's from the bot or the user (or in a task or a subtask). Text Message Classification describes how the Conversation Designer evaluates messages based on their position in the dialog flow and content.


Conversation Patterns for Subtasks

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

To create a conversation for a subtask:
  1. Select a subtask (This is an image of the subtask icon.) from the task list.
  2. Click the Bot Speaks (This is an image of the Bot Speaks icon.) icon. When you start a subtask flow with a user message, the Conversation Designer classifies it as Unrecognized (This is an image of the Unrecognized 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.
  3. If needed, add a user reply followed by other bot messages Designer retains the keyword values that you added in the task-level messages, so you can reference them in the subtask's dialog.
    Description of tasks_in_preview.png follows
    Description of the illustration tasks_in_preview.png

User Messages

You can add text or, if the bot user needs to upload a file, image, or video, an attachment message. In addition to the GREETING and INTENT UTTERANCE messages that begin task dialog flow, the Conversation Designer can classify the user text message in different ways as well, such as CHOICE when the user message includes a value that matches the name of an action in a bot message. User Text Message Classification describes the different message types.

Add User Text Messages
To add a text message:
  1. Click Person Speaks (This is an image of the User Speaks icon.)
  2. Click Text.
  3. Enter the message that's appropriate to the context of the dialog and the intended content. Use the Conversation Designer's classfication as a guide.
  4. Click Done. When the Conversation Designer populates the message to the preview, it identifies built-in entity values, such as email addresses or numbers with bold text. It highlights terms from the INTENT UTTERANCE message and the values that will be replaced at runtime with user input, such as the names of actions or cards.
Note

If you alter the dialog flow using the context menu, make sure the Conversation Designer's classification remains valid. For example, clicking Move Up (This is an image of the Move Up icon.) in the context menu to reposition a user CHOICE message to the start of flow would reclassify it as UNRECOGNIZED (This is an image of the Unrecognized icon. )
Add User Attachment Messages

Add user attachment messages when user need to upload images, videos or files. For example, you can add an attachment message to an expense report skill to allow its users to upload receipts.

To add an upload message:
  1. Click Person Speaks (This is an image of the User Speaks icon.)
  2. Click Attachment.
  3. Enter the URL where the file, video, or image is hosted.
  4. Click Done.

Bot Messages

For the bot, you can create messages that are text, 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. 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.

Like user text messages, the Conversation Designer classifies the bot text messages differently based on their position in the flow, their content, and their proximity to user messages. Bot Text Message Classification describes these different message types.

Add Bot Text Messages
To add a text message to a task or subtask:
  1. Click the Bot Speaks (This is an image of the Bot Speaks icon.) icon. For tasks, add the bot message after the INTENT UTTERANCE message. If you're building a subtask, start the dialog with a bot message.
  2. Click Text.
  3. Enter a message, then click Done. When the Conversation Designer populates the message to the preview, it highlights terms from the INTENT UTTERANCE message and the values that will be replaced at runtime with user input.
  4. To verify the classification, select the message in the preview and then open the Edit Message dialog by clicking the Edit Interaction (This is an image of the Edit Interaction icon.) icon in the context menu. The classification can change depending on the message's position in the dialog.
Add an Actions Message

Create an Actions message when users need to pick a specific option. Actions messages can be a list of items that return values or actions that branch to another task or subtask, or open an external URL.

To create an Actions message:
  1. Click the Bot Speaks (This is an image of the Bot Speaks icon.) icon. For tasks, add the bot message after the INTENT UTTERANCE message. If you're building a subtask, start the dialog with a bot message.
  2. Click Actions.
  3. Enter a message in the Bot's Message field. When you generate the skill, the Conversation Designer creates a value list entity from the Actions message. It interpolates the name of the entity from the contents of this message and from the task name. For example, Choose a pizza size results in an entity called PizzaSize because it ends with size and is part of a message that was created for the Order Pizza task. You can reference variable values from previous messages. For example, That's a Veggie pizza. Now order a pizza size references Veggie, a value from a previous message. As in the previous example, this message would also result in an entity called PizzaSize.
  4. Configure the actions:
    1. Enter an action name. The Conversation Designer incorporates these names as the values in a value list entity.
    2. If you're not configuring this message as a list of values, then select an action by first clicking the menu (This is an image of the menu icon.) and then choosing either Branch Conversation or Go to URL.
      • For Branch Conversation, choose a task or subtask that you've already created, or create a new one by entering a name. To view this action in the preview, click Default. Then click Done. The tasks and subtasks that you create here display in the Tasks list. You can then populate them with messages.
      • For Go to URL, enter the URL. To view this action in the preview, click Default. Then click Done.
  5. Click Done. When the message is populated to the preview:
    • The default action for the preview has a check mark (This is an image of the Default icon.).
    • The branching actions (This is an image of the Branch icon.) and URL actions (This is an image of the Link icon.) are both noted.
Add Cards

You can add a carousel of graphics-rich cards that have images and actions that branch to other tasks and subtasks, or launch a URL.

To add a carousel of cards:
  1. Click the Bot Speaks (This is an image of the Bot Speaks icon.) icon. For tasks, add the bot message after the INTENT UTTERANCE message. If you're building a subtask, start the dialog with a bot message.
  2. Click Cards.
  3. In the General tab:
    • Choose a scrolling option (vertical or horizontal).
    • Enter a message. Enter a message in the Bot's Message field. When you generate the skill, the Conversation Designer creates a value list entity from the Actions message. It interpolates the name of the entity from the contents of this message and from the task name. For example, Choose a pizza type results in an entity called PizzaType because it ends with type is part of a message that was created for the Order Pizza task. You can reference variable values from previous messages. For example, That's a large pizza. Now order a pizza type references large, a value from a previous message. As in the previous example, this message would also result in an entity called PizzaType.
  4. If needed, add a global action that persists across the carousel:
    1. Enter an action name (Buy or Purchase, for example).
    2. Click the menu and then choose either Branch Conversation or Go to URL from the Action Type dialog.
      • For Branch Conversation, choose (or add) a task or subtask.
      • For Go to URL, enter the target URL.
    3. Click Done.
  5. Click Cards.
  6. Complete the card:
    • Enter a title and description. The Conversation Designer incorporates the enumerated values in the generated value list entity.
    • Enter a URL that points to an image.
    • Configure an action that returns a value, or branches to a URL or an external URL. You must configure an action for each card.
    • Enter a link that will appear below image. This is an optional property. You can't test the feature in the preview.
  7. Click Add Card (This is an image of the Add Card icon.) and repeat these steps.
    Note

    Add an action for each card.
  8. By default, the first card is displayed in the preview. To preview another card, click the menu in the card tile, then click Default.
  9. Click Done to close the Add Message dialog.
Add Bot Attachment Messages

You can add attachment that your skill's user can download by naming the URL that hosts the video, audio, image or file.

To add an attachment message:
  1. Click the Bot Speaks (This is an image of the Bot Speaks icon.) icon. For tasks, add the bot message after the INTENT UTTERANCE message. If you're building a subtask, start the dialog with a bot message.
  2. Click Attachment.
  3. Enter a message.
  4. Enter the attachment URL.
  5. Click Done.

Text Message Classification

The Conversation Designer classifies both user and bot text messages by their context, specifically by their position in the dialog flow and by their relationship to one another.

User Text Message Classification
The Conversation Designer classifies user text messages based on the entity values in the message.

Classification Description
GREETING UTTERANCE A typical greeting (Hi, Hello, Howdy) or an incomplete utterance such as "I want a".
INTENT UTTERANCE A typical user request. Best Practices describes how to form a user request message.
UNRECOGNIZED UTTERANCE Indicates a misplaced message, such as an INTENT UTTERANCE or GREETING in a subtask.
ENTITY A single string value. At runtime, this is rendered as a value list with a single option.
ENTITY (MULTIPLE) Multiple string values that are separated by commas. For example, a user message of "meat, vegetable, combo, cheese, potato". The Conversation Designer creates a list of values from this input. At runtime, this list is auto-numbered. You can use an ENTITY MULTIPLE entity to emulate the chat on a text-only channel. The Conversation Designer can interpret other comma-separated entries, such as a street address, as ENTITY MULTIPLE.
CHOICE Messages are classified as CHOICE when they include a value that matches an action in a bot Actions or Card message. CHOICE responses are optional. In the preview mode, they override the default action or card that's been configured for the preceding bot message.
UNRECOGNIZED CHOICE Messages are classified as UNRECOGNIZED CHOICE if they follow a bot card or action message, but don't contain correct values. For example, a user message of "huge!" following a bot message with actions of Small, Medium, and Large.
UNRECOGNIZED UTTERANCE Indicates a misplaced message, such as an INTENT UTTERANCE or GREETING in a subtask.
STRING Messages are classified as a STRING when they don't have nouns or adjectives. For example, messages such as "thanks", "bye", or "got it".
Classification of Built-in Entity Values
The Conversation Designer also classifies user messages by the following built-in entity types:
  • YES_NO
  • CURRENCY
  • NUMBER
  • DATE
  • URL
  • PHONE NUMBER
  • EMAIL
Typically, you would a add user message that contains one of these values after a bot message that prompts for a specific value. At runtime, these user messages enable the skill to validate the user input.
Description of runtime_built_in_entity_validation.png follows
Description of the illustration runtime_built_in_entity_validation.png
Bot Text Message Classification

Like user messages, the Conversation Designer classifies the bot message by context. For example, it classifies a bot's follow-up messages to an Action, Card, or Attachment message as an ACKNOWLEDGEMENT when these messages themselves are followed by other bot messages. In other cases, the Conversation Designer classifies the bot messages as OUTPUT, when it's the last message in the dialog, or PROMPT, when it precedes a user message that names a built-in entity value or an attachment.
Description of bot_message_classification.png follows
Description of the illustration bot_message_classification.png
Bot text messages get interpolated in different ways after you generate the skill. For example, PROMPT messages are incorporated into composite bag entities while OUTPUT messages are expressed as System.Output states in the dialog flow.

Add Variable Values to Messages

Use the highlighting to ensure that you're entering the entity values the same way for each message.
Description of matching_values.png follows
Description of the illustration matching_values.png

For example, if a user message includes 8:30 pm, the bot's reply should include 8:30 pm, not 830 pm.
Description of runtime_variable_replacement.png follows
Description of the illustration runtime_variable_replacement.png

If the values don't match, then the message will be treated as a string at runtime.
Description of runtime_string_message.png follows
Description of the illustration runtime_string_message.png

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-default actions, or upload attachments. You can’t execute the tasks with new messages until after you’ve generated your bot.

Tip:

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

Preview a Task

  1. Click a task or subtask in the Tasks list.
  2. Click Preview Your Task!
  3. Click Send Message to enter the user messages. These include the standalone user messages, and the default actions or cards.
  4. Test each action that you’ve added to an Actions or Card message to ensure that the intended URL, task, or subtask opens. To do this, change the default settings:
    1. Click the message in the preview.
    2. From the context menu, select Edit Interaction.
    3. Change the defaults:
      • For a card, click the menu in the card tile and then click Default.
      • For an action, click the menu and then click Default.
  5. When you've replayed the conversation, click Back to Mockup.

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 components.

This skill is not production-ready, but you can use this skeleton as the basis for further development.
Note

The generation is one way: you can look at the artifacts to understand the mechanics of the skill, but you shouldn't edit them. Changes that you make to the intent, entity, or dialog flow definitions cannot be applied to the mockup. They will be overwritten when you generate a new skill from the mockup and may also make the skill unusable.

The Generated Intents

The Conversation Designer generates a Welcome intent and a set of intents based on the task names and the content of the user INTENT UTTERANCE message. The content of this message is included in the training corpus as is the task name itself and variants of the task name.
Description of generated_corpus.png follows
Description of the illustration generated_corpus.png

The Generated Entities

As mentioned in Text Message Classification, the Conversation Designer generates a set of entities based on their context. It includes these entities, which can be built-in entity types or different types of custom entities, within a composite bag. Here are some examples:
  • Value list entities—The Conversation Designer generates these entities from the bot's Actions and Card, messages and from the user messages it classifies as ENTITY and ENTITY (MULTIPLE). It adds synonyms to the values.
    Description of generated_list.png follows
    Description of the illustration generated_list.png
    Within the composite bag, the Conversation Designer incorporates a prompt using the text that you entered in the Bot's Message field in the Add Message dialog for Cards and Actions messages. For the ENTITY (MULTIPLE) value list entities, the Conversation Designer derives a prompt message from the bot messages that precede the user message containing both the ENTITY and the ENTITY (MULTIPLE) content. (The Conversation Designer classifies this bot message as PROMPT).
  • Built-in entities—The Conversation Designer adds the Built-In entity type to the composite bag and adds the PROMPT bot messages that precedes it as the Prompt message string.
For each message included in the composite bag, the Conversation Designer generates an error message to validate the input:
'${system.entityToResolve.value.userInput!'This'}' is not valid for size.

The Generated Dialog Flow

The Conversation Designer declares all of the composite bag entities in the context section of the flow. If you added a cards, the creates a map variable for the cards and sets this object within the flow.
context:
  variables:
    iResult: nlpresult
    typeCards: map
    pizza: PizzaBag
    home: HomeBag
    location: LocationBag
The intents (derived from the tasks) are defined as the actions for the System.Intent component along with the seeded Greeting and unresolvedIntent actions:
states:
  mockupIntent:
    component: System.Intent
    properties:
      translate: false
      variable: iResult
    transitions:
      actions:
        Greeting: greeting
        OrderPizza: pizzaOutput
        unresolvedIntent: unresolved
Comments identify the dialog flow definition for each task. In the following snippet, the System.SetVariable state that sets the cards map variable follows a System.Output state that Conversation Designer interpolated from a bot message that it classified as OUTPUT.
#-------------------------------------------------------------------------------
  # Task "Order Pizza" -----------------------------------------------------------
  #-------------------------------------------------------------------------------
  pizzaOutput:
    component: System.Output
    properties:
      translate: false
      text: "Ok! Let's get started!"
      keepTurn: true
    transitions: {}
  setTypeCards:
    component: System.SetVariable
    properties:
      variable: typeCards
      value:
        veggie:
          title: Veggie
          imageUrl: "https://example1.com/veggiepizza.jpg"
          description: "Save the planet!"
          link: "https://example2.org/"
          action1Label: Order

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.
Note

Do not edit this definition. Any changes that you make to it might break the mockup. Instead of editing it directly, update the mockup in the Conversation Designer and 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"
#!                  }
#!                ]
#!              }
#!            }
#!          ]
#!        }
#!      ]
#!    }
#!  ]
#!}

Chat with Your Generated Skill

Because of the artifacts created by the Conversation Designer, you can demonstrate a "live" experience when you chat with it using the Skill Tester. For example, you can invoke the skill using different intent utterances, scroll the through the cards, open URLs, and traverse different conversation paths. You can also demonstrate the skill's validation of user input by entering incorrect values. For example, enter letters when the expected value is a number.
Description of chat_variable_populate.png follows
Description of the illustration chat_variable_populate.png
The chat also demonstrates how the skill can respond to out-of-order user input and update variables.
Description of chat_out_of_order.png follows
Description of the illustration chat_out_of_order.png

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.

Glossary

  • 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.