NAV Navbar

Creating Mix.dialog Applications

Mix.dialog is a multichannel dialog design development tool for creating conversational experiences. It works hand-in-hand with Mix.nlu. Use Mix.nlu to create NLU models to understand your users. In Mix.dialog, you build conversational interfaces to engage with them.

Get started

This section explains how to design a simple chat application. When you open a new project in Mix.dialog, a blank canvas appears in the center pane, with a Start node, a node palette, and the Components pane on the left. Once you have added nodes on the canvas, the Node properties pane becomes available on the right-hand side of the screen. Click Components or Node properties, on the toolbar, to collapse or expand those panes. You can change the position of the node palette by dragging it. Click the X button to close the palette. Click the Icon restore palette icon in the upper-left corner of the canvas to open the palette again.

As you add nodes and define their properties, the dialog flow takes shape in the form of a graph.

All applications start with a component called Main, which typically covers greeting the user and asking what they would like to do. Use a message node for the greeting, and a question and answer node for asking the user what they would like to do. Use an intent mapper node to connect the dialog flow to another component meant for a specific purpose, depending on the user’s response. For example, the chat application for an airline might let you book a flight, check the current status of a flight, and so on. In such an application, designing the dialog flow for booking a flight separately from the dialog flow for checking a flight’s status makes your dialog model more readable.

This scenario assumes you have created a Mix project. It does not require you to have already started developing the NLU model for your chat application in Mix.nlu—with its NLU panel, Mix.dialog also supports managing intents and entities. However, before you can preview a dialog design you might need to further develop the NLU model for the project by adding sample sentences and annotating them in Mix.nlu (refer to the Mix.nlu documentation).

Open your project in Mix.dialog

  1. On the Mix dashboard, click your new project if it is not already in focus.
  2. Click the large .dialog button above the area where project details appear.
    Btn dashboard dot dialog
    Mix.dialog opens with the DESIGN tab in focus, showing a Start node on a blank canvas in the center pane.
    Design initial view
  3. If your project supports multiple languages, use the menu near the name of the project, to choose the language you want to start with.
    Design choose language

Add NLU intents and entities

  1. Click NLU, on the toolbar, to open the NLU resource panel.
  2. Click +Add Intent.
  3. Type a name for your intent—for example, ORDER_COFFEE—and press Enter.
    The new intent appears in the mapping table.
  4. Next to ORDER_COFFEE, click Map this intent, and choose +Create Intent Component.
    Add nlu intent This adds a new ORDER_COFFEE intent component where you will design the part of the dialog to collect all the information required to fulfill this intent. The new intent component appears in the Components pane. This also sets a global default mapping from the ORDER_COFFEE intent to the corresponding ORDER_COFFEE intent component.
    Design intent component new
  5. Switch to the Entities tab.
  6. Click the Add icon Icon plus and type a name for an entity your application is meant to collect—for example, COFFEE_TYPE— and press Enter.
    The new entity appears in the list of custom entities.
    Add nlu entity
  7. Proceed in the same fashion to add, for example, COFFEE_SIZE.
  8. Click COFFEE_TYPE in the list of custom entities.
  9. In the area on the right-hand side, add a few representative literal-value pairs—for example, enter literals espresso, ristretto, americano.
    The literal text automatically doubles as the value, by default. If you want the value to be different, press Tab and type the desired value before pressing Enter.
    Panel nlu entities literals
  10. Proceed in the same fashion to add a few representative literal-value pairs for the COFFEE_SIZE entity—for example, literals large, and small.
    Multiple literals can have the same value, to help your application recognize the different ways a user might say an entity.
  11. Click the Add icon Icon plus next to the literal large, type double, and press Enter.
  12. Proceed in the same fashion to add the literal single, for the value small.
    Panel nlu entities literals2
  13. Click NLU again, on the toolbar, to close the panel.

Design your dialog

Main component example
Design main component coffee shop

Build a dialog by adding nodes and configuring their properties to direct the dialog flow based on interaction with the user.

Greet the user

  1. Drag a Message node from the palette onto the Start node on the canvas.
    This automatically connects the Start node to the message node.
    Design add message node
    The properties for this message node appear in the right-hand pane.
    Prop message node
  2. Click the default node name, Message, at the top of the Node properties pane, and replace it with a unique name—for example, Welcome.
  3. Enter the desired greeting message—for example, Welcome to My Coffee Shop!
    The message appears on the Welcome node.
    Prop message node wip

Collect the user intent

  1. Drag a Question & Answer node from the palette onto the GoTo area of the Welcome message node.
    This automatically connects the message node to the question and answer node.
    Design add question answer node
  2. (Optional) In the Node properties for the Welcome node, replace the default GoTo transition label, with Always, to make it more obvious that this transition is not conditional.
    Notice the GoTo field already indicates that the question and answer node is the next node in this flow.
  3. Click the question and answer node on the canvas.
    The properties for this node appear in the right-hand pane.
    Prop question answer node
  4. Replace the default node name, Question & Answer, with a unique name—for example, Get Intent.
  5. Enter the desired question—for example, How can I help you today?
    The question appears on the Get Intent node.
    Prop question answer node applied
  6. Expand User Input and click Collect.
  7. Choose NLU for your project under Collect Intent.
    Prop question answer node user input
  8. Click Add Intent Mapper node.
    Prop question answer node user input nlu
    This automatically connects the Get Intent question and answer node to an intent mapper node.
    Notice the intent mapper node indicates 1 Mapped Component. This corresponds to the ORDER_COFFEE intent that was earlier defined as a global default in the NLU panel.
    Design add intent mapper node
  9. Expand System Actions and click Default.
    Notice the GoTo field already indicates that the intent mapper node is the next node in this flow.
    Prop question answer node nlu intent actions
  10. (Optional) Replace the default GoTo transition label, with Always, to make it more obvious that this transition is not conditional.

Say goodbye to the user

  1. Click the intent mapper node on the canvas.
    The properties for this node appear in the right-hand pane.
    Prop intent mapper node
  2. At the bottom of the pane, expand the GoTo list, expand Add new, and choose Message.
    This determines what happens when the dialog returns to this intent mapper node from an intent component, after the interaction associated with a specific intent is complete.
  3. Click the Message node on the canvas.
  4. Replace the default name of the message node with a unique name—for example, Goodbye.
  5. Type the desired parting message—for example, Thanks for visiting My Coffee Shop. Goodbye.
    The message appears on the Goodbye node on the canvas.
  6. In the Node properties pane, expand the GoTo list, expand Add new, and choose External Actions.
    This automatically connects the Goodbye node to an external actions node.
    Design add end node
  7. (Optional) Replace the default GoTo transition label, with Always.
    Notice the GoTo field already indicates that the external actions node is the next node in this part of the flow.
  8. Click the external actions node.
  9. Replace its default name with a unique name—for example, End.
  10. Under Action Type, choose End.
    Prop external actions node end
    The End node represents the end of the conversation.
    Design add end node complete

Fulfill the intent

Intent component example

Design question router complete with wrap up message

  1. In the Components pane, click your ORDER_COFFEE intent component.
  2. Drag a Question Router node from the palette onto the canvas. The properties for the question router node appear in the right-hand pane.
    Prop question router node
  3. Replace the default node name, Question Router, with a unique name—for example, Get Order Details.
  4. Under Route to questions, specify every piece of information to be collected—that is, entities you have defined, such as: COFFEE_TYPE, and COFFEE_SIZE.
    Prop question router node entities
    The specified entities appear on the Get Order Details node, on the canvas.
    Design question router entities
  5. In the Node properties pane, next to COFFEE_TYPE, the first piece of information to collect, expand GoTo collect node, expand Add new, and choose Question & Answer.
    Prop question router add new
    This connects the Get Order Details question router node to a new question and answer node named COFFEE_TYPE, after the entity to collect.
    Design question router add question answer
  6. Proceed in the same fashion to add another questions and answer node for the remaining pieces of information to be collected—that is, the COFFEE_SIZE entity.
    Design question router add question answer2

Collect entities

  1. Click the COFFEE_TYPE question and answer node.
  2. Enter the desired question—for example, What would you like to drink?
  3. Expand User Input and click Collect.
    Prop question answer node user input show in actions on
  4. Since this scenario does not require the dialog flow to take different paths depending on the collected value, turn off all Show in Actions switches.
    Prop question answer node user input show in actions off
    Notice the values no longer appear on the COFFEE_TYPE node, on the canvas.
    Design question answer show in actions all off
  5. Expand System Actions and click View All.
    Prop question answer node system actions
  6. Under COFFEE_TYPE (Default), expand the GoTo list, then expand Return to, and choose Get Order Details.
    Prop question answer return to question router
    This means that, once the question and answer node has collected information relevant to the active intent—that is, any entities required to fulfill the intent—, the dialog flow goes back to the question router node. The question router node determines whether information still remains to be collected.
    A symbol representing the Return To transition appears next to the GoTo label on the COFFEE_TYPE node.
    Design return transition
  7. Configure the COFFEE_SIZE question and answer node in the same fashion:
    1. Add a question—for example, What size would you like?
    2. Turn off all Show in Actions switches.
    3. Set the Return To transition to return to the Get Order Details question router node.

Wrap up

  1. Click the Get Order Details question router node on the canvas.
  2. In the Node properties pane, under GoTo when questions are completed, expand the GoTo list, expand Add new, and choose Message.
    This connects the question router node to a new message node.
  3. Click the new message node on the canvas.
  4. Replace the default name of the message node with a unique name—for example, Wrap Up.
  5. Type the desired message—for example, Your coffee is coming right up!
    The message appears on the Wrap Up node on the canvas.
  6. Expand the GoTo list, and choose Return.
    Prop return from component
    When the dialog reaches this node, all interaction associated with the ORDER_COFFEE intent is complete and the dialog returns to the intent mapper node in the component from where this intent component was called.
    A symbol representing the Return transition appears next to the GoTo label on the Wrap Up node
    Design message node with return transition

Validate your design

  1. Click the gear icon Icon gear and, under Validate Design Panel, choose Show.
    The validation panel appears.
    You can change its position by dragging it. (Click its X button to close it.)
  2. Click Run Validation.
    The panel reports any issues found in the design.
    Panel validation done
  3. If the panel reports warnings (or errors), click Warnings (or Errors) to expand the list of issues.
    Note: With this simple dialog design, the validation panel reports missing transitions in the component called Main. This is because we haven’t configured the five global event handlers in the Start node. You can safely ignore these warnings for now. If the NLU model for your project is not yet available, this also generates a warning.
  4. Click an issue to bring the affected node into focus, and correct your design as needed.
  5. Click Run Again to validate your design again.

Preview your design

Dialog preview example

Try coffee shop all in one

Note: Before you can preview this dialog design you must further develop the associated NLU model by adding sample sentences, annotating them, and setting their verification status, in Mix.nlu (refer to the Mix.nlu documentation).

  1. Switch to the TRY tab.
    Mix.dialog prompts you to train (or retrain) your NLU model.
    Try nlu model train prompt
  2. Click Train NLU model (or Retrain NLU model), if appropriate; otherwise click Try anyway (or Use existing).
  3. Click one of the available channel profiles.
    Try it initial
    Mix.dialog generates channel-appropriate code for your dialog app, validates the code, and reports any issues found in the code.
    Try codegen validation warnings
  4. Click Continue.
    The Main flow of your dialog design appears in the main pane.
  5. If your project supports multiple languages, use the menu near the name of the project, to choose the language you want to use for this session, as desired.
  6. Click Start, in the chat pane.
    Your greeting and initial question appear in the chat pane.
    Try coffee shop start
  7. Type something in the chat box at the bottom of the pane and press Enter.
    A response appears, based on what you typed.
  8. Pursue the conversation until you are satisfied with your scenario.
    If you reached the end of the dialog, your can click Start New Session.
    Alternatively, click Restart at the top of the main pane, at any time, to try another scenario.

Refine your dialog

To further develop your dialog model you might consider these tasks:

Basic operations

This section describe basic operations you can perform to manipulate the elements of a dialog design, that is, components, nodes, and their interconnections.

Add a node

Define node properties

Click the node you want to configure if it’s not already in focus. The properties for this node appear in the Node properties pane.

To access detailed documentation for the node in focus, click the Information icon Icon info in the upper-right corner of the Node properties pane. This opens the Mix documentation in a separate browser tab, with the related section in focus.

Depending on the node type, you can perform most or all of these tasks:

See Design a dialog flow for more details.

Rename a node in the Node properties pane

  1. Click the node you want to rename if it’s not already in focus.
    The properties for this node appear in the Node properties pane.
  2. Click the default node name, at the top of the Node properties pane, and replace it with a unique name.
    Note: The name must be unique across all nodes and components in your project.

Rename a node directly on the canvas

Add a description to a node

  1. Click the node you want to describe if it’s not already in focus.
    The properties for this node appear in the Node properties pane.
  2. Click the Node description icon Icon file next to the node name, at the top of the Node properties pane.
  3. Enter the desired description (maximum 1000 characters), in the field that appears.
    Prop add node description

Show or hide a node description

When you click a node on the canvas, if the Node description icon has a blue indicator, this means there is a description for this node.

Remove a node

  1. Click the More icon Icon ellipsis v for the node you want to remove.
    Canvas node menu
  2. Choose Delete.

Add a generic component

In addition to the component called Main, Mix.dialog supports two types of components: intent components and generic components. To add an intent component, use the NLU panel (see Manage intents). This section explains how to add a component that is not an intent component.

  1. Click the Add icon Icon plus next to Components.
  2. Type a unique name for the component and press Enter.
    Note: Generic component names are limited to letters (A-Z, a-z), digits (0-9), and the characters _, ., :, ;, -, and ~, which you can use as separators, if desired. The name must be unique across all nodes and components in your project.
    The new component appears in the Components pane.

Rename a generic component

  1. In the Components pane, click the Edit icon Icon edit next to the generic component you want to rename (expand the Components list, if needed).
  2. Modify the name as desired.
    Note: Generic component names are limited to letters (A-Z, a-z), digits (0-9), and the characters _, ., :, ;, -, and ~, which you can use as separators, if desired. The name must be unique across all nodes and components in your project.

Delete a component

  1. In the Components pane, click the Delete icon Icon trash next to the component you want to delete (expand the Intent Components list, or the Components list, if needed).
    A message appears prompting you to confirm your intention.
  2. Click Confirm.

Switch to another component

In the Components pane, click the component you want to bring into focus (expand the Intent Components list, or the Components list, if needed).
The dialog design for the selected component appears in the center pane.

Filter the Components pane

You can narrow down the list of components and nodes that appear in the Components pane, by node type, keyword or both. For example you could choose to focus on decision nodes with the word “set” in their name.

Filter the Component pane by node type

Click the Filter Icon filter icon and choose the desired type of node.

Pane components filter node types

Only nodes of the type you chose remain visible in the Components pane.

To stop filtering by node type, click the Clear filter Icon filter clear icon.

Pane components filter node types clear

Filter the Component pane by keyword

Use the Search box to narrow down the components and nodes displayed in the Components pane.

Pane components filter keyword

Any components or nodes with a name that matches the search string remain visible in the Components pane.

To stop filtering by keyword, click the Clear search Icon search clear icon.

Show or hide the Components pane

Click the Show/Hide Components icon Icon pane components to hide the Components pane. Click the icon again to show the pane.

Show or hide the Node properties pane

Click the Show/Hide Node properties icon Icon pane properties to hide the Node properties pane. Click the icon again to show the pane.

Zoom and pan

When you open a project, or switch between components, the dialog design automatically appears with a predetermined layout at 100% scale.

Change the active language

If your project supports multiple languages, use the menu near the name of the project to switch to the desired language.

Design choose language

Global settings and behaviors

Global settings define common functionality such as error recovery and command handling. They determine how your application handles commands and events, and they define confirmation and recovery behaviors. You can define settings and behaviors for your application at different levels:

Scope Description
Global The top-level settings apply to all channel profiles, that is your whole project.
Channel profile Settings you define for a specific channel profile take precedence over the global settings, in all parts of your project under the dialog flow for this channel profile.
Entity Settings and behaviors you define for a specific entity will apply at any question and answer node where this entity might be collected, in the context of a specific channel profile. In an open dialog application where a question router node handles multiple entities to be collected, any of the question and answer nodes under the question router node is able to collect any of the entities. In such applications, setting entity behaviors at a specific question and answer node would not be sufficient.
Component Event handling and error recovery behaviors you define for a specific component take precedence over the default behaviors set in the Start node of your project. Component-specific behaviors are set in a component’s Enter node.
Node You can override some settings at the node level, for individual question and answer nodes and message nodes. Node-level settings take precedence over the global settings and any component-level overrides.
Message You can prevent users from interrupting specific messages by disabling barge-in at the message level, in the Messages resource panel.

Use the Project Settings panel to configure global behaviors for your whole project, and overrides for specific channel profiles and for specific entities in your project. To open the Project Settings panel, click the gear icon Icon gear and, under Project, choose Settings.

The Project Settings panel is organized into these categories:

Category Description
Conversation settings Set how many times the application will try to collect the same piece of information (intent or entity) before giving up.
Collection settings Set the low-confidence threshold, below which the application rejects a collected utterance and throws a nomatch event, the high-confidence threshold above which it is not necessary for the application to prompt for confirmation, the number of nomatch event before the application throws a maxnomatch event, and how many times the application will try to collect the same piece of information after failing to detect any response from the user. You can also choose whether the initial message is to be used, or not, after nomatch and noinput recovery messages at question and answer nodes. You can set different high- and low-confidence thresholds separately, for each entity in your project. In a multilingual project, you can set different confidence thresholds separately, for each language.
Confirmation settings Set the confirmation strategy for entities, including the low-confidence threshold below which the application rejects a collected utterance at the confirmation step and throws a nomatch event, and how many times the application will try to collect the same piece of information after the user responds negatively to the confirmation question. In multilingual projects, you can set different low-confidence thresholds separately, for each language. In projects meant to support a VoiceXML application, you can specify GRXML grammar references—available at the project level only—for speech and DTMF confirmation interactions. When specified, confirmation grammars apply to all channels.
Speech settings Set the desired recognition speed and sensitivity, and the default barge-in type (speech vs. hotword). Barge-in is enabled by default, and can be disabled for individual messages in the Messages resource panel, or at the node level (in the speech settings of a question and answer node, or in the settings of a message node).
TTS settings Choose the desired voice per language, including gender and quality, for the text-to-speech engine. No default values. Only available in projects with channel profiles that support the TTS modality.
DTMF settings Only available in projects with channel profiles that support DTMF input.
Grammars Specify, for each channel profile, whether to allow referencing external speech or DTMF grammars in question and answer nodes. Only available at the channel-profile level.
Collection default messages Add default messages to handle situations when your application fails to recognize the user’s utterance, when it fails to detect any utterance from the user, and when it reaches the maximum number of turns, nomatch events, or noinput events.
Confirmation default messages Add default messages to handle confirmation for entities, including recovery behaviors at the confirmation step. Creating confirmation default messages directly from the Project Settings panel allows you to reference the entity being collected in a generic way by using the Current Entity Value predefined variable.
Custom global commands Global commands are utterances the user can use at any time and which immediately invoke an associated action; for example: main menu, operator, goodbye. Enable the commands you want to support and add new ones if desired. In projects meant to support a VoiceXML application, you can specify GRXML grammar references for speech and DTMF command actions. Only available at the global (all channels) level.
Audio file extension Extension to append to audio file IDs when exporting the list of messages: .wav (default), .vox, or .ulaw. Only available in projects with channel profiles that support the Audio Script modality.
Entities settings Set a confirmation strategy for specific entities (predefined and custom), confirmation default messages, and other applicable settings in the collection, speech, TTS, and DTMF setting categories. Only available at the channel-profile level.

Detailed information appears on the panel itself, to help you understand the available settings. Click the Reset icon Icon undo to revert any modified setting to its default value. Click the Close icon Icon close to close the panel.

Language-specific settings

Language-specific collection settings example for the YES_NO entity

To support language-specific settings and messages, choose the desired language from the menu near the name of the project.

Language-specific settings and messages are available in these categories:

Configure global commands

Global command settings example

Panel settings global commands example

For your application to support global commands, you must add an entity to hold the recognized command values you want your application to support. Once you have enabled global commands, you can add handlers for the events those commands are meant to throw, in the Start node for your dialog design.

  1. Add a list entity—for example, COMMAND.
  2. Add literals for your entity—for example:
    Literal “goodbye” for value goodbye; “agent” and “operator” for agent; “main menu” for main_menu.
  3. In Mix.nlu, add at least ”goodbye” as a sample under the NO_INTENT intent, and annotate it with the COMMAND entity.
    Note: This is a workaround to prevent “goodbye” from being recognized as a value for a global entity that Mix.dialog does not yet support.
  4. In Mix.dialog, open the Project settings panel and scroll down to the Custom global commands category.
    Panel settings global commands
  5. Expand the Entity list and choose the entity you defined at step 1.
    Panel settings global commands entity
    Note: This entity becomes a reserved entity. You cannot assign its value to a variable or use it in dynamic messages.
  6. Enable a command (for example, Goodbye), and choose the entity value (goodbye) that represents this command.
    Panel settings global commands escalate
  7. If the project has channel profiles that support DTMF interaction, choose a DTMF key for this command, if desired.
  8. Proceed in the same fashion for the other commands you want to enable.
  9. If the project is meant to support a VoiceXML application, specify any required speech or DTMF grammar references:
    1. Turn on the desired option: Reference speech grammar, or Reference DTMF grammar.
      A new field appears.
    2. Expand the field, and:
      • Enter the name of the desired grammar file, including the extension (for example, my-command-grammar.grxml).
      • Choose the variable that is meant to hold a dynamic grammar reference at runtime.
        If the variable you want to use is missing, you can create it on the fly, and then use it immediately.
    3. (Optional) Export the grammar specification document, to be used by the VoiceXML application, if desired.

Add a global command

  1. Click the Add icon Icon plus next to the Entity selector.
    Panel settings add global command
    A new row appears.
    Panel settings add global command new row
  2. Choose the desired command event.
    Panel settings add global command choose event
    Tip: If your project does not yet have the event for the command you want to enable, you can create it on the fly.
  3. Choose the corresponding entity value, and a DTMF key if your project supports DTMF interaction.
    Your new global command is enabled by default.

Remove a global command

Click the More icon Icon ellipsis v for the global command you want to delete and choose Delete.

Specify external grammars for confirmation

Confirmation grammar settings example

Panel settings confirmation grammars example

  1. Turn on the desired option: Reference speech grammar, or Reference DTMF grammar.
    A new field appears.
  2. Expand the field, and:
    • Enter the name of the desired grammar file, including the extension (for example, my-confirmation-grammar.grxml).
    • Choose the variable that is meant to hold a dynamic grammar reference at runtime.
      If the variable you want to use is missing, you can create it on the fly, and then use it immediately.
  3. If you are specifying a DTMF grammar, choose the desired DTMF keys for Yes and for No.

Create a grammar reference variable on the fly

When setting a dynamic reference for a global command grammar, a confirmation grammar, or an entity grammar, you can create the required variable directly from the variable selector.

  1. Click the Add icon Icon plus next to Variables.
    Panel settings create variable
  2. Enter a name for the new variable in the field that appears.
    Note: Variable names are limited to letters (A-Z, a-z), digits (0-9), the dollar sign ($) and the underscore. They must not start with a digit. The name must be unique across all intents, entities, and variables in your project.
    The new variable appears in the list, with an indication that its type is String.
  3. Choose the new variable.

Design a dialog flow

In Mix.dialog, the component called Main handles the main dialog flow for your application. If your application involves NLU intents, use intent components to handle the intent-specific dialog flows. In addition to making your design more readable and easier to maintain, using separate components makes it possible for multiple designers to work concurrently on a dialog project.

In Main, the Start node is where the application starts. In other components, the dialog flow proceeds from the Enter node until it returns back to Main.

When designing a multichannel application you can define channel-specific messages or channel-specific branches in the dialog flow.

Dialog design elements

A dialog design comprises nodes that perform operations such as prompting the user, evaluating a response, retrieving information from a backend system, or transferring the user to a live agent for assistance.

Mix.dialog provides several types of nodes that each perform a specific kind of operation. The node types are identified by distinctive icons.

Icon Node type Description
Nod start Start Starts the conversation
Nod question answer Question & Answer Listens for and recognizes user responses
Nod message Message Performs non-recognition actions, such as playing a prompt, assigning a variable, or defining the next node in the dialog flow
Nod decision Decision Determines the next node in the dialog flow
Nod data access Data Access Exchanges information with a backend system
Nod question router Question Router Specifies multiple pieces of information to be collected, and determines the next node in the dialog flow, based on the information collected so far
Nod intent mapper Intent Mapper Handles data for NLU/call routing menus
Nod sms SMS Not yet available
Nod email Email Not yet available
Nod component call Component call Temporarily passes control to another component
Nod enter Enter Enters the part of the dialog flow in the current component
Nod external actions External Actions Supports actions to be performed when ending a conversation, transferring to another system, or escalating to a live agent, and allows exchanging information with an external system via a client application
Nod transfer Transfer Deprecated—In legacy projects, please replace any transfer nodes with external actions nodes
Nod end End Deprecated—In legacy projects, please replace any end nodes with external actions nodes

Set up the Start node or an enter node

Start node properties example

Prop start node initial

The Start node is where your application starts. Similarly, an Enter node is where a specialized component of your application starts. Neither support interaction with the user but you can use them to perform variable assignments. Remember that variables in Mix.dialog have a global scope. You cannot rename the Start and Enter nodes.

The Start node is also where you set default behaviors for handling events and errors that might occur at any question and answer nodes in your project. Event handlers you define in the Node properties pane for your project’s Start node have a global scope; that is, they can catch events associated with global commands, recognition events, collection events, custom events, and so on. Event handlers you define in the Enter node for a component are limited to catching events that occur in the context of the specific component. Component-level event handlers have precedence over global event handlers in your project. You can configure local overrides for these behaviors at the node-level for specific question and answer nodes.

Mix.dialog automatically connects the first node you drag onto the canvas to the Start node (in Main) or to the Enter node (in any other component). If you later want to connect the Start node (or an Enter node) to another node, drop the new node directly onto the canvas, if it is not there already, and change the GoTo transition of the Start (or Enter) node.

Click the Start node (in Main) or the Enter node (in any other component), to see its properties in the Node properties pane.

Add an event handler

Click Add Event Handler at the bottom of the Component Events section.

Prop enter node add event handler

Blank fields appear.

Prop add event handler blank

Remove an event handler

Click the More icon Icon ellipsis h for the event handler you want to delete and choose Delete.

Configure an event handler

  1. Choose the desired event to handle—for example, Escalate.
    Tip: If your project does not yet have the event you want to handle, you can create it on the fly.
  2. Set the GoTo transition to the node (or component) that will handle the event.
    For example, the event thrown by the Escalate command could be handled in a separate component named Escalation, in which case you would point the GoTo transition to a component call node for the Escalation component.
    Prop start node event handler escalate

Create a custom event on the fly

When setting up the Start node or an Enter node, you can create a custom event directly from the event selector of an event handler. It is also possible to create a custom event directly from the event selector for a custom global command, and from the event selector when setting a throw event action.

  1. Click the Add icon Icon plus next to Select event.
    Prop add event from handler
    A text field appears.
  2. Type a name for the new custom event in the text field and press Enter.
    Prop add event from handler adding
    The new event becomes available.
    Prop add event from handler added
  3. Click the new event to choose it.

Set up a question and answer node

A question and answer node prompts the user for information, and then recognizes the user response. Click a question and answer node on the design canvas, to see its properties in the Node properties pane. The properties for a question and answer node are organized across these categories:

Category Description
System Question The systems invites the user to say something—for example, How can I help you today? or Where are you flying from? You can set separate, channel-specific or conditional messages. For example, you might want a different wording for the system question, depending on the channel. If the dialog flow can come back to this node, you might use a reentry message. Add messages to handle confirmation, and recognition events (such as nomatch, maxnomatch) locally, if desired. Recovery messages and confirmation messages set at the node level override any corresponding collection default messages or confirmation default messages from your project settings.
User Input Choose the type of information to collect: either an NLU intent, or an entity. For an entity, determine whether value-specific actions are required. If this question and answer node is meant to collect an entity whose values are determined by a grammar (as opposed to being subject to NLU), you can specify speech and DTMF grammars and set DTMF mappings for channel profiles that support these modalities. The ability to reference grammar files in question and answer nodes must be enabled in your project settings, for the appropriate channel profiles. Use the Grammars tab of the NLU resource panel to export a grammar specification document, to help design and manage grammars that will be referenced by a VoiceXML application. You can configure interactive elements for values of a yes/no, Boolean or custom entity. Only available in projects with channels that have interactivity enabled. Not available for isA relationship entities.
System Actions Set where to go next, or throw an event. You can add messages, assign variables and define conditions to determine which actions and which transition are to be performed. A simple question and answer node meant to collect an entity typically returns to the question router node that handles the entities for an intent.
Advanced Configure local event handlers for events that should be caught at this specific node, if any. Node-level event handlers take precedence over the global event handlers set in your project’s Start node, and any component-level overrides set in the Enter node for the component of this question and answer node. Specify a question router node to handle any captured entity or intent that is not the entity in focus for this question and answer node. Specify data to send to the client application. Override global settings, if needed.

System question properties

Add the system question

  1. Expand System Question and click Initial Message.
  2. Type the desired system prompt—for example, How can I help you today?
    Prop question answer node initial message
    The message appears on the question and answer node on the canvas.

Add a reentry message

  1. Expand System Question, then expand Optional, and click Reentry Message.
    Prop question answer node reentry message initial

  2. Click Add Reentry Message.
    A blank field appears.

  3. Enter the desired message—for example, What else can I do for you?
    Prop question answer node reentry message

The second time your application reaches this node, and every time after that during a session, it will use this question instead of the initial message.

Remove the reentry message

Click the Remove icon Icon trash in the upper-right corner of the Reentry area.
Prop question answer node reentry message remove

Define local recovery behaviors

You can define messages to be used when recognition events occur at this node, to supplement any collection default messages defined for your project or for specific channel profiles. When a recognition event happens at the collection phase for a question and answer node, recovery messages are issued in this order:

  1. Global pre-message (all channels), or a channel-specific override, if any
  2. Local message, if any
  3. The current node’s initial message, if enabled (for nomatch and noinput events only)

For example, when the first nomatch event happens at a question and answer node that collects a payment date, an application would issue: the global No Match 1 pre-message (for example, “Sorry.”), followed by the local No Match 1 message (“Say the date you'd like to post this payment, like October 5th. Or say Today.”), and finally repeat the node's initial message (“When would you like to make the payment?”).

  1. Expand System Question, then expand Optional, and click Recovery.
    Prop question answer node recovery blank
    By default, dialog applications use the initial message set for a node, after any applicable global or channel-specific recovery messages. If you haven’t modified your project settings, both related switches are turned on, in this node’s properties.
  2. If you do not want to use the initial message after the message set for a nomatch event, at this specific node, turn off Use Recovery Initial Message with each No Match.
  3. If you do not want to use the initial message after the message set for a noinput event, at this specific node, turn off Use Recovery Initial Message with each No Input.
  4. Add local recovery messages for recognition events, if desired.
    Note: The number of recovery messages the application will be allowed to use at runtime for nomatch or noinput events is limited to three, but ultimately depends on the collection settings for your project.

Define local confirmation behaviors

You can define messages to be used at the confirmation step for this node, to supplement any confirmation default messages defined for your project or for specific channel profiles. Note: Unlike the default recovery behavior for recognition events at the collection phase of a question and answer node, dialog applications do not repeat the confirmation initial message, after recovery messages for recognition events at the confirmation phase of question and answer nodes.

  1. Expand System Question, then expand Optional, and click Confirmation.
    Prop question answer node confirmation initial
  2. Add local confirmation messages—that is, the confirmation question, messages for recognition events at the confirmation step, and messages for acknowledging the answer (yes or no) to the confirmation question—, if desired.

Add messages for local behaviors

You can add local recovery messages for recognition events that happen at a question and answer node during collection or confirmation. For the confirmation step, you can also add the initial message—that is, the confirmation question—and messages for acknowledging the answer (yes or no) to the confirmation question.

You can add local recovery messages for these events: No Match 1, No Match 2, No Match 3, No Input 1, No Input 2, No Input 3, Max No Input, Max No Match, Max Turns

You can add local messages for these events at the confirmation step: Initial, No Match 1, No Match 2, No Match 3, No Input 1, No Input 2, No Input 3, Yes to confirm, No to confirm

Confirmation message Description
Initial To prompt the user for a confirmation—for example, I understood X is that correct? where X is the entity being collected
No Match 1, No Match 2, No Match 3 To prompt the user again in case of a nomatch event—for example Sorry, I didn't get that. Was it yes or no? (with appropriate variations for the second and third nomatch events)
No Input 1, No Input 2, No Input 3 To prompt the user again in case of a noinput event (with appropriate variations for the second and third noinput events)
Yes to confirm To acknowledge a yes answer to the confirmation question—for example, Awesome, got it!
No to confirm To apologize following a no answer to the confirmation question—for example, Sorry, my mistake…

The Recovery section and the Confirmation section of the properties for a question and answer nodes show applicable global messages and local overrides, if any.

To add a new local message:

  1. Choose the event for which you want to add a local message.
    Prop question answer node recovery choose event
  2. Click the Add icon Icon plus.
    If you’re adding a collection recovery message for a nomatch or noinput event, and Use Initial Message… is enabled, the initial message for this node appears, for reference.
    Prop question answer node recovery add message
  3. Click Add Message, and choose the desired format: Rich Text, TTS, or Audio Script.
    (Alternatively, choose an existing message from the list.)
  4. Enter the desired message.
    Prop question answer node recovery nm1
    In this scenario, the first time your application fails to recognize the user response at this node, it will use this special message before repeating the initial message.

User Input properties

Choose the type of information to collect

  1. Expand User Input and click Collect.
  2. Choose the type of information to collect (NLU intent or an entity).
    Prop question answer node user input choose yes no
    Tip: If your project does not yet have the entity you want to collect, you can create it on the fly.
  3. If this node is meant to collect a list entity whose values are all meant to be handled the same way, turn off all Show in Actions switches.
    Prop question answer node user input show in actions off
    Otherwise, if the list entity to collect requires value-specific behaviors, turn on the Show in Actions switches for the desired values.
  4. If this node is meant to collect a list entity for which the set of values can only be fully determined at runtime, click the Dynamic check box if it is not already selected (see Dynamic list entities for more information).
  5. If this node is meant to collect an entity that will hold sensitive information that must be masked in application logs, click the Sensitive check box if it is not already selected.
  6. Optionally, if this node is meant to collect an entity, choose a question router node to handle any captured entity or intent that is not the entity in focus at this point in the dialog flow.

Create an entity on the fly

When setting up a question and answer node, you can create an entity directly from the entity selector. This scenario shows how to add a relationship entity with an isA relationship to the dialog predefined entity YES_NO. See Manage entities for more information.

  1. Click the Add icon Icon plus next to Collect Entity.
    Prop question answer node user input add entity on the fly
  2. Type a name for the new entity (for example, myYES_NO), and press Enter.
    Note: The name must be unique across all intents, entities and variables in your project.
    The new entity becomes available.
    Prop question answer node user input yes no added
  3. Click the new entity.
    By default new entities appear as list entities, with fields you can use to add literal-value pairs.
    Prop question answer node user input yes no
  4. Choose the appropriate type from the list—in this case, Relationship.
    Prop question answer node user input yes no relationship
    New fields appear.
    Prop question answer node user input yes no relationship2
  5. Click the Add Relationship icon Icon plus next to isA, expand Predefined Entities, and choose YES_NO.
    Prop question answer node user input yes no relationship3
    The relationship is set.
    Prop question answer node user input yes no relationship set
  6. If this node is meant to collect a list entity for which the set of values can only be fully determined at runtime, click the Dynamic check box (see Dynamic list entities for more information).
  7. If this node is meant to collect an entity that will hold sensitive information that must be masked in application logs, click the Sensitive check box.

Specify grammars

Example of grammar settings, at a question and answer node—dynamic grammar reference (via a variable), for speech input; static grammar reference (filename) for DTMF input

Prop question answer node grammars settings

Mix supports GRXML grammars. The options available for a specific channel profile depend on the modalities it supports. Grammar files must be placed in specific directories, relative to the client application, that is basePath/language/, where basePath is the path to where the client application expects to find all required language-specific material (audio files and grammars), and language is a directory named after the appropriate language code (for example, en-US, fr-CA).

To specify a grammar reference:

  1. Expand User Input, then expand Optional, and click Grammars.
  2. If the grammar is for a specific channel profile, choose the desired profile.
    Prop question answer node grammars pick channel
  3. Turn on the switch for the grammar reference you want to specify.
  4. Expand the field, and:
    • Enter the name of the desired grammar file, including the extension (for example, mygrammar.grxml).
    • Choose the variable that is meant to hold a dynamic grammar reference at runtime.
      If the variable you want to use is missing, you can create it on the fly, and then use it immediately.

Set DTMF mappings

Setting DTMF mappings for entity values to be collected at question and answer nodes allows you to generate DTMF grammar specifications, to be used by a VoiceXML application. Use the Grammars tab of the NLU resource panel to export the DTMF grammar specification for your project.

To specify DTMF mappings:

  1. Expand User Input, then expand Optional, and click DTMF.
  2. If the entity for which you want to specify DTMF mappings has not yet been selected for collection at this node, use the list to select it.
    If the entity does not yet exist, you can create it on the fly.
  3. Choose the channel profile to which the DTMF mappings will apply, if it is not already selected.
    Only channel profiles that support DTMF are available for selection.
    Prop question answer node dtmf mapping
  4. If this node is collecting a list entity, you can quickly add entity values on the fly, directly in the DTMF tab, as needed.
  5. Turn on the switch next to a value you want to map to a DTMF key.
    Prop question answer node dtmf mapping start
  6. Choose the desired DTMF key for this entity value.
  7. Proceed in the same fashion until you have completed the mappings for all applicable channel profiles.
    Prop question answer node dtmf mapping done
  8. (Optional) Export the grammar specification document, to be used by a VoiceXML application, if desired.

Create an entity on the fly in the DTMF tab

When setting up a question and answer node, you can create the entity to collect directly in the DTMF tab.

  1. Expand the list, under What you are collecting from the user.
    Prop question answer node dtmf no entity
  2. Click the Add icon Icon plus next to Collect Entity.
  3. Type a name for the new entity (for example, CALL_DESTINATION), and press Enter.
    Note: The name must be unique across all intents, entities and variables in your project.
    Prop question answer node dtmf create entity
    The new entity is now selected for collection at this node.
    Prop question answer node dtmf new entity selected
  4. If this node is meant to collect a Boolean, or a yes/no entity, navigate to the Collect tab to set the required relationship.

Add entity values on the fly in the DTMF tab

  1. Type one or more comma-separated values, in the field under the entity name, and press Enter.
    Prop question answer node dtmf new entity values
    This creates the new values, and automatically maps them to DTMF keys.
    Prop question answer node dtmf new entity values mapped
  2. Turn off any mappings you wish to disable.

Define interactive elements

Question and answer node interactivity properties example

Prop question answer node interactivity yes no

In a project with channels that support interactive elements, question and answer nodes meant to collect Boolean, yes/no, or custom entities have Interactivity properties, to configure interactive elements such as buttons.

  1. Expand User Input, then expand Optional, and click Interactivity.
  2. (Optional) In the upper field enter the type of your interactive elements, such as Buttons, List, or Carousel, and the name of a class or inline CSS code to format them, if desired.
    Your dialog application will pass this information on to the client application.
    Note: Formatting of interactive elements is not yet supported. Any information in these two fields is ignored.
  3. Turn on the switches for the values for which you want to create interactive elements.
  4. For each interactive element, enter:
    1. A label, such as the text to show on a button—optional if a link is specified
    2. A link (URL or relative path) for the image to use on a button—optional if a label is specified
    3. A description—optional
  5. (Optional) Change the order of the elements, if needed.

System Actions properties

Set the system actions

System Actions properties example in a question and answer node collecting a list entity

Prop question answer node list entity actions

If this node is meant to collect an entity handled by a question router node, you must eventually set a transition back to the question router node. You can do it directly from the question and answer node, or from another node further downstream.

To transition back to the question router node that handles the entity in focus for this node:

  1. Expand System Actions and click View All.
  2. If the Default section doesn’t already contain a blank GoTo field, click Add Action and choose Add GoTo.
    A pair of fields appears.
  3. Expand the GoTo list, then expand Return to, and choose the question router node.

If this node is meant to collect a list entity that does not require any value-specific behavior, use the Default section to set the desired messages and actions. Messages and actions found in the Default section are executed in this order: first all messages, next all variable assignments, and last any throw event action or transition. If you want to both set a variable and use its new value in a message, add the assign actions to the Setup section.

If this node is meant to collect a Boolean entity, a yes/no entity, or a list entity that requires value-specific actions, the System Actions tab allows you to set messages and actions, separately, for each entity value. If desired, you can:

Advanced properties

Set local event handlers

  1. Expand Advanced and click Event Handling.
  2. Add and configure event handlers, if needed.
    Prop question answer node event handling tab
    On the canvas, the names of the events for which you add local handlers appear below the main transition for the question and answer node.
    Design question answer node event handler port

Set a question router reference

The question router reference field identifies the question router node that is to handle any captured entity or intent that is not the entity in focus for this question and answer node.

When you create a node directly from the question routing table of a question router node, or by dropping it from the design palette onto the corresponding area of the question router node on the canvas, the question router reference field automatically points to the originating question router node.

However, in some cases, you must set the question router reference manually:

A missing (or stale) reference will prevent intent switching.

Incidentally, in an intent component that includes question and answer nodes collecting entities that are not handled by the question router node, you can use the question router reference to allow intent switching at these nodes as well. For example, a question and answer node that prompts the user to confirm they really want to stop fulfilling the active intent and switch to another one does not automatically support intent switching itself. Setting the Question Router Reference field will allow the dialog flow to jump to the specified question router node whenever the captured value is not the yes/no answer expected at this question and answer node. The question router node will then handle the intent switching, assuming it is configured accordingly.

To set the reference:

  1. Expand Advanced and click Question Router.
    Prop question answer node advanced question router
  2. Click (Optional) Select a question router, and choose the desired question router node.
    Prop question answer node question router reference

Send data to the client application

  1. Expand Advanced and click Send Data.
  2. Click the Add icon Icon plus in the upper-right corner.
  3. Choose a variable or an entity you want to send to the client application.
    You can also send the active intent’s value, confidence score, and literal, or the interpretation results from the last collection and confirmation steps (see Predefined variables).
    Tip: Use the search field to narrow down the list if needed. If a variable you want to send is missing, you can create it on the fly, and then use it immediately.
  4. Proceed in the same fashion until you have added all the variables and entities you want to send to the client application.
    Prop question answer node send data

Override global settings

  1. Expand Advanced and click Settings.
  2. If the override must be limited to a specific channel profile, choose the desired channel profile.
    By default, node-level settings apply to all channel profiles.
  3. Expand the category for the settings you want to override.
    Prop question answer node settings maxturns
  4. Change the setting as required.
    Notice the description changed from italics to roman text, and the Reset icon appears.
    Prop question answer node settings maxturns override
    These changes indicate an override.
  5. Proceed in a similar fashion until you have configured all the required overrides.
    Detailed information appears in the Node properties pane, to help you understand the available settings.

Tip: Click the Reset icon Icon undo to remove an override.

Set up a message node

Message node properties example

Prop message node welcome

Use a message node to play or show a message, and perform actions that don’t require input from the user. Click a message node on the design canvas, to see its properties in the Node properties pane.

Set up a decision node

Decision node properties example

Use a decision node to perform actions that don’t involve messages and don’t require input from the user. For example, you can use a decision node in the intent component that handles dynamic list entities, to check whether you already have the required dynamic entity data for the current session and therefore don’t need to look it up again. You might also use a decision node after a data access node, to check whether information was actually returned (that is, not NULL) and whether some entities collected so far for the active intent need to be cleared and collected again—for example if you look up a product and the data access node returns a Boolean variable indicating this product is momentarily unavailable at the specified location, your design might allow the user to choose a different location, in which case you would clear the entity that represents the location and collect it again.

Click a decision node on the design canvas, to see its properties in the Node properties pane, then click Edit Conditions to expand the conditions table.

Set up a data access node

Data access node properties example

Prop data access node

Use data access nodes to exchange information with a backend system. For example:

Remember that the client application is often better suited than the dialog model to perform business logic, such as verifying whether the specified medication is actually listed in the user’s file and that the maximum number of refills hasn’t yet been reached.

Click a data access node on the design canvas, to see its properties in the Node properties pane.

Specify data to send to the backend

Under Send Data choose the variables and entities you want to send to the backend system, if any. Use the search field to narrow down the list if needed. If a variable you want to send is missing, you can create it on the fly, and then use it immediately. You can also send the active intent’s value, confidence score, and literal, or the interpretation results from the last collection and confirmation steps (see Predefined variables).

Specify data to get from the backend

Under Get Data choose the variables you want the backend system to return, if any. Use the search field to narrow down the list if needed. If a variable you want to get is missing, you can create one on the fly, and then use it immediately.

In addition to data you might get back from the backend system, two predefined variables are always returned to your dialog from the backend:

You do not need to specify these predefined variables in the Get Data section of your data access nodes. However, if you want to validate your data access node’s failure path in preview, add returnCode to the Get Data section, momentarily. This will allow you to enter a non-zero value when the data access node prompts for stub values, in the chat pane.

Create an input or return variable on the fly

In data access nodes (also in external actions nodes), when choosing data to exchange with an external system, you can create variables directly from the Send Data and Get Data selectors.

  1. Click the Add icon Icon plus next to Variables.
    Prop send create variable
  2. Enter a name for the new variable in the field that appears.
    Note: Variable names are limited to letters (A-Z, a-z), digits (0-9), the dollar sign ($) and the underscore. They must not start with a digit. The name must be unique across all intents, entities, and variables in your project.
    The new variable appears in the list, with an indication that its type is String.

You can now choose the new variable. Unless the variable is meant to be of type String (default), you must eventually use the Variables resource panel to complete its definition. See Manage variables.

Specify where to go with the returned data

  1. Set the GoTo transition to perform when the external system returns a success code.
    A success return code means that the dialog was able to communicate with the backend. It does not mean that the backend actually returned the desired data.
  2. Set the GoTo transition to perform when the external system returns a failure code.

Set up backend connection details

By default data access nodes support client-side integration—that is, data is to be exchanged between the dialog runtime service and the client application. In such a case, the client application itself is set up to access any required backend system and no further configuration is required for your data access node.

Otherwise, if your data access node must communicate directly with an external data host, turn off Enable client-side fetching, under Integration, and use the fields that appear to configure server-side integration.
Prop data access server side integration

Refer to Exchange data with an external system for more information on setting up server-side integration (as opposed to client-side integration).

See also: Configure default connection settings for information on creating connection profiles you can apply to multiple data access nodes.

Set up a question router node

Question router node properties example

Prop question router node get coffee details

Use a question router node to manage all entities required to fulfill an intent. The question router node specifies multiple pieces of information to be collected, and determines the next node in the dialog flow, based on the information collected so far. Depending on what the user already provided, when the dialog flows reaches a question router node, some information might already be available. In such cases, the corresponding slots are considered filled, and the question router node directs the dialog flow to the question and answer node that is meant to collect information for the next slot that has yet to be filled. When the dialog flow returns from a question and answer node, more slots might have been filled. Once all slots are filled, the question router node uses the transition under GoTo when questions are completed.

Click a question router node on the design canvas, to see its properties in the Node properties pane.

Replace the default node name, Question Router, with a unique name representing the questions to be fired from this node—for example, Get Order Details—and press Enter.

List the questions

Build a question routing table for your intent by specifying every piece of information to collect—that is, entities you have defined with your NLU intents—, in the desired sequence. For example:

  1. Under Route to questions, choose COFFEE_TYPE.
    A new row automatically appears.
  2. Choose COFFEE_SIZE on the next row.
    Prop question router route to question coffee app
    The application will prompt the user for the type of coffee, before any other information—such as the coffee size—required to fulfill the ORDER_COFFEE intent. This allows you to design your application so that it won’t unnecessarily prompt the user for the coffee size it the specified coffee type only comes in one size. See Set optional entity collection for more details.

Specify where to collect the answers

For each entity in your question routing table:

  1. Expand GoTo collect node.
  2. Expand Add new and choose Question & Answer.
    This connects the question router node to a new question and answer node named after the entity to collect.

Change the order of the questions

  1. Click the sort icon Icon sort in the upper right corner of the question routing table.
    Prop question router node entity sort before
    The table switches to sorting mode, with handles at the end of each row.
    Prop question router node entity sort handles
  2. Use the handles to move rows up or down until all entities are in the desired sequence.
  3. Click the close icon Icon close when you are done.

Set where to go with the answers

Under the question routing table, expand GoTo and choose a node on the canvas or add a new one. In the context of an intent component, you might:

Configure intent switching

In a component that has a question router node handling entity collection, you can choose to allow or prevent intent switching. For example, in a banking app, a user who wants to pay a bill and has started providing the required information might suddenly ask how much money they have in a specific account. By default intent switching is enabled, and when a user says something that is recognized as a different intent, at a question and answer node, the dialog flow uses the Intent Switching transition of the question router node that handles entity collection for the active intent, to eventually return to the upstream intent mapper. Any entities collected so far for the active intent persist, unless you add actions to clear them before switching.

Prop question router node switch intents

To prevent users from switching to another intent at this part of the dialog flow, turn off Switch Intents.

Depending on your purposes, additional actions might be required before letting the user switch to the other intent. For example:

Under Switch Intent Action, expand GoTo and set the desired transition:

Set optional entity collection

  1. Click Show Advanced Options.
  2. Enable Skip Input, under the entity for which you want to skip collection under certain conditions.
    Fields appear allowing you to define a condition.
    Prop question router node entity optional in process
  3. Set the condition that determines when the optional entity must be collected.
    For example, since ristretto only comes in one size, you don’t need to ask for the coffee size when the user orders a ristretto, which translates as collect COFFEE_SIZE only if the value of COFFEE_TYPE is not ristretto:
    Prop question router node entity optional condition
  4. Click Hide Advanced Options.

Set up an intent mapper node

Intent mapper node properties example

Intent mapper node

In a dialog flow, an intent mapper node generally follows a question and answer node set up to collect an NLU intent. Once the question and answer node has collected the user input and inferred an intent, the intent mapper node directs the dialog flow, based on the inferred intent, to a component or node that will handle the fulfilment of that intent. You can think of the intent mapper as a sort of intents switchboard or router.

The intent mapper node properties includes a table of mappings. For each intent, you can specify either a component or a node, to handle the intent. When you add an intent mapper node, it automatically inherits any global intent mappings from the NLU resource panel. The number of intents already mapped to a component (or node) appears on the intent mapper node on the canvas and is dynamically updated when you add or remove mappings. If you need to, you can override global intent mappings, and set local mappings for a specific intent mapper node.

Override a default intent mapping

  1. Click Map this intent, next to the name of the intent you want to map locally, at this intent mapper node level. (Click the name of the current component, if the intent was already mapped.)
  2. Choose either the dedicated intent component or an existing generic component, as required.
    Intent mapper override default

Tip: If your project does not yet have the generic component or node you want to use, you can create it on the fly.

Override multiple intent mappings at once

  1. Use the check boxes beside the intent names to select the intents whose mapping you want to override locally, at this intent mapper node level.
    Intent mapper select multiple
  2. Expand Map (n) to component, and choose an existing generic component or a node from the list.
    Intent mapper remap multiple
    Tip: If your project does not yet have the generic component or node you want to use, you can create it on the fly.
  3. Click Confirm to dismiss the message that prompts you to confirm your intention.
    This maps all selected intents to the specified component.

Restore the default mapping for an intent

For an intent that has a default mapping set in the NLU resource panel:

Click the More icon Icon ellipsis h for the intent and choose Reset to global mapping.

Intent mapper reset to default

Remove the local mapping for an intent

For an intent that does not have a default mapping set in the NLU resource panel:

Click the More icon Icon ellipsis h for the intent and choose Remove mapping.

Intent mapping remove

If an intent has been mapped to a component, it is easy to navigate directly to that component to further design it.

Click the More icon Icon ellipsis h for the intent and choose Go to component.

Intent mapping go to component

The desired component appears on the canvas.

Filter displayed mappings

If you have a project with a lot of intents, the table of mappings will get long. To make it easier to find the intent you are looking for, filtering capabilities are provided.

Intent mapper filter displayed intents

You can use the search field to do a keyword search. The intents list updates as you type, showing only the intents that match the search string.

You can also use Filter intent mappings, to alternate between:

Specify where to go upon return

The intent mapper node properties pane also allows you to specify where to go next if the dialog returns to the intent mapper from a mapped component (or node) after handling an intent. For example, after completing the customer's request, you might want the dialog to return to a previous question and answer node, triggering a reentry message asking the user if there is anything else they would like to do.

Expand the GoTo list, and set the desired transition.

Intent mapper goto on return

Set up an external actions node

External action nodes support actions to be performed when ending a conversation, transferring to another system, or escalating to a live agent, and allow exchanging information with external systems via a client application. Unlike a data access node, which communicates directly with an external system, an external actions node does not require connection settings.

Click an external actions node on the design canvas, to see its properties in the Node properties pane.

Choose the desired action: End, or Transfer.

End actions

  1. Replace the default name, External Action, with a unique name—for example, End.
    Prop external actions node end
  2. Choose the variables and entities you want the client application to send to an external system, if needed. You can also send the active intent’s value, confidence score, and literal, or the interpretation results from the last collection and confirmation steps (see Predefined variables).

Transfer actions

  1. Replace the default name, External Action, with a unique name—for example, Transfer.
    Prop external actions node transfer
  2. If needed, choose information you want the client application to exchange with an external system:
    • Variables and entities you want the client application to send to the external system. You can also send the active intent’s value, confidence score, and literal, or the interpretation results from the last collection and confirmation steps (see Predefined variables).
    • Variables to be returned.
  3. Set the GoTo transition to perform when the external system returns a success code.
    A success return code means that the user was successfully transferred, in which the dialog typically ends after performing any required end-of-dialog business logic.
  4. Set the GoTo transition to perform when the external system returns a failure code.
    A failure return code means that the user could not be transferred, in which case you might need to ask them what they would like to do next—for example try again, or abandon what they were trying to do and end the dialog.

Tips: Use the search fields to narrow down the lists of variables and entities, if needed, when choosing the information to exchange. If a variable you want to use is missing, you can create it on the fly, and then use it immediately.

Set up a component call node

Component call node properties example

Prop component call node

A component call node provides a means to allow the dialog flow to enter another component—for example, a component that performs authentication, disambiguation, or operations that are required after a user is transferred to a live agent.

The component call node transfers the dialog flow to the specified component. When the component is finished, the dialog returns to the component call node and proceeds from there.

Click a component call node on the design canvas, to see its properties in the Node properties pane.

Add a component call node

  1. Click Components on the design palette and drag the component you want this node to invoke, onto the canvas (or directly onto a transition area of a node).
    By default the name of a new component call node has this format: the word Call, followed by the name of the destination component—for example, Call TRANSFER_MONEY. You can rename the node as desired.
  2. Expand the GoTo list and set the desired transition.
    This determines where the dialog will go after it returns from the destination component of this node.

Change the destination component

The destination of a component call node is automatically set upon adding the node. Choose a different destination from the Set Component list, if needed, in which case you might want to rename the component call node accordingly.

Go to the destination component

Click Go to Component.

This brings the destination component into focus.

Set messages and actions

At every node in a dialog, messages and actions (such as transitions, assignments, an so on) are performed. Messages and actions can be conditional. When you set messages or actions for a node, you can use existing resources or, in some cases, create new resources on the fly. For example, when you add a message to a message node, you can use an existing message or create a new one. Likewise, when you add an assign action, you can use an existing variable, or create a new one.

Item Description
Message In Mix.dialog, message nodes use messages that do not require the user to respond, while question and answer nodes use messages meant to engage the user by asking questions to collect required information. While the Messages resource panel allows you to manage all messages for your project, you can create messages directly from the nodes at which they are meant to be used. You can also create default global messages from the Project Settings panel.
Assign Question and answer nodes, message nodes, and decision nodes support assigning values to variables and entity attributes, with our without a condition. You can also initialize variables in Start and Enter nodes. The set of variables, entities, operators and methods available on the right-hand side of an assign action depends on the type of the variable or entity on the left-hand side.
Transition A transition identifies the next node to execute after completing an action. Choose the appropriate transition type based on where the target node is located and the purpose of the transition.
Throw event Use throw event actions, in question and answer nodes, message nodes, or decision nodes, to throw custom events. It is also possible use a throw action to throw a global command event, if you want to handle a situation the same way as the corresponding global command—for example, if you want to transfer the user to a live agent to handle some error situations where a maximum threshold is reached, you can set a throw event action to throw the Escalate event.
Condition Use conditions to determine the next message or action, based on logical expressions.

Set messages

When configuring message nodes and question and answer nodes, you can add one or more messages, directly in the Node properties pane.

The Project Settings panel allows you to create default global messages that your application will use whenever a recognition event (such as a failure to collect or recognize what the user said) occurs. The question and answer nodes support recovery messages to override global behaviors locally, at the node level.

When you add a message, Mix.dialog automatically gives it a normalized name, based on the text of the message—for example, if you enter How may I help you? the name of the message is automatically set to how_may_i_help_you_. Messages created from the Project Settings panel have names starting with global_ (for example, global_sorry_i_didn't_get_that_). You can rename messages, if desired.

To support language-specific messages, choose the desired language from the menu near the name of the project.

You can define separate channel-specific message variations. You can also add message variations in up to three different formats—rich text, TTS, audio script—depending on the channel. Messages defined for the default channel apply to all channels unless a channel-specific variation exists. Messages defined for a non-default channel—and their format-specific variations—are only used in that channel.

You can use HTML code in text messages, SSML tags in TTS messages, or CPR parameters in audio script messages.

Dynamic messages

You can create a dynamic message by adding annotations that represent variables, entities, or the active intent’s value, literal or confidence score, to be inserted in the message at runtime.

Annotations that represent variables or entities of certain types (date, time, temperature, and so on) support output formatting.

In dialog designs that support the Audio Script modality, messages can also include dynamic audio file references.

Annotation colors and naming conventions

Message annotations have distinctive background colors:

Color Annotation type
Blue Variable
Sea blue Entity value
Sea blue with quotes Entity literal
Green Active intent value or confidence score
Green with quotes Active intent literal

Output formatting options

The formatting options available for variables and entities used in dynamic messages depend on the data type, message format, and current language.

Annotations that represent variables or entities of these types support output formatting:

Variable types Entity types (isA relationship) Options by modality
Alphanumeric Rich Text, TTS, Audio Script
Amount nuance_AMOUNT Rich Text, TTS, Audio Script
Date DATE, nuance_EXPIRY_DATE Rich Text, TTS, Audio Script
Decimal nuance_DOUBLE, nuance_NUMBER Rich Text, TTS, Audio Script
Digits nuance_CARDINAL_NUMBER Rich Text, TTS, Audio Script
Distance nuance_DISTANCE Rich Text, TTS, Audio Script
Integer Rich Text, Audio Script
Temperature nuance_TEMPERATURE Rich Text, TTS, Audio Script
Time TIME Rich Text, TTS, Audio Script

For these data types, when you add an annotation, among various supported methods (or entity attritutes), you can choose Formatted value. It is possible to customize the formatting for annotations that represent a formatted value, or to add formatting for an annotation that represents an unformatted value (see Configure output formatting for an annotation).

Text output formatting
Alphanumeric display

Set a pattern to show groups of characters of specified length with delimiters. The default format is 123-12-12345, that is: 3 characters, hyphen, 2 characters, hyphen, 5 characters.

Turn on Advanced, to use the advanced format editor, if desired.

Amount display
Parameter Description
Currency For display purposes only: choose any currency to show on the annotation. At runtime (and in preview) the currency is part of the value.
Thousands separator Turn on (default) to show the value with the applicable thousands separator; turn off to show the value without thousands separator.
Date display
Parameter Description
Order Choose between Month/Day/Year (default), Day/Month/Year, or Year/Month/Day.
Day of Week Choose between the long form (Monday), the short form (Mon), or choose None (default) to omit the day of the week.
Day Format Choose between the long form with leading zero (default), the short form without leading zero, or choose None to omit the day.
Month Format Choose between the long form with leading zero (default), the short form without leading zero, the long month name (July), the short month name (Jul), or choose None to omit the month.
Year Format Choose between the long form with four digits (default), the short form with two digits, or choose None to omit the year.
Delimiter Choose between -, / (default), ., a space, or no delimiter.

Use the advanced date format editor, if desired. When you switch to the advanced editor, the pattern reflects the current format—for example, MM/dd/yyyy for the default format. The pattern string must comply with the SimpleDateFormat Java class. To go back to the basic date format editor, clear the pattern string, and then turn off Advanced.

Decimal display
Parameter Description
Decimal places Choose the number of decimal places to show (0–7). Default: 2.
Thousands separator Turn on (default) to show the value with the applicable thousands separator; turn off to show the value without thousands separator.
Digits display

Set a pattern to show groups of characters of specified length with delimiters. The default format is 123-12-12345, that is: 3 characters, hyphen, 2 characters, hyphen, 5 characters.

Turn on Advanced, to use the advanced format editor, if desired.

Distance display
Parameter Description
Decimal places Choose the number of decimal places to show (0–7). Default: 2.
Thousands separator Turn on (default) to show the value with the applicable thousands separator; turn off to show the value without thousands separator.
Integer display

Choose whether to show the value with the applicable thousands separator (default), or to show the value without thousands separator.

Temperature display
Parameter Description
Decimal places Choose the number of decimal places to show (0–7). Default: 2.
Thousands separator Turn on (default) to show the value with the applicable thousands separator; turn off to show the value without thousands separator.
Time display

Choose the hour format: 12-hour clock (default), or 24-hour clock.

Use the advanced date format editor, if desired. When you switch to the advanced editor, the pattern reflects the current format—for example, h:mm a for the default format. The pattern string must comply with the SimpleDateFormat Java class. To go back to the basic time format editor, clear the pattern string, and then turn off Advanced.

TTS for playback
Alphanumeric TTS playback

Set a pattern to show groups of characters of specified length. The default format is 123 12 1234, that is: 3 characters, pause, 2 characters, pause, 4 characters.

Turn on Advanced, to use the advanced format editor, if desired.

Amount TTS playback
Parameter Description
Currency For display purposes only: choose any currency to show on the annotation. At runtime (and in preview) the currency is part of the value.
Play zero cents Turn on (default) to play “zero cents” (in the session language), when the number of cents (or sub-unit for the specified currency) is zero.
Date TTS playback
Parameter Description
Order Choose between Month/Day/Year (default), Day/Month/Year, or Year/Month/Day.
Day of week Turn on to play the day of the week (for example, “Sunday”); otherwise, turn off (default).
Day Turn on to play the day of the month (default).
Month Turn on to play the month (default).
Year Turn on to play the year (default).
Decimal TTS playback
Parameter Description
Decimal places Choose the number of decimal places to show (0–7). Default: 2.
Play zero decimals Turn on (default) to play “point zero” (in the session language), when the value after the decimal point (or comma) is zero.
Digits TTS playback

Set a pattern to show groups of characters of specified length. The default format is 123 12 1234, that is: 3 characters, pause, 2 characters, pause, 4 characters.

Turn on Advanced, to use the advanced format editor, if desired.

Distance TTS playback

Choose the number of decimal places to play (0–7). Default: 2.

Integer TTS playback

No formatting options for integer values in TTS messages.

Temperature TTS playback

Choose the number of decimal places to play (0–7). Default: 2.

Time TTS playback

Choose the hour format: 12-hour clock (default), or 24-hour clock.

Audio Script for CPR playback
Alphanumeric CPR playback

Set a pattern to play groups of characters of specified length. The default format is 123 12 1234, that is: 3 characters, pause, 2 characters, pause, 4 characters.

Choose the appropriate intonation, based on the position of the annotation in the message: Medial (default), or Final.

Turn on Advanced, to use the advanced format editor, if desired.

Amount CPR playback
Parameter Description
Currency For display purposes only: choose any currency to show on the annotation. At runtime (and in preview) the currency is part of the value. Note: CPR supports only one currency per language. The available currency for a language depends on the CPR package that was set up for that language in your Mix environment. At runtime, amounts in a currency that the CPR package for the session language doesn’t support are played as dollars.
Intonation Choose the appropriate intonation, based on the position of the annotation in the message: Medial (default), or Final.
Case Available for German only: Choose the appropriate case, based on the grammatical function of the annotation in the message: Nominative (default), or Dative.
Play zero dollars Turn on (default) to play “zero dollars” (in the session language), when the number of dollars (or selected currency) is zero.
Play zero cents Turn on (default) to play “zero cents” (in the session language), when the number of cents (or sub-unit for the selected currency) is zero.
Play pre-hundred Available for English (United States) only: Turn on to use different audio recordings for hundreds prior to millions/thousands, and for hundreds prior to tens; turn off (default) to use the same audio recording for hundreds regardless of their position in amounts.
Date CPR playback
Parameter Description
Day of week Turn on to play the day of the week (for example, “Sunday”); otherwise, turn off (default).
Day Turn on to play the day of the month (default).
Month CPR playback always includes the month.
Year Turn on to play the year (default).
Intonation Choose the appropriate intonation, based on the position of the annotation in the message: Medial (default), or Final.
Case Available for German only: Choose the appropriate case, based on the grammatical function of the annotation in the message: Nominative (default), or Dative.
Decimal CPR playback
Parameter Description
Intonation Choose the appropriate intonation, based on the position of the annotation in the message: Medial (default), or Final.
Case Available for German only: Choose the appropriate case, based on the grammatical function of the annotation in the message: Nominative (default), or Dative.
Play zero units Turn on (default) to play “zero point” (in the session language), when the value before the decimal point (or comma) is zero.
Play zero decimals Turn on (default) to play “point zero” (in the session language), when the value after the decimal point (or comma) is zero.
Digits CPR playback

Set a pattern to play groups of characters of specified length. The default format is 123 12 1234, that is: 3 characters, pause, 2 characters, pause, 4 characters.

Choose the appropriate intonation, based on the position of the annotation in the message: Medial (default), or Final.

Turn on Advanced, to use the advanced format editor, if desired.

Distance CPR playback

Choose the number of decimal places to play (0–7). Default: 2.

Integer CPR playback

Choose the appropriate intonation, based on the position of the annotation in the message: Medial (default), or Final.

Temperature CPR playback

Choose the number of decimal places to play (0–7). Default: 2.

Time CPR playback
Parameter Description
Hour Format Choose between a 12-hour clock (default), or a 24-hour clock.
Intonation Choose the appropriate intonation, based on the position of the annotation in the message: Medial (default), or Final.

Add a message

When you create a message node it already has one blank field where to set a message. Likewise, a new question and answer node has one blank field for setting the system question. The steps you must perform for adding more messages depend on where you want to add them.

Add a message above or between existing messages or actions

  1. Bring your pointer to the area above the appropriate row.
    A link appears allowing you to add a new row.
    Prop add row
  2. Click +Add Row, and then click +Message.
    Prop add row+message
    A blank field appears, allowing you to define a message.

Add a message below all existing messages and actions

  1. Click the Add action icon Icon plus, and then click Add Message.
    Prop add message after all other items
  2. Choose the desired message format.
    Alternatively, choose an existing message.
    Prop add message choose format or existing

Use an existing message

  1. Click New Message (above a blank message field), or the message ID (if there is already a message in the field).
    A list appears showing all messages in your project.
    Use the Search box to narrow down the list, if desired. Only messages whose text or name contains the search string remain in the list.
    Prop add message existing filtered list
  2. Choose the desired message from the list.
    The message appears in the field.

Duplicate a message

  1. Click the Copy icon Icon copy below the message.
    Prop message existing
    A copy of the original message appears, with a distinct message ID (a numeric suffix is appended to the original message ID).
    Prop message duplicated
  2. Modify the new message as desired.
    Prop message duplicated and edited

Open the Messages panel from a message

Click the Library icon Icon library below the message.
The Messages resource panel opens, and your message is in focus. See Manage messages, for more information.

Remove a message

Click the Remove icon Icon trash below the message.
This removes the message from the current context (node properties, or project settings). The original message remains in your project.

Add a format-specific version for a message

  1. Click the Add format icon Icon plus.
    Prop message add format
  2. Choose the desired format.
    Prop message format choose
    A new blank field appears.
    Prop message tts blank
  3. Enter the text you want to use when the message must be in the specified format.

Remove a format-specific message

Clear the field where the format-specific version appears.
This removes the field.

Add a dynamic message

As you type any message, you can specify placeholders (annotations) to be replaced at runtime according to what the user said or according to what happened during the interaction. Make sure your design includes actions to initialize the variables or to collect the entities or the intent you specified.

  1. Start typing your message.
  2. When you reach the point where you want to insert a placeholder for a variable or entity:
    1. Type a left square bracket ([).
      A menu appears.
      Message annotate start
    2. Expand the appropriate category: Variables, if you want insert the placeholder for a variable; Entities, for an entity; or Intent, for the active intent.
      Message annotate menu entity
    3. Choose the variable or entity you want to use, or an attribute of the active intent.
      Depending on the type of element, you might have to choose between different attributes, such as the element’s value or literal, its length, and so on (see Supported methods). For variables that support output formatting, you can choose Formatted value (and then customize the format, if desired).
    4. The name of the dynamic element you chose appears as highlighted text in your message.
      Message annotate entity added
  3. Complete your message.
    Message annotate complete

Annotate a message

You can annotate an existing message to add dynamic placeholders for variables, entities, or attributes of the active intent.

  1. Highlight the part of your message you want to replace with a dynamic placeholder.
    A menu appears.
  2. Expand the appropriate category and choose the variable or entity you want to use.
    Depending on the type of element, you might have to choose between different attributes, such as the element’s value or literal, its length, and so on (see Supported methods). For variables that support output formatting, you can choose Formatted value (and then customize the format, if desired).
    Message annotate existing complete
    The highlighted text now represents the specified entity or variable. You can edit the display text, if desired.

Change the variable or entity for an annotation

This can be useful, for example, after you have duplicated a dynamic message and the copy should use a different variable.

  1. Click the annotation you want to modify, and choose Edit value.
    Message annotate edit value
    A menu appears.
  2. Expand the appropriate category and choose the variable or entity you want to use.
    Depending on the type of element, you might have to choose between different attributes, such as the element’s value or literal, its length, and so on (see Supported methods). For variables that support output formatting, you can choose Formatted value (and then customize the format, if desired).
    The highlighted text now represents the specified entity or variable. You can edit the display text, if desired.

Edit the text of an annotation

This can be useful, for example, after you have renamed a variable or entity that was used in an existing dynamic message.

Click the annotation you want to modify, choose Edit display text, and modify the text as desired.

This only changes the text on the annotation, not the entity or variable that the annotation represents.

Remove an annotation in a message

Click the annotation you want to undo, and choose Remove tag.

Message annotate remove tag

Only static text from the former annotation remains.

Message annotate remove tag done

Configure output formatting for an annotation

  1. Click the annotation for which you want to specify output formatting.
  2. If the annotation represents the formatted value of a variable or entity, choose Edit formatting; otherwise, choose Add formatting.
    Message annotate add formatting
    A format editor with applicable formatting options (for the data type, active language, and message format) appears.
  3. Use the formatting options.
  4. When the sample value matches the desired format, click outside the editor to close it.
    The formatted sample value text appears on the annotation, next to the display text.
    Message annotate formatted sample

Remove output formatting for an annotation

Click the annotation for which you want to restore the unformatted output behavior, and choose Remove formatting.

Message annotate remove formatting

The annotation no longer shows a formatted value sample; only the display text remain.

Message annotate remove formatting done

Set a format pattern for alphanumeric values or digits

By default, the format editor for alphanumeric values or digits contains a default pattern, showing groups, such as 123-12-12345. Each group can have up to 9 characters. The Rich Text format supports a leading character and delimiters between groups. For TTS and CPR playback, the space between groups represents a pause.

Message format editor digits initial

Remove a group

Click the Remove group icon Icon close of the group you want to remove.

Message format editor group remove

Add the first group

  1. (Rich Text only) Choose the initial character.
  2. Choose the number of characters for the group.
  3. Click the Add icon Icon plus.

Insert a group

  1. Click the blank area to the right of the group after which you want the new group to appear.
  2. (Rich Text only) Choose the desired delimiter from the Break list.
  3. Choose the number of characters you want to add.
  4. Click the Add icon Icon plus.

Increase the length of a group (Rich Text only)

  1. Click the blank area to the right of the group you want to modify.
  2. Choose None from the Break list.
  3. Choose the number of characters you want to add.
  4. Click the Add icon Icon plus.

Use the advanced format editor for alphanumeric values or digits

When you switch to the advanced editor, the pattern string reflects the current format—for example, ###-##-##### for Rich Text, or 3 2 4 for TTS and Audio Script.

Message format editor alphanum advanced initial

For Rich Text, the pattern string can only include # to represent any letters or digits (only digits, for values of type Digits). The characters -, ., /, \, (, ), +, *, and space are the only supported delimiters.

For TTS and Audio Script, the pattern string can only include digits between 1 and 9, to represent groups of characters (and spaces between the digits, if desired). For example, 3 2 4 represents a group of three characters, pause, two characters, pause, four characters.

To go back to the basic format editor, clear the pattern string, and then turn off Advanced.

Set assign actions

Use assign actions to set the value of variables or entity attributes—for example:

Some elements have a distinctive background color, when they appear on the right-hand side of an assign action:

Color Element type
Blue Variable
Sea blue Entity value
Sea blue with quotes Entity literal
Green Active intent value, literal, or confidence score
Pink Method
Magenta NULL

Add an assign action

The steps you must perform for adding an assign action depend on where you want to add it.

Add an assign action above or between existing messages or actions

  1. Bring your pointer to the area above the appropriate row.
    A link appears allowing you to add a new row.
    Prop add row
  2. Click +Add Row, and then click +Set.
    Prop add row+set
    Blank fields appear, allowing you to define the action.
    Prop assign variable initial

Add an assign action below all existing messages and actions

  1. Click the Add action icon Icon plus, and then click Add Action.
    Prop add message after all other items
  2. Choose Set Variable.
    Prop add set action after all other items
    Blank fields appear.
    Prop assign variable initial

Assign a value to a variable or entity attribute

  1. Choose the desired variable from the Set list.
    Prop assign variable lhs
    Tips:
    Use the search field to narrow down the list if needed.
    Click a complex variable to see its fields.
    Prop assign complex variable Click an entity to see its attributes.
    Prop assign entity attribute
    Tip: If the variable you want to use is missing, you can create it on the fly, and then use it immediately.
    A second field appears.
    Prop assign variable rhs blank
  2. Depending on the variable’s type, enter a value, an expression, or choose another variable or an entity.
    Prop assign variable rhs set

Clear an entity

Clearing an entity allows you to use it again during the same dialog session. For example, your dialog might include multiple question and answer nodes that collect a yes/no entity, or might allow the user to stop providing information to fulfill the active intent and start over afresh. Clearing an entity sets its .value and .literal attributes to NULL, .isRequired to true, .isConfirmed and .isCompleted to false.

  1. Navigate to the entity you want to clear.
    Prop assign entity clear yesno
  2. Choose .clear().
    Prop assign entity clear

Clear a complex variable

Assign NULL to a variable when you don't need it anymore. For example, your dialog might use a complex variable to hold a customer’s first name, last name, and a list of bank accounts, for a fund transfer intent. Once the fund transfer is completed, setting the complex variable to NULL allows you to use it again for another transaction during the same dialog session. This is similar to clearing an entity.

  1. Choose the complex variable you want to clear (use the top-level object).
    Prop assign complex variable obj
    The complex variable object appears in the Set field, followed by a blank field.
    Prop assign complex variable obj blank field for rhs operand
  2. Expand the To list.
    Prop assign complex variable rhs null
  3. Choose NULL.
    Prop assign complex variable rhs null set

Use a mathematical expression

A variable of type integer can be set to the value of an arithmetic operation (addition, subtraction, multiplication, division, or percentage). Mix.dialog supports simple mathematical expressions involving:

This example shows how to increment a variable to use it as a counter. (It assumes your design includes actions to initialize this variable, and reset it if needed.)

  1. Choose the variable you want to set—for example, count, an integer.
    Prop assign var integer lhs
  2. Click the Add icon Icon plus and choose the same variable.
    Prop assign var integer expression lhs
  3. Click the Add icon Icon plus again, and choose the desired operator—in this case, the + sign.
    Prop assign var integer expression oper
  4. Enter the number by which you want to increment the counter.
    Prop assign var integer expression rhs constant

Use a random number

A variable of type integer can be set to a random value between 1 and a number you specify. In this example, a variable is assigned a random integer value between 1 and 6. Once you have set a variable to a random value you can use it in conditions, for example to play a random greeting message when your application starts, or to perform a random transition.

  1. Choose the variable you want to set—for example, lotto, an integer.
    Prop assign var random lhs
  2. Click the Add icon Icon plus and choose Integer.random(…) under Helper Functions.
    Prop assign var random helper function
  3. Enter the desired number in the bottom field.
    Prop assign var random rhs

Switch intent manually

To initiate intent switching programmatically, you can use an assign action to modify the predefined variable Active Intent Value.

Intent switching requires Active Intent Value to be set before the dialog flow reaches the intent mapper node that will perform the switch.

If you set Active Intent Value downstream from the intent mapper node, the type of transition to apply depends on whether the intent mapper node is in the same component as the assign action, or in another component; and on whether a question router node is present in the component where the assign action takes place:

To set Active Intent Value:

  1. Expand the Set list and choose Active Intent Value.
    Prop assign var active intent
    A second field appears.
  2. Expand the To field.
    Prop assign var active intent to
  3. Choose the desired intent.
    Prop assign var active intent set
    Alternatively, use the Add icon and choose the desired variable.
    Prop assign var active intent set to other var

Create a variable on the fly

When adding a set variable action, you can create a variable directly from the selector.

  1. Click the Add icon Icon plus next to Variables.
    Prop assign create variable
  2. Enter a name for the new variable in the field that appears.
    Note: Variable names are limited to letters (A-Z, a-z), digits (0-9), the dollar sign ($) and the underscore. They must not start with a digit. The name must be unique across all intents, entities, and variables in your project.
    Prop assign create variable add name
    The new variable appears in the list, with an indication that its type is undefined.
    Prop assign create variable undefined

Unless the variable is of type String (default), you must eventually use the Variables resource panel to complete its definition, before you can set the value. See Manage variables.

Delete an assign action

Click the More icon Icon ellipsis h for the action you want to remove, and choose Delete.
Prop assign variable menu expanded

Set transitions

A transition identifies the next node to execute after completing an action. Distinctive elements represent transitions between nodes on the canvas. Mix.dialog supports these transition types:

Transition type Appearance Description
GoTo Arrow between two nodes on the canvas. Color-coded by channel. Gray (default) represents a transition that applies to all channels. Other colors represent channel-specific transitions. Transitions to another node within the same dialog component.
Return To Icon transition return to Returns any collected entity information back to a question router node.
Return Icon transition return Returns to the intent mapper node or component call node that called the current component from another component. Not available in the component called Main.
Return to Intent Mapper Icon transition return to intent mapper Returns to the upstream intent mapper node when a user says something that is recognized as an intent, while entities are being collected to fulfill a different intent. Requires intent switching to be enabled, in the question router node that handles the entities for the active intent.

Setting up a question router node determines transitions to other nodes from which the dialog flow should eventually return—via a Return To transition—after having collected information for entities handled by the question router node.

Setting up an intent mapper node determines transitions to other nodes or to other components that handle the intents in your project. When a separate component handles an intent the dialog flow must eventually return to the intent mapper via a Return transition.

Similarly, if your design uses component call nodes to transition to separate components that handle specific parts of the dialog flow, such a component should eventually use a Return transition to go back to the node from where it was called.

Set throw event actions

Use throw event actions, in question and answer nodes, message nodes, or decision nodes, to throw custom events.

Add a throw event action

The steps you must perform for adding a throw event action depend on where you want to add it.

Throw an event above or between existing messages or actions

  1. Bring your pointer to the area above the appropriate row.
    A link appears allowing you to add a new row.
    Prop add row
  2. Click +Add Row, and then click +Event.
    Prop add row+event
    Blank fields appear, allowing you to define the action.

Throw an event below all existing messages and actions

  1. Click the Add action icon Icon plus, and then click Add Action.
    Prop add message after all other items
  2. Choose Throw Event.
    Prop add throw action after all other items
    Blank fields appear.
    Prop add throw blank
  3. Choose the event you want to throw.
    Prop throw event choose
    Tip: If your project does not yet have the event you want to throw, you can create it on the fly.
  4. (Optional) Type a description or text to be logged when the event is thrown.

Delete a throw event action

Click the More icon Icon ellipsis h for the action you want to remove, and choose Delete.
Prop throw event menu expanded

Set conditions

Use conditions to determine the next action based on logical expressions. For example:

You can define conditions in these context:

Show the condition table

Click Edit Conditions.
The Node properties pane expands, revealing the condition table.

Hide the condition table

Click Done Editing.
The Node properties pane reverts to its default state, showing only the actions.

Define a simple condition

  1. On the first row of a condition table expand the first list (Always) and choose If.
    A set of fields appears, allowing you to build an expression.
    Condition if statement blank
  2. Choose an element (such as a variable or entity) from the second list.
    Condition if statement lhs
  3. Replace the default operator (is equal to) with another one from the third list, if needed.
  4. Choose the desired element from the fourth list (such as a variable, an entity, or NULL), or enter a static value.
    Condition if statement rhs
  5. Set the action to perform under this condition: assign a variable, play a message, or transition to another node.

Add a row at the bottom of a condition table

Use the desired button: Add Message, or Add Action.
Condition table bottom row actions

In some cases, depending on the node type and context, only one of these buttons is available. For example, in the System Question tab of a question and answer node, it is only possible to add messages.

Add a row at the top or between rows of a condition table

  1. Bring your pointer to the area above the appropriate row. A link appears allowing you to add a new row.
    Prop cond add row
  2. Click +Add Row, and then click +Message, +Set, +GoTo, or +Event, depending on what you want the new row to handle.
    Prop cond add row message
    A new row appears, with a default condition of Always and the required blank fields to define the desired message or action.

Remove a row in the condition table

  1. Click the delete icon Icon trash on the row you want to remove.
    A message appears prompting you to confirm your intention.
  2. Click Confirm.

Add a message or an action in a condition row

  1. Click the Add action icon Icon plus below an action item to add a message or another action to perform under this same condition.
    Condition if statement message add other
  2. Use the desired button: Add Message, or Add Action.
    Condition if statement message add other choose
    For example, click Add Action and choose Add GoTo.
    The required blank fields to define the desired message or action appear.
    Condition if statement message add goto

Remove a message in a condition row

Click the Remove icon Icon trash below the message.

Remove an action in a condition row

Click the More icon Icon ellipsis h for the action you want to remove, and choose Delete.

Manage resources

All resources in a dialog project have a global scope, which means you can use them anywhere in your dialog design. A dialog flow involves these resource types:

Resource Description
Intent An intent is what a user is trying to accomplish—for example, booking a flight, or checking the current status of a flight.
Entity Entities are details the user might need to provide to fulfill an intent. For example, in the scenario where a user wants to book a flight, the origin, the destination, the departure time, and the arrival time are entities.
Grammar If your Mix project is meant to support a VoiceXML application, you can export a grammar specification document to help design and manage grammars that will be referenced by the application.
Variable Variables are named objects that store values to be used in the applications you build from your dialog project.
Message Messages allow your application to respond to what a user says, in the most specific and relevant way to help them accomplish what they want to do. In Mix.dialog, a message can have format-specific and channel-specific variants. The available message formats—Rich Text (default), TTS, or Audio Script—depend on the modalities that the active channel profile supports. Channels and the modalities they support are determined when you create a project.
Event An event interrupts the current call flow, and passes flow control to an event handler. Events are available for throw actions you can set in most node types, and for event handlers you can set at the project level, at a component level, or in a question and answer node. Configure global event handlers in the Start node for your project, component-level event handlers in the Enter node of a component, node-level handler in the Event Handling tab of a question and answer node.

Manage intents

NLU resource panel, Intents tab example

Panel nlu intents

In Mix.dialog you can use the NLU resource panel to manage intents and entities. Any changes you make to intents or entities in Mix.dialog become available in Mix.nlu, and vice versa. Use Mix.nlu to link entities to intents, by adding samples and annotating them. Associating each intent with a variety of representative utterances allows your application to be able to recognize what the user said in their own words. Refer to the Mix.nlu documentation for more information.

Open the NLU resource panel

Click NLU, on the Mix.dialog toolbar, to open the NLU resource panel.

(Click NLU again to close the panel.)

Add an intent

  1. Click +Add Intent.
  2. Type a unique name for the intent—for example, ORDER_COFFEE—and press Enter.
    Note: Intent names must not start with a number and cannot include spaces. Use underscores as separators if desired. The name must be unique across all intents, entities and variables in your project.

Delete an intent

  1. In the Intents list, click the checkbox next to the intent name.
    A toolbar appears above the intents table.
  2. Click Delete Intent.
    A message appears prompting you to confirm your intention.
  3. Click Delete Intent(s).

Add an intent component

An intent component is a special type of component meant to handle one specific intent.

To create the intent component for an intent:

  1. Click Map this intent, next to the intent name.
    (Click the name of the current component, if the intent was already mapped.)
  2. Click +Create Intent Component.
    Panel nlu intents add intent component
    This creates the intent component and maps it to the intent. This new intent component appears in the Intent Components section of the Components pane.
    Design intent component added from nlu panel
    It is possible to override the default mappings, in individual intent mapper nodes.

Add a generic component on the fly

  1. Click Map this intent, next to the name of the intent you want to map to a new reusable component
    (Click the name of the current component, if the intent was already mapped.)
  2. Click the Add icon Icon plus, next to Existing Component.
  3. Enter a name for the new component.
    The new generic component becomes available for mapping. It also appears in the Components section of the Components pane.

Set global mappings for intents

Intents can be mapped to components, to route the dialog based on the intent. When an intent is detected by the NLU model, the flow of the dialog can transfer to that component.

For most intents, you will probably want to have the intent handled consistently by the same component wherever the intent is detected in the dialog. In the Intents tab of the NLU resource panel, you can set global default mappings for intents.

Default mappings set in the NLU resource panel are inherited by intent mapper nodes but can be overridden if needed within the intent mapper node.

One-to-one vs many-to-one mappings

Mappings from intent to component can be of two types:

The types of mappings possible depend on the type of component. Only generic components support many-to-one mapping. Both intent components and generic components support one-to-one mapping. Intent components support one-to-one mapping only.

Set a many-to-one mapping

  1. Use the check boxes beside the intent names to select the intents you want to map.
    A toolbar appears above the intents table.
    Panel nlu intents select multiple
  2. Click Map (n) to component, and choose an existing component from the list.
    Panel nlu intents select multiple map to component
    Tip: If your project does not yet have the generic component you want to use, you can create it on the fly.
  3. Click Confirm to dismiss the message that prompts you to confirm your intention.
    This maps all selected intents to the specified component.

Set a one-to-one mapping

  1. Click Map this intent, next to the name of the intent you want to map.
    (Click the name of the current component, if the intent was already mapped.)
  2. Choose either the dedicated intent component or an existing generic component, as required.

Convert an intent component into a generic component

  1. In the Components pane, click the Component icon [icon-component IMAGE] next to the intent component you want to convert into a generic component (expand the Intent Components section of the Components pane, if needed).
    Design convert to component
    A message appears prompting you to confirm your intention.
    Note: This action cannot be undone.
  2. Click Confirm.
    The component now appears in the (generic) Components section of the Components pane.
    Design converted component

Remove the default mapping for an intent

Click the More icon Icon ellipsis h for the intent and choose Remove mapping.

Once an intent has been mapped to a component in the NLU panel, it is easy to navigate directly to that component to further design it.

Click the More icon Icon ellipsis h for the intent and choose Go to component.

This closes the NLU resource panel and shows the desired component on the canvas.

Manage entities

In Mix.dialog you can use the Entities tab of the NLU resource panel to manage entities. You can also create entities on the fly from question and answer nodes. Any changes you make to entities in Mix.dialog become available in Mix.nlu, and vice versa. Use Mix.nlu to link entities to intents by adding sample sentences and annotating them (refer to the Mix.nlu documentation).

Entity attributes

Entities have these attributes:

Attribute Type Description
.literal String The exact words collected for the entity.
.value Any The recognized value, in the format specified for the entity. An entity that has not yet been collected does not have a value and is considered null. Use the .clear() method in an assign action to reset an entity to this null state.
.isCompleted Boolean true if the entity has a value that is considered valid; otherwise false. By default, question router nodes automatically set .isCompleted to true, for the entities they handle, whenever question and answer nodes return with collected values. You can enable Manual Complete for an entity, in the question router node that handles it, if your dialog design requires this attribute to be set manually.
.isRequired Boolean true if the entity is required for the associated intent; otherwise false.
.isConfirmed Boolean true if the entity has a value that does not require further confirmation; otherwise false.

If business logic requires setting entity attributes manually, make sure you set assign actions at the appropriate nodes in your dialog.

Note: Clearing an entity sets its .value and .literal attributes to NULL, .isRequired to true, .isConfirmed and .isCompleted to false. You cannot change the .literal attribute of an entity (except by clearing the entity).

List entities

The default type for a custom entity, List, represents a list of possible values.

For list entities, literals and values are language-specific, whereas the entities themselves are common to all languages. When you add an entity value, it only applies to the current language in your project. To support language-specific requests, choose the desired language from the menu near the name of the project, and add literal-value pairs as required.

When you attempt to delete the last literal for a specific value, Mix warns you that you will be permanently deleting not only the (last) literal but also the entity value itself for the current languages, and prompts you to confirm the deletion.

In a dialog that collects a list entity, the next step might need to be different for each possible value, or it might be the same for all possible values. It is also possible for your application to perform exclusive actions for some values, and proceed via a common path for all other values. You determine the required behavior for a list entity—that is, whether all values are handled the same way, or individual values determine different paths—, when you set up the question and answer node that collects the entity.

Dynamic list entities

When you create your NLU model, you might realize that, for some list entities, the set of values can only be fully determined at runtime. For example, the set of contacts for a user is specific to that user. Another example is the list of products available at a specific location (such as the restaurant branch closest to the user’s current position), or on specific occasions (seasonal products, holiday products), and so on. For such purposes, you can define dynamic list entities, and rely on the client application to make additional literal-value pairs available to the dialog, at runtime, via a data access node.

Workflow for using a dynamic list entity

  1. Add a list entity, and mark it as dynamic.
  2. Add a few representative literal-value pairs for the entity.
  3. Create a variable of type Dynamic Entity Data.
  4. Set up a data access node using your dynamic entity data variable to get additional values for your dynamic entity, from the appropriate external system, at runtime.
  5. Set up a question and answer node to collect your dynamic list entity.
  6. In Mix.nlu, make sure you have annotated some samples with your dynamic list entity, and that your NLU model has been trained.
  7. Preview your dialog design.
    When the dialog reaches the data access node that is meant to return the dynamic entity data variable:
    1. Choose the dynamic list entity to be extended with data from your dynamic entity data variable.
    2. Use the fields that appear to enter literal-value pairs (and define interactive elements if needed).
      Tip: Use Copy to Clipboard and save the JSON representation of the stub data, to be able to use the JSON bulk input feature the next time you must provide stub data at this data access node.

Dynamic entity data specification

Dynamic entity data variable example

{
    "moreCoffeeTypes": {
        "COFFEE_TYPE": [{
                "canonical": "cold brew",
                "literal": "cold brew"
            }, {
                "canonical": "iced cappuccino",
                "literal": "iced cappuccino"
            }
        ]
    }
}

The Nuance Mix Platform’s NLU and ASR services support dynamic list entities by using inline wordsets. In Mix.dialog, when using the TRY tab to preview your dialog design, the stub data you provide at a data access node is a JSON representation that includes both the inline wordset and data to support interactivity. For more information on using wordsets to extend your NLU and ASR models, refer to the gRPC API documentation for NLU as a Service, and ASR as a Service.

Dynamic entity data variable object

Represents a dynamic entity data variable returned by a data access node.

Element Type Description
variable Dynamic entity data object Where variable is the dynamic entity data variable specified in the data access node
Dynamic entity data object

Represents dynamic entity data for a dynamic list entity.

Element Type Description
entity Array of Dynamic entity data items Where entity is the dynamic list entity to be extended with the dynamic entity data
Dynamic entity data item

Represents an additional value for a dynamic list entity, and attributes to support interactivity for the value.

Element Type Description
canonical String (Optional) The value of the entity
literal String The written or spoken form of the value; doubles as the value when canonical is omitted
spoken Array (Optional) One or more additional spoken forms of the value—used by ASR; ignored for NLU
label String (Optional) A label, such as the text to show on a button
image_url String (Optional) A link (URL or relative path) for the image to use on a button
description String (Optional) A description

Relationship entities

A relationship entity has a specific relationship to an existing entity, either the isA or hasA relationship. For example, for an airline application, the entities that represent departure and arrival airports typically have the same possible values. If you first create a list entity (for example, CITY) to represent all the airports served by the airline, you can share its definition with other entities meant to represent departure and arrival cities by making these isA relationship entities: for example, ORIGIN isA CITY, and DESTINATION isA CITY. Assuming your NLU model has representative samples annotated with ORIGIN and DESTINATION, the application will be able to recognize what a user means when they say, for example, “I would like to book a flight to Barcelona from Helsinki.” Refer to the Mix.nlu documentation for more information.

Freeform entities

A freeform entity is used to capture user input that you cannot enumerate in a list. For example, a text message body could be any sequence of words of any length. Unlike other entity types, for which the keywords in the user input that allow the NLU service to recognize an entity are directly associated with the entity values, a freeform entity is like a black box—at runtime, the NLU service relies on the surrounding text to identify where the entity itself starts and ends. When the user says, for example, "Send Joe this message: I'll be there tonight," the words "this message" are what tells the NLU service that what follows is the freeform entity to collect. Refer to the Mix.nlu documentation for details.

Regex-based entities

A regex-based entity represents a sequence of characters matching a pattern defined by a regular expression. For example, account numbers, postal/zip codes, order numbers, and other pattern-based formats. Refer to the Mix.nlu documentation for details.

Rule-based entities

A rule-based entity defines a set of values based on a GRXML grammar file. Refer to the Mix.nlu documentation for detailed information.

Predefined entities in Mix.dialog

Mix.nlu shares with Mix.dialog a set of predefined entities from data packs installed with your Mix platform. Mix.dialog supports these:

In addition to the entities from the data packs, Mix also provides a set of dialog-specific predefined entities. Mix.dialog supports these:

Anaphoras

The dialog context service supports resolving anaphoras recognized by your project’s NLU model, such as “there” (REF_PLACE), “then” (REF_TIME), or “her” (REF_PERSON) to a corresponding entity value that was previously collected (up to the previous two recognition steps) in the dialog flow. Once anaphoras have been tagged and your model trained in Mix.nlu, your dialog can handle them automatically. You do not need to configure anything in your dialog model. At runtime, the dialog uses the data that is has available to determine how to resolve the anaphora. Refer to the Mix.nlu documentation for details.

Show the Entities tab of the NLU resource panel

Click NLU, on the toolbar, to open the NLU resource panel, and then switch to the Entities tab.

(Click NLU again to close the panel.)

Panel nlu entities

Add an entity

  1. Choose the desired input format from the Input format list:
  2. Click the Add icon Icon plus.
  3. Type a unique name for the entity—for example, COFFEE_SIZE—and press Enter.
    The new entity appears in the list of custom entities.
    Note: Entity names must not start with a number and cannot include spaces. Use underscores as separators if desired. The name must be unique across all intents, entities and variables in your project.
  4. If this is a list entity, choose its type:
  5. For a list-type entity: add literal-value pairs.
  6. For a dynamic list entity, mark it as dynamic.
  7. If this entity will hold sensitive information that must be masked in application logs, mark it as sensitive.
  8. If this is an entity for which you want to be able to recognize anaphoras, mark it as referable.

Rename an entity

  1. In the list of custom entities, click the entity you want to rename.
    Alternatively, choose the entity from the list in the upper-right area of the panel.
    Tip: Use the Input format list, or the text filter box, to narrow down the list.
  2. Click the Edit icon Icon edit next to the selected entity in the upper-right area of the panel.
    The name becomes editable.
  3. Modify the name as desired.
    Note: Entity names must not start with a number and cannot include spaces. Use underscores as separators if desired. The name must be unique across all intents, entities and variables in your project.

Delete an entity

Note: You can delete an entity only if your project does not use it.

  1. In the list of custom entities, click the entity you want to delete.
    Alternatively, choose the entity from the list in the upper-right area of the panel.
    Tip: Use the Input format list, or the text filter box, to narrow down the list.
  2. Click the Delete icon Icon trash next to the selected entity in the upper-right area of the panel.
    A message appears prompting you to confirm your intention.
  3. Click Confirm.

Add literals for a list entity

  1. In the list of custom entities, click the entity for which you want to add literals.
    Alternatively, choose the entity from the Entity list in the upper-right area of the panel.
    Tip: Use the Input format list, or the text filter box, to narrow down the list.
  2. Use the fields under Literals, in the area on the right-hand side, to add a few representative literal-value pairs.
    The literal text automatically doubles as the value, by default. If you want the value to be different, press Tab and type the desired value before pressing Enter.
    Multiple literals can have the same value, to help your application recognize the different ways a user might say an entity.
  3. To add a literal for an existing value, click the Add icon Icon plus next to the existing literal, type the new literal and press Enter.
    Panel nlu entities literals add
  4. If your project supports multiple languages, use the menu near the name of the project to switch to another language, and proceed in the same fashion, until you have representative literal-value pairs for every language in your project.

Delete a value

  1. In the list of custom entities, click the entity for which you want to delete a literal-value pair.
    Alternatively, choose the entity from the Entity list in the upper-right area of the panel.
    Tip: Use the Input format list, or the text filter box, to narrow down the list.
  2. Click the Delete icon Icon trash next to the value you want to delete.
    A message appears prompting you to confirm to confirm your intention.
  3. Click Yes, Delete.
    The value and all associated literals are no longer available.

Delete a literal

  1. In the list of custom entities, click the entity for which you want to delete a literal-value pair.
    Alternatively, choose the entity from the Entity list in the upper-right area of the panel.
    Tip: Use the Input format list, or the text filter box, to narrow down the list.
  2. Click the Delete Literal icon next to the literal you want to delete.
    Entity delete literal
    A message appears prompting you to confirm your intention.
  3. Click Yes, Delete Literal.

Mark a list entity as dynamic

  1. In the list of custom entities, click the entity you want to use as a dynamic list entity.
    Alternatively, choose the entity from the Entity list in the upper-right area of the panel.
    Tip: Use the Input format list, or the text filter box, to narrow down the list.
  2. Click the Dynamic check box under the selected entity in the upper-right area of the panel.

Mark an entity as referable

  1. In the list of custom entities, click the entity for which you want to be able to recognize anaphoras.
    Alternatively, choose the entity from the Entity list in the upper-right area of the panel.
    Tip: Use the Input format list, or the text filter box, to narrow down the list.
  2. Under the selected entity in the upper-right area of the panel, expand the list next to Referenced as, and choose the appropriate anaphora type:
    • REF_PERSON: References a person (for example, “him”, “her”, “them”)
    • REF_PLACE: References a place (for example, “there”, “here”, “that place”)
    • REF_THING: References a thing (for example, “it”)
    • REF_MOMENT: References a time (for example, “then”, “at that time”)

Mark an entity as sensitive

Entities marked as sensitive are masked in application logs.

  1. In the list of custom entities, click the entity you want to mark as sensitive.
    Alternatively, choose the entity from the Entity list in the upper-right area of the panel.
    Tip: Use the Input format list, or the text filter box, to narrow down the list.
  2. Click the Sensitive check box under the selected entity in the upper-right area of the panel.
    Panel nlu entities sensitive

Manage grammars

Use the Grammars tab of the NLU resource panel to export a grammar specification document, to help design and manage grammars that will be referenced by a VoiceXML application.

A grammar specification document lists all speech and DTMF grammar references found in your dialog design:

The document also includes any DTMF mappings you may have specified in your dialog design, for commands, confirmation, or entity values.

A grammar specification document includes these columns:

Column Description
channel Name of a channel profile, or Global Commands
node name Name of a specific question and answer node, or All Nodes for a global command or confirmation grammar
speech enabled T (true) if the the speech grammar referenced at the specified node is enabled; T (true) for All Nodes, if your project supports a global speech grammar for command or confirmation interactions; otherwise F (false)
speech grammar name Speech grammar referenced for global command or confirmation interactions, or at the specified question and answer node: either a filename including extension—for example, myGrammar.grxml—, or a variable name followed by “(dynamic)”—for example, myGrammar (dynamic)
dtmf enabled T (true) if the the DTMF grammar referenced at the specified node is enabled, in the context of a channel profile that support DTMF input; T (true) for All Nodes, if your project supports a global DTMF grammar for command or confirmation interactions; otherwise F (false)
dtmf grammar name DTMF grammar referenced for global command or confirmation interactions, or at the specified question and answer node: either a filename including extension—for example, myDtmfGrammar.grxml—, or a variable name followed by “(dynamic)”—for example, myDtmfGrammar (dynamic)
intent For a question and answer node that collects an entity, applicable intent, if any; otherwise blank
entity name Name of the entity collected at the question and answer node specified under node name; or name of the global command entity (for a global command grammar); or nuance_BOOLEAN (for a global confirmation grammar)—matches the slot/root name that the grammar should return for speech and DMTF
language Language of a literal-value pair for an entity, as a language code (for example, en-US, fr-CA)
entity value A specific entity value
entity literals The literals for the specified entity value, if the specified entity is a list entity
dtmf value The DTMF key, if any, for the specified entity value

Show the Grammars tab of the NLU resource panel

Click NLU, on the toolbar, to open the NLU resource panel, and then switch to the Grammars tab.

Panel nlu grammars

(Click NLU again to close the panel.)

Export the grammar specification document

  1. If you want to restrict the grammar specification document to a specific channel profile, choose it from the Channel Dock list; otherwise, the grammar specification covers all channel profiles in your project.
  2. Click Download Grammar Properties, on the Grammars tab of the NLU resource panel.
    This downloads a CSV file, whose filename has this format: project_timestamp_grammars.csv, where project is the name of your Mix project, and timestamp reflects the current date and time.

Manage variables

In Mix.dialog use the Variables resource panel to manage variables in the current dialog project. For example, you can use a variable:

The Variables panel organizes your variables into these categories:

Category Description
Undefined Variables whose data type has yet to be set. In some situations, you might prefer to quickly add a variable and wait until later to fully define its data type. For example, while setting up a node, you realize you need a new variable to store a value: you can add a variable on the fly and start using it immediately. The new variable is considered undefined, until you set its data type, upon which it will appear under Simple, or under Data Objects.
Simple Variables of type string (default), alphanumeric, digits, Boolean, integer, decimal, amount, date, time, distance, temperature, list, or dynamic entity data. Note: Use dynamic entity data variables to support dynamic list entities. Dynamic entity data is not a supported type for list items.
Data Objects In Mix.dialog, data objects represent complex variables comprising multiple variables, including nested data objects. For example, the data object for a person might include the person’s name, address, phone number, date of birth, and so on, where the address is also a data object specifying street number, street name, city, and so on. Before adding data objects you must first define their underlying schema. A data object is always based on a schema.
Schemas A schema represents the structure of a data object. You can create multiple data objects, or lists of data objects, based on a common schema. Schemas can also refer to other schemas. For example, the schema for a postal address may appear in schemas that represent a user, a company, and so on. Note: Dynamic entity data is not a supported type for schema fields.

If your design has variables that will store sensitive information that must be masked in application logs, you can mark these variables as sensitive. For complex variables, mark sensitive fields in the schema upon which they are based.

Simple variable types

Choose the type of a simple variable based on what you want it to hold. When you use a variable of a specific type in a dynamic message, its value can be rendered with appropriate formatting.

A variable of type string on the left-hand side of an assign action is compatible with all entities and variable types. However, if you use a variable of type string on the right-hand side of an assign action, you are responsible for making sure its value will comply with the internal format of the variable or entity on the left-hand side. Neglecting this could generate errors in your application, at runtime.

Dynamic Entity Data is a special variable type, meant to turn a list entity into a dynamic list entity.

A variable of type list can have elements of one single type (simple or complex), except for Dynamic Entity Data, and list.

Compatibility between variables and entities

For each variable type, this table shows compatibility information.

Variable type Description Compatible entities Other compatible variable types
String String of characters (default) YES_NO, nuance_GENERIC_ORDER, List, Regex, Freeform Alphanumeric, Digits
Alphanumeric String of alphanumeric characters (a-z, A-Z, 0-9) Regex Digits
Digits String of digits (0-9) nuance_CARDINAL_NUMBER, Regex Integer
Boolean Boolean (true, false) nuance_BOOLEAN
Integer Whole number nuance_CARDINAL_NUMBER Digits
Decimal Decimal-point number nuance_DOUBLE, nuance_NUMBER
Amount Amount, including currency nuance_AMOUNT
Date Date (YYYYMMDD) DATE, nuance_EXPIRY_DATE
Time Time (HHMM) TIME
Distance Distance, including unit and modifier nuance_DISTANCE
Temperature Temperature, including unit nuance_TEMPERATURE
Dynamic Entity Data Special type, to support dynamic list entities Dynamic list entities
List List of values of a single simple variable type (except for Dynamic Entity Data), or complex values based on a single schema Depends on the type of the list elements Type of the list elements

Supported methods

This table shows the methods that are available for each simple variable type.

Variable type Methods in assign actions Methods in conditional expressions Methods in message annotations
String .length(), .concat(…), .search(…), .substring(…) .value(), .length() .value(), .length()
Alphanumeric Value (implicit) Value (implicit) Formatted value, .value()
Digits Value (implicit) Value (implicit) Formatted value, .value()
Boolean Value (implicit) Value (implicit) Value (implicit)
Integer Value (implicit) Value (implicit) Formatted value, .value()
Decimal Value (implicit) Value (implicit) Formatted value, .value()
Amount .getNumber(), .getUnit() .value(), .getNumber(), .getUnit() Formatted value, .value(), .getNumber(), .getUnit()
Date .getDay(), .getMonth(), .getYear(), .isBefore(…), .isAfter(…), .addDay(…), .addMonth(…), .addYear(…) .value(), .getDay(), .getMonth(), .getYear() Formatted value, .value(), .getDay(), .getMonth(), .getYear()
Time .getHour(), .getMinute(), .getMeridiem(), .isBefore(…), .isAfter(…), .addHour(…), .addMinute(…) .value(), .getHour(), .getMinute(), .getMeridiem() Formatted value, .value(), .getHour(), .getMinute(), .getMeridiem()
Distance getNumber(), getUnit(), getModifier() .value(), .getNumber(), .getUnit(), getModifier() Formatted value, .value(), .getNumber(), .getUnit(), getModifier()
Temperature .getNumber(), .getUnit() .value(), .getNumber(), .getUnit() Formatted value, .value(), .getNumber(), .getUnit()
List .length(), .get(…), .contains(…) .value(), .length() .value(), .length()
Dynamic Entity Data Value (implicit) Value (implicit) Value (implicit)

Predefined variables

All dialog projects have these predefined variables:

Variable Description
channelIntegration Channel information provided by the client application—not to be confused with channel profile. For example, a “Social VA” channel profile might apply to multiple channels, such as WhatsApp, or Facebook Messenger. In a dialog design, you can use this variable to define channel-specific conditions, or for reporting purposes (for example, to report metrics per channel).
language Current interaction language. Use this variable to switch to another language at runtime when required.
returnCode Return code for data access nodes.
returnMessage Message that describes the meaning of the return code.
Active Intent Value Value of the active intent. This value is set by an intent mapper node and it primarily comes from the last NLU interpretation result, either at a question and answer node collecting an NLU intent, or at question and answer nodes collecting entities subject to a question router node where intent switching is enabled. Use this variable to switch to another intent programmatically at runtime, when required—for example, in a disambiguation context when the dialog needs to prompt the user for more details in order to correctly identify their intent. See Active Intent behavior for more details.
Active Intent Literal Literal for the active intent from the last NLU interpretation result.
Active Intent Confidence Confidence score for the active intent from the last NLU interpretation result.
Current Entity Value Current entity value from the last NLU interpretation result. Use this variable to create dynamic confirmation default messages. Only available in the Confirmation default messages section of the Project Settings panel.
Last Collection Interpretation Interpretation result from the last collection operation, including literal, possible intents, the confidence score for each possible intent, possible entities, if any, including value and confirmation score. Last Collection Interpretation is updated each time recognition happens upon user input at a question and answer node, recovery, global command, or intent switch, including when recognition generates a nomatch event. You could use this, for example, to analyze the literals that generated nomatch events in your application. Use a data access node, an external actions node, or a question and answer node, to send this variable to the client application or to an external system for further processing. If you want to use the last interpretation literal—for example, to use its length in a condition—use the complex variable lastCollectionResultObject.
Last Confirmation Interpretation Interpretation result from the last confirmation operation, including literal, possible intents, possible entities, and confidence scores. Last Confirmation Interpretation is updated each time the dialog prompts the user for confirmation. Use a data access node, an external actions node, or a question and answer node, to send this variable to the client application or to an external system for further processing. If you want to use the last confirmation literal—for example, to use its length in a condition—use the complex variable lastConfirmationResultObject.
lastCollectionResultObject Complex variable based on the interpretationResult schema. Interpretation result from the last collection operation, including literal, possible intents, and the confidence score for each possible intent. You can use this variable to reference the intent literal’s length, for example, in conditions.
lastConfirmationResultObject Complex variable based on the interpretationResult schema. Interpretation result from the last confirmation operation, including literal, possible intents, and the confidence score for each possible intent.
userData Complex variable based on the userData schema.

Active intent behavior

Active Intent Value doesn't exactly behave as you would expect from a variable. You might think of it more as a function that returns the active intent at the state where you invoke it. At runtime, only an intent mapper node can update Active Intent Value, based on the latest recognition results (built-in intent switching), or following an assign action (manual intent switching).

When the system recognizes that the user wants to fulfill a different intent, Active Intent Value does not immediately reflect the new intent: if you follow Active Intent Value as the dialog flows (for example, by using it in dynamic messages or by sending it to external systems), you'll notice that its value persists from the moment the dialog enters a mapped component—that is, a component that has been mapped to an intent, either in the NLU resource panel or in an intent mapper node—, from an intent mapper node, all the way until the dialog eventually returns to the same intent mapper node, or reaches another one.

When the dialog enters a component via a component call node (as opposed to entering via an intent mapper node), Active Intent Value does not change. In the case of an otherwise mapped component, any required entities can still be collected to fulfill the intent associated with this component but, if you use Active Intent Value for reporting purposes, you might notice that it doesn't match the intent for the component in focus.

Likewise, in a manual intent switching scenario, when an assign action is used to set Active Intent Value, the new value is not immediately applied and only becomes effective at the next intent mapper node. However, in this scenario, you must also make sure there are no other question and answer nodes between the assign action and the intent mapper that will perform the switch since the recognition results from the last question and answer node would take precedence and be applied to Active Intent Value instead of the intent you specified.

Last interpretation behavior

At runtime, whenever the dialog enters a question and answer node, the last interpretation variables (collection and confirmation, simple and complex) are all cleared (null). Therefore, if you have configured the Send Data section of the node properties to send any of these variables to the client application, since the node sends the specified data with each request it makes to the Dialog service, they will be sent as null with the first request, upon entering the node. In case of a nomatch recognition event at this node, the data sent with the next request will include the nomatch recognition results (that is, the literal, NO_MATCH as the intent, and a confidence score). Data specified in Send data is never sent when transitioning out of the node.

Last interpretation specification

Example of last interpretation object

{
    "literal": "from my tfsa account please",
    "interpretations": [{
            "intent": "CHECK_BALANCE",
            "confidence": 0.27720454,
            "literal": "from my tfsa account please",
            "entities": [{
                    "name": "ACCOUNT_TYPE",
                    "value": "TFSA",
                    "confidence": 1.0,
                    "literal": "tfsa"
                }
            ]
        }, {
            "intent": "TRANSFER_FUNDS",
            "confidence": 0.51478267,
            "literal": "from my tfsa account please",
            "entities": [{
                    "name": "TO_ACCOUNT",
                    "value": "TFSA",
                    "confidence": 1.0,
                    "literal": "tfsa"
                }
            ]
        }, {
            "intent": "TECH_SUPPORT",
            "confidence": 0.09913357,
            "literal": "from my tfsa account please"
        }
    ]
}

Represents the last interpretation at the collection or confirmation step of a question and answer node. Except in noinput situations, in which case these predefined variables are null, the predefined simple variables Last Collection Interpretation and Last Confirmation Interpretation contain a key-value pair, where the key is either LAST_COLLECTION_INTERPRETATION or LAST_CONFIRMATION_INTERPRETATION, and the value is a string that contains an object with this structure:

Element Type Description
literal String Literal from the last recognition results
interpretations Array or intent interpretations Possible intents and entities, including confirmation scores
Intent interpretation
Element Type Description
intent String Intent name
confidence Number Confidence score
literal String Literal from the last recognition results
entities Array of entity interpretations Possible entities, if any, including value and confirmation score
Entity interpretation
Element Type Description
name String Entity name
value String Entity value
confidence Number Confidence score
literal String Entity literal extracted from the last recognition results

Predefined schemas

All dialog projects have these predefined schemas:

DynamicMessageReference schema

Use this schema to create complex variables, when you need dynamic message references—for example, when a message does not directly depend on something the user said but on something else that can only be determined by the client application at runtime. This schema has two fields:

Field Type Description
audioFileName String Holds an audio filename, extension included. Audio files must be placed in specific directories, relative to the client application, that is basePath/language/prompts/library/channel/, where basePath is where the client application expects to find all required language-specific material (audio files and grammar files), language is the appropriate language code (for example, en-US, fr-CA), library is the name of a message library (must be: “default”), and channel is the name of the channel profile using the audio files (or “default” for audio files that apply to all channel profiles).
ttsBackup String Holds alternative TTS verbiage, in case the audio file with the message becomes unavailable. The alternative TTS verbiage is also used in the TRY tab, when you preview your dialog design.
Workflow for using a dynamic audio file reference
  1. Create a complex variable based on the DynamicMessageReference schema.
  2. Set up a data access node using your complex variable to get the required audio file reference, from the appropriate external system, at runtime.
  3. Add a dynamic message for the Audio Script modality, and use your complex variable as a dynamic placeholder.
  4. Preview your dialog design for a channel profile that supports the Audio Script modality (for example, IVR/Voice VA).
  5. When the dialog reaches the data access node that is meant to return the dynamic file reference, use the fields that appear to enter an audio filename (including the extension), and alternative text.
    Notice that the alternative text appears in the chat pane when the dialog reaches the node that has the message with the dynamic audio file reference.

interpretationResult schema

This reserved schema applies to the predefined complex variables lastCollectionResultObject and lastConfirmationResultObject. This schema has two fields:

Field Type Description
literal String Literal from the last recognition results
interpretations List of interpretation Possible intents and confirmation scores

interpretation schema

This schema has two fields:

Field Type Description
intent String Intent name
confidence Decimal Confidence score

userData schema

Represents data collected from the current end user.

Field Type Description
timezone String Time zone of the user—can be used for reporting purposes, or to convert time and date information to the appropriate time zone
userGlobalID String Global unique identifier of the user across all channels—for example, a member ID (from a banking or healthcare system), or a Social Security number; can be used for reporting purposes
userChannelID String Channel-specific identifier for the user—for example, the ANI (for IVR, SMS, and WhatsApp channels), or the user's IP address (for webchat); can be used for reporting purposes
userAuxiliaryID String Secondary identifier for the user—for example, a device ID, tracking number, or package number; can be used to log a secondary identifier of the user
systemID String Identifies how the system or application was reached by the end user—for example, the DNIS (for IVR, SMS, and WhatsApp channels), or a Facebook page (for Facebook Messenger); can be used for reporting purposes
location location object Geographic coordinates (latitude, longitude) of the user—can be used for reporting purposes, and for mobile web and mobile native virtual assistant applications

location schema

Represents geographic coordinates.

Field Type Description
latitude String East-west position, in the format set by the client application
longitude String North-south position, in the format set by the client application

Open the Variables resource panel

Click Variables, on the Mix.dialog toolbar, to open the Variables resource panel. (Click Variables again to close the panel.)

Panel variables simple

Create a simple variable

  1. Click the Add icon Icon plus, next to Simple.
  2. Type a unique name for the variable and press Enter.
    The new variable appears in the Simple list.
    Note: Variable names are limited to letters (A-Z, a-z), digits (0-9), the dollar sign ($) and the underscore (_). They must not start with a digit. The name must be unique across all intents, entities and variables in your project.
  3. On the right-hand side of the panel, choose the desired simple variable type from the Type list.
  4. If you chose List, choose a type for the list elements from the List Type list.
  5. Add a display value, to be used when previewing your design, if desired.
    (Not available for list and dynamic entity data variables.)
  6. Mark the variable as sensitive, if required.
  7. Add notes (maximum 255 characters), if desired.

Set the type of an undefined variable

  1. In the left-hand pane of the Variables panel, expand the Undefined category, if needed, and click the variable whose type you want to set.
  2. On the right-hand side of the panel, choose the appropriate category: Simple, or Object.
    Panel variables undefined set category
  3. If you chose Simple, now choose the desired type from the second list that appears.
    Panel variables simple set type
  4. If you chose Object, now choose the appropriate schema from the second list.
    Panel variables complex set schema

Rename a variable

  1. In the left-hand pane of the Variables panel, expand the appropriate category, if needed, and click the variable you want to rename.
  2. In the right-hand pane of the panel, click the variable name.
    The name becomes editable.
  3. Modify the name as desired.
    Note: Variable names are limited to letters (A-Z, a-z), digits (0-9), the dollar sign ($) and the underscore (_). They must not start with a digit. The name must be unique across all intents, entities and variables in your project.

Delete a variable

Note: You can delete a variable only if there are no references to it in your design. To remove stray variable references from your design, see review the variable’s usage information.

  1. In the left-hand pane of the Variables panel, expand the appropriate category, if needed, and click the variable you want to delete.
  2. In the upper-right corner of the panel, click the Delete icon.
    A message appears prompting you to confirm your intention.
  3. Click Confirm.

View usage information for a variable

  1. In the left-hand pane of the Variables panel, expand the appropriate category, if needed, and click the desired variable.
    The number of references to this variable in the current project appears, as a button, next to the variable’s name in the right-hand pane.
    Panel variables usage count
  2. Click the button to see the nodes whose properties include references to this variable.
    Panel variables usage count expanded
  3. Click a node in the list.
    The Variables panel closes and the selected node is in focus on the design canvas. You can review the references to the variable in the Properties pane.

Mark a variable as sensitive

Variables marked as sensitive are masked in application logs.

  1. In the left-hand pane of the Variables panel, expand the appropriate category, if needed, and click the variable you want to mark as sensitive.
  2. Click the Sensitive check box to select it.
    Panel variables sensitive

Create a schema

  1. Click the Add icon Icon plus next to Schema.
  2. Type a unique name for the schema and press Enter.
    The new schema appears in the Schema list.
    Panel variables schema initial
  3. Use the fields under Add to Schema, in the area on the right-hand side of the panel, to add the desired fields and set their type.
    Panel variables schema simple
  4. If some fields will be holding sensitive information, mark them as sensitive.
  5. Add notes (maximum 255 characters), if desired.

Rename a schema

  1. In the left-hand pane of the Variables panel, expand the Schema category, if needed, and click the schema you want to rename.
  2. In the right-hand pane of the panel, click the schema name.
    The name becomes editable.
  3. Modify the name as desired.

Delete a schema

  1. In the left-hand pane of the Variables panel, expand the Schema category, if needed, and click the schema you want to delete.
  2. In the upper-right corner of the panel, click the Delete icon.
    A message appears prompting you to confirm your intention.
  3. Click Confirm.

Rename a field in a schema

  1. In the left-hand pane of the Variables panel, click the desired schema.
  2. In the right-hand pane of the panel, click the field you want to rename.
    The name becomes editable.
  3. Modify the name as desired.
    Note: Like simple variable names, complex variable field names are limited to letters (A-Z, a-z), digits (0-9), the dollar sign ($) and the underscore (_). They must not start with a digit. The name must be unique across all intents, entities and variables in your project.

Change the type of a field in a schema

  1. In the left-hand pane of the Variables panel, expand the appropriate schema, and click the field whose type you want to change.
  2. Use the fields under Type, in the area on the right-hand side of the panel, to set the desired type.
  3. (Optional) Add a display value, and notes (maximum 255 characters), if desired.

Change the order of the fields in a schema

Use the grip icon Icon grip to drag a field up or down, until all fields are in the desired sequence.

Delete a field in a schema

  1. In the left-hand pane of the Variables panel, click the appropriate schema.
  2. In the right-hand pane of the panel, click the Delete icon Icon trash next to the name of the field you want to delete.

Mark a field as sensitive in a schema

For complex variables, fields marked as sensitive in the base schema are masked in application logs.

  1. In the left-hand pane of the Variables panel, expand the appropriate schema, and click the field you want to mark as sensitive.
  2. Click the Sensitive check box to select it.
    Panel variables schema field sensitive

Create a complex variable

  1. Click the Add icon Icon plus next to Data Objects.
  2. Type a unique name for the complex variable and press Enter.
    The new complex variable appears in the Data Objects list.
  3. On the right-hand side of the panel, choose the desired schema from the second list, under Type.
    Panel variables complex added
  4. Add notes (maximum 255 characters), if desired.

Manage messages

Messages resource panel example, Table View

The Messages resource panel allows you to manage all messages in your project. When you set a message in a node, or in the Project Settings panel, or directly in the Messages resource panel, it becomes available for reuse anywhere within your project. To support language-specific messages, choose the desired language from the menu near the name of the project.

Open the Messages resource panel

Click Messages, on the toolbar, to open the Messages resource panel.

(Click Messages again to close the panel.)

Add a message for your project

  1. Click the Add icon Icon plus in the upper-right corner of the Messages list.
    A new message skeleton appears in the list.
    Add message
  2. Enter the text to be used by default for this message.
    Mix.dialog automatically generates a name for the message, based on the text of the message. You can rename the message, if desired.
  3. (Optional) if your application must prevent users from interrupting this message, turn on Disable Barge-in.
    Disabling barge-in at the message level applies to all channel profiles and message formats.
  4. (Optional) Add format-specific variations, if desired.
    Panel messages multiformat sample
  5. (Optional) Under Channel Overrides, enter channel-specific variations, if desired.
    Panel messages multichannel sample
  6. (Optional) Use the Generate icon Icon redo to generate a static filename for the audio file to play in channels that use the Audio Script modality (the file extension is determined in the project settings).
    The generated audio file ID reflects the location of the message in the dialog design—for example gl_nm1_01, for a global (gl_) no match 1 (nm1_) recovery message created in the project settings panel; or Get_intent_ini_01, for the initial (ini_) message of the node called Get intent.
    Panel messages audio file id
    You cannot automatically generate a filename for messages that are not used in your project. However, you can enter one manually (maximum 255 characters), if desired. Only available in projects that support the Audio Script modality.
    Tip: Click Audio File IDs, in the upper-right corner of the Messages resource panel to generate static filenames for all messages that don’t already have one.

Find a message

Use the text filter box in the upper-right corner of the Messages list, to narrow down the list to only messages that include the specified text—in their name or within their content.
Panel messages filter

Edit a message

  1. In the list of messages, click the message you want to edit.
    Tip: Use the text filter box, to narrow down the list.
    The message details appear in the right-hand area of the panel.
  2. Modify the text of the default message, or the channel-specific or format-specific variations, as desired.
    Tip: In a dynamic message, you can safely edit the text of any annotation—this does not break the link with the dynamic element (variable, entity, or the active intent) represented by the annotation.

Translate a message

  1. In the list of messages, click the message you want to translate (or view) in another language.
    Tip: Use the text filter box, to narrow down the list.
    The message details appear in the right-hand area of the panel.
  2. (Optional) Copy the original text of the message to your clipboard.
  3. Choose the desired language from the menu on the toolbar of the Messages resource panel.
    This menu allows you to alternate between language-specific versions of the selected message without changing the current design language.
    Panel messages language menu
  4. (Optional) Paste the original text into one of the available message field.
  5. Translate the message text.
    Panel messages language french
  6. Add channel-specific or format-specific variations, as desired.

Rename a message

  1. In the list of messages, click the message you want to rename.
    Tip: Use the text filter box, to narrow down the list.
    The message details appear in the right-hand area of the panel.
  2. Enter the desired name in the Message ID field.
    Note: Message IDs are limited to alphanumeric characters and the characters _, [, and ].

Delete a message

  1. In the list of messages, click the message you want to delete.
    Tip: Use the text filter box, to narrow down the list.
    The message details appear in the right-hand area of the panel.
  2. Click the Delete icon Icon trash in the upper-right corner of the details pane.
    Panel messages delete
    Note: Delete is available only for messages that are not used in the project.

Find nodes that use a message

  1. In the list of messages, click the message of interest.
    Tip: Use the text filter box, to narrow down the list.
    The message details appear in the right-hand area of the panel, including the number of references for this message.
    Panel messages usage count
  2. Click the usage count.
    A list of all nodes currently using the selected message appear.
    Panel messages usage references
  3. Click a node in the list to bring that node into focus in your dialog design.

Manage events

Events resource panel showing all predefined events and one custom event

Panel events

All dialog projects have these predefined events:

Category Events
Global commands Escalate, Goodbye, MainMenu
Conversation MaxTurns
Collection MaxNomatch, MaxNoinput
Recognition MaxInvalidRecoOption, MaxNoToConfirm
Generic GenericError, GenericEvent, UserDisconnect

You cannot delete or rename the predefined events. Use the Events resource panel to add custom events for your project. You can also create custom events on the fly from event handlers.

Default dialog events (such as MaxTurns, MaxNomatch, MaxInvalidRecoOption) are thrown automatically, in a question and answer node, when their respective threshold is reached. You can configure the thresholds globally, or by channel profile, in the global settings of the project.

Likewise, global command events (Escalate, Goodbye, and MainMenu) are thrown automatically, when a question and answer node happens to recognize the corresponding global command entity value.

You set global handlers for specific command or dialog events in your project’s Start node. You can override global event handlers by setting component-level event handlers in the Enter node for a component, or by setting local event handlers in individual question and answer nodes, as needed.

If you set an event handler for GenericEvent, it will catch any event for which you haven’t set a specific handler.

Use throw event actions, in question and answer nodes, message nodes, or decision nodes, to throw custom events. It is also possible use a throw action to throw a global command event, if you want to handle a situation the same way as the global command—for example, if you want to transfer the user to a live agent to handle some error situations where a maximum threshold is reached, you can set a throw event action to throw the Escalate event.

Open the Events resource panel

Click Events, on the Mix.dialog toolbar, to open the Events resource panel.

(Click Events again to close the panel.)

Add a custom event

  1. Click the Add icon Icon plus in the upper-right corner of the Events list.
  2. Type a unique name for the custom event and press Enter.
    The new event appears at the bottom of the list.
    Note: Event names can only include letters (A-Z, a-z), and digits (0-9).

Find an event

Use the text filter box in the upper-right corner of the Events list, to narrow down the list to only events that include the specified text in their name.

Rename a custom event

  1. In the Events list, click the custom event you want to rename.
  2. In the right-hand pane of the panel, click the event name.
    The name becomes editable.
  3. Modify the name as desired.
    Note: Event names can only include letters (A-Z, a-z), and digits (0-9).

Delete a custom event

  1. In the Events list, click the custom event you want to delete.
  2. In the upper-right corner of the panel, click the Delete icon.
    A message appears prompting you to confirm your intention.
  3. Click Confirm.

Change log

Below are changes made to the Mix.dialog documentation since the initial Beta release.

2021-02-17

Updated Set messages and Supported methods, to cover output formatting for dynamic messages

2021-01-28

2021-01-20

2020-12-08

2020-12-02

Updated Manage variables to cover predefined variables: channelIntegration and userData

2020-11-25

2020-11-09

2020-10-28

2020-10-16

2020-10-06

2020-10-01

2020-08-28

2020-08-19

Updated Manage entities to reflect that the literal-value pairs for list entities are now language-specific, and to cover regex-based entities

2020-08-03

2020-07-20

Added Set up a decision node

2020-07-14

Added Set up a message node

2020-07-03

2020-06-26

2020-05-25

2020-05-14

2020-05-06

Added Set Messages

2020-04-24

Added Manage events

2020-04-14

2020-04-04

2020-03-31

2020-02-19

2020-01-22

2019-12-18

Explained how to create dynamic messages. See Manage messages.

2019-12-11

Added Manage intents, Manage entities, Manage variables, and Manage messages.

2019-12-02

Minor changes. See Get started and Dialog design elements.

2019-11-25

Sample scenario simplified and further revised to match UX changes. See Get started.

2019-11-15

Sample scenario revised to match UX changes. See Get started.