NAV Navbar

Dialog Application Specification

The Dialog Application Specification defines a JSON syntax for dialog models. Use Mix Dashboard to export or import dialog models.

This document specifies the syntax of the objects that constitute a dialog model.

Sample file

{
    "importProject": {
        // project object...
    }
}

This documentation includes a sample PizzaApp dialog design file. Download PizzaApp.json, to explore its structure. Import it into a project to experiment with the Mix.dialog features.

The sample file contains an object with this structure:

Element Type Description
importProject Project object Top level of the dialog design project

Project object

Project object example

{
    "id": "480",
    "name": "my dialog",
    "defaultLocale": "en-US",
    "supportedLocales": ["en-US"],
    "connectorColors": {
        // <channel uuid>: <color code> pairs...
    },
    "baseServiceUrl": "",
    "staticProjectId": "",
    "version": "1.0",
    "supportedChannels": [{
            "id": "154fbcdd-13ae-4ed8-9f41-3b39a4dfd0ce",
            "displayName": "IVR/Voice VA",
            "supportsRichText": false,
            "supportsViews": false,
            "codeName": "custom",
            "projectId": "480",
            "modes": ["Audio", "DTMF"],
            "lastModified": "2019-10-21T20:51:08.372Z"
        }, // more supported channels...
    ],
    "supportedCustomChannels": [],
    "richTextChannels": [],
    "globalConfirmations": [],
    "components": [{
            "id": "718ced73-350f-4ed9-b389-823fb405a096",
            "name": "Main",
            "description": "Main component",
            "nodes": [{
                    "id": "97a91ff7-6e98-49a7-ae2e-f8dc62c9a8b3",
                    "parentComponentId": "718ced73-350f-4ed9-b389-823fb405a096",
                    "endNode": {
                        // properties of the end node...
                    },
                    "projectId": "480"
                }, {
                    "id": "7f5c4335-7f4f-4d44-8904-bd06830f23ea",
                    "parentComponentId": "718ced73-350f-4ed9-b389-823fb405a096",
                    "intentmapperNode": {
                        "name": "Intent Mapper",
                        "description": "",
                        "intentMappings": {
                            "c19a0bcb-3bd9-4f7a-b5fa-80926cd25476": {
                                "componentId": "ca53b46a-e54f-4ffb-aca3-e565a263a091"
                            },
                            "68f5cd24-1cb3-4b61-80e5-6f25d0cf0564": {
                                "componentId": "0a33bd61-ee9e-4cf9-a3d9-b550af78864b"
                            },
                            "bacfe612-d642-47df-8942-266880013dd6": {
                                "nodeId": "3241a66b-96cb-4a54-8baa-fe4cbbc5d19d"
                            },
                            "5d39f071-f958-46e7-a6c0-2c038779ae4e": {
                                "componentId": "d0d9900e-8881-4b9d-a545-ec844cf10bdb"
                            }
                        },
                        "transition": {
                            "id": "c2ef0247-2b69-4570-8807-a9685e0013cc",
                            "transitionType": "GO_TO",
                            "event": "",
                            "label": "On Return",
                            "projectId": "480",
                            "nodeId": "389bba31-9825-4406-8e45-e7b0d2e38561"
                        },
                        "intentNames": {
                            "bacfe612-d642-47df-8942-266880013dd6": "Goodbye",
                            "5d39f071-f958-46e7-a6c0-2c038779ae4e": "LostBaggage",
                            "68f5cd24-1cb3-4b61-80e5-6f25d0cf0564": "FlightStatus",
                            "c19a0bcb-3bd9-4f7a-b5fa-80926cd25476": "BookFlight"
                        },
                        "timestamp": "2019-10-22T22:56:00.726Z"
                    },
                    "projectId": "480"
                }, {
                    "id": "375b8e57-2241-44ef-83df-6daa706d38a5",
                    "parentComponentId": "718ced73-350f-4ed9-b389-823fb405a096",
                    "messageNode": {
                        // properties of the message node...
                    },
                    "projectId": "480"
                }, // more nodes in the main component...
            ],
            "projectId": "480",
            "timestamp": "2019-10-21T20:51:08.437Z"
        }, // more components...
    ],
    "recovery": [],
    "variables": [{
            "id": "fcd07c8b-1e13-4840-8363-0d8d630dad15",
            "name": "Location",
            "description": "",
            "possibleValues": ["JFK", "LGA", "EWR"],
            "projectId": "480",
            "simpleVariableType": "LIST_TYPE",
            "timestamp": "2019-10-25T00:24:39.416Z"
        }, // more variables...
    ],
    "complexVariableTypes": [],
    "promptGroups": [{
            "id": "cb2c1f7a-cdb9-4e5f-9c2e-fab271b77d9d",
            "name": "pXJO4EY6AKMv_prompt",
            "prompts": [{
                    "payload": {
                        "displayText": "Welcome to Nuance Air!",
                        "ttsText": "",
                        "audioFile": ""
                    },
                    "language": "en-US",
                    "channel": "3134bc95-e755-4a9a-9b53-85107be634d7",
                    "lastModified": "2019-10-22T22:33:35.836Z"
                }
            ],
            "projectId": "480",
            "lastModified": "2019-10-22T22:33:35.832Z"
        }, // more prompt groups...
    ],
    "expressions": [{
            "id": "271845be-5a0b-4fd1-8d3b-2b7a240e3154",
            "leftVariable": {
                "id": "aa50d96a-99e2-4580-92cf-c2bb22351083",
                "name": "LocationFound",
                "description": "",
                "possibleValues": ["Exact Match", "Close Match", "No Match"],
                "projectId": "480",
                "simpleVariableType": "LIST_TYPE",
                "timestamp": "2019-10-25T00:25:11.627Z"
            },
            "projectId": "480",
            "relationalOperator": "EQUAL_OPERATOR",
            "rightConstant": "Exact Match",
            "lastModified": "2019-10-25T01:10:18.441Z"
        }, // more expressions...
    ],
    "parentId": "NONE",
    "ontologyId": "eb9c1ffd-5c1d-4702-a524-27afb9f4e976",
    "ontology": {
        "projectId": "480",
        "intents": [
                // intents in the project...
        ],
        "concepts": [
                // entities in the project...
        ],
        "lastModified": "1970-01-01T00:00:00Z"
    },
    "globalSettings": [],
    "backendConfig": [],
    "upgradeVersion": 3,
    "events": [
        // events in the project...
    ]
    "globalCommandsEntityId": "7628d885-ef5c-4d29-b79a-079afd0aa9b2",
    "globalCommands": [
        // global commands in the project...
    ]
    "versionTimestamp": "2020-02-27T01:45:56Z",
    "lastModified": "2020-02-28T01:31:28.933Z"
}

The project object is the top level of the JSON file. For a complete example, refer to the sample file.

Element Type Description
id String Unique identifier for the project
name String Name of the project
defaultLocale String Default locale for the project, as a 4-letter language code (for example, en-US)—refer to Languages and Voices for the list of languages available in the current version of Nuance Mix
supportedLocales Array of strings Supported locales for the project, as 4-letter language codes—refer to Languages and Voices for the list of languages available in the current version of Nuance Mix
connectorColors Object Key-value pairs mapping channel UUIDs and color codes
baseServiceUrl String Base application URL—for example, mycompany.com/mix
staticProjectId String ID of the master project, used to link different versions of a project
version String Version number of the project
supportedChannels Array of channels Standard channels to be used to interact with the system (for example, IVR, Web, SMS)
supportedCustomChannels Array of channels Custom channels to be used to interact with the system
richTextChannels Array of channels Rich text channels to be used to interact with the system—legacy element, supported for backward compatibility only
globalConfirmations Array of confirmations Global and default confirmation behaviors
components Array of components Components in the project
recovery Array of recovery handling objects Global and default recovery handling
variables Array of variables Variables used in the project
complexVariableTypes Array of schemas Complex variable schemas in the project
promptGroups Array of prompt groups Messages used in the project
expressions Array of expressions Expressions used in the project
parentId String Project owner
ontologyId String UUID of the ontology used for this dialog project
ontology Object Intents and entities for this dialog project
globalSettings Array Global settings for the project
backendConfig Array Backend connection presets for the project
upgradeVersion Number Internal version number used as a reference for upgrading the dialog model upon import, to include new features as they become available
events Array of events Global and custom events in the project
globalCommandsEntityId String UUID of the entity used to store a command from the user
globalCommands Array of commands Global commands defined in the project
versionTimestamp String Creation date and time for this project version, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z
lastModified String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-10-17T20:55:38.488Z

Event

Global command event example

{
    "id": "295420a0-7675-4917-9329-35e26654ed05",
    "projectId": "3534",
    "eventString": "event.nuance.dialog.escalate",
    "uiString": "Escalate",
    "throwable": true,
    "reserved": true
}

Global event example

{
    "id": "7cfb8e7a-a9ee-40b6-b660-a66ca0a0f463",
    "projectId": "3534",
    "eventString": "event.nuance.dialog.odm.maxnomatches",
    "uiString": "MaxNomatch",
    "throwable": false,
    "reserved": true
}

Custom event example

{
    "id": "54d22d9d-1793-472e-ad74-7037b76dacf0",
    "projectId": "3534",
    "eventString": "event.custom.Ping",
    "uiString": "Ping",
    "throwable": true,
    "reserved": false
}

Represents an event in the project.

Element Type Description
id String UUID of the event
projectId String ID of the project
eventString String The event to throw—for example, event.nuance.dialog.escalate
uiString String Display name of the event—for example, Escalate
throwable Boolean true if the event can be used in a throw action; otherwise false
reserved Boolean true for predefined events; false for custom events

Command

Global command example

{
    "id": "fffc3887-c8c6-4201-ae30-17d9536ca8ce",
    "projectId": "3534",
    "entityValue": "agent",
    "event": {
        "id": "295420a0-7675-4917-9329-35e26654ed05",
        "projectId": "3534",
        "eventString": "event.nuance.dialog.escalate",
        "uiString": "Escalate",
        "throwable": true,
        "reserved": true
    },
    "dtmfValue": "",
    "projectLevelEnabled": true,
    "disabledNodeIds": [],
    "disabledComponentIds": [],
    "timestamp": "2020-04-14T03:55:36.574Z"
}

Represents a global command in the project.

Element Type Description
id String UUID of the command
projectId String ID of the project
entityValue String Global command entity value to invoke the command
event Event object Event thrown when this command is invoked
dtmfValue String DTMF value to invoke the command
projectLevelEnabled Boolean true if the command is enabled in this project; otherwise false
disabledNodeIds Array Nodes where this command is disabled—Future use
disabledComponentIds Array Components where this command is disabled—Future use
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

Channel

Channel example

{
    "id": "d603492a-cebf-4344-86e1-ae08532d4e86",
    "displayName": "Omnichannel VA",
    "supportsRichText": false,
    "supportsViews": false,
    "codeName": "custom",
    "projectId": "4718",
    "modes": ["Audio Script", "DTMF", "Interactivity", "Rich Text", "TTS"],
    "lastModified": "2020-02-19T22:51:29.236Z"
}

Represents a communication channel used to interact with the system (for example, IVR, Web, SMS).

Element Type Description
id String Unique ID of the channel
displayName String Name of the channel
supportsRichText Boolean Indicates whether the channel supports rich text
supportsViews Boolean Indicates whether the channel has a visual UI component
codeName String Name used for the channel, in generated code and other code-related references
projectId String ID of the project
modes Array of strings Modalities available for messages in this channel—for example, Audio Script, TTS, Rich Text, Interactivity, DTMF
lastModified String Date and time of the last modification

Confirmation

Represents a global confirmation behavior.

Element Type Description
globalValue String Global command value or default
confirmationRecoveryBehaviors Array of global recovery behaviors Error handling for the confirmation behavior
entityType String Information type for this confirmation behavior—one of: DEFAULT, ALPHANUM, DIGITS, DATE, TIME, CURRENCY, YESNO

Recovery handling

Represent the global (default) error recovery handling.

Element Type Description
globalValue String Global command value or default
RecoveryBehaviors Array of global recovery behaviors Error handling for the recovery behavior

Global recovery behavior

Global recovery behavior example

{
    "event": "nomatch1-pre-prompt",
    "escalationLevel": 0,
    "processingItemsList": {
        // processing items to perform...
    },
    "enabled": true
}

Represents a global recovery behavior for confirmation or error recovery handling.

Element Type Description
event String Event ID—nomatch1-pre-prompt, nomatch1-prompt, yes-prompt, no-prompt, for example
escalationLevel Number Always 0
processingItemsList Processing item group object Processing items to perform
enabled Boolean true if the global recovery behavior is enabled; otherwise false

Component

Component example

{
    "id": "f5faadad-3625-4e98-a2b3-56af014c154d",
    "name": "BookFlight",
    "description": "intent",
    "nodes": [
        // one or more nodes...
    ],
    "projectId": "893",
    "eventHandlers": [],
    "timestamp": "2019-10-11T21:54:08.219Z"
}

Represents a group of nodes that make up a flow in the project.

Element Type Description
id String Unique ID of the component
name String Name of the component
description String Description of the component
nodes Array of nodes Nodes in the component
projectId String ID of the project
eventHandlers Array of event handlers Global event handlers, if in Main; component-level event handlers, in other components
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

Event handler

Event handler example

{
    "id": "71156f96-a1ac-43eb-8aed-03b97983cdc5",
    "eventId": "295420a0-7675-4917-9329-35e26654ed05",
    "transition": {
        "id": "fc7eacac-95eb-45ff-a844-f60c10cf6978",
        "transitionType": "GO_TO",
        "eventId": "",
        "label": "",
        "projectId": "3534",
        "eventLog": "",
        "nodeId": "db875195-9f58-41ca-a79c-3668e4104304"
    },
    "reserved": true,
    "projectId": "3534",
    "componentId": "de19a39d-f5f2-46bb-ad7c-671b13bd045c"
}

Represents a global event handler, if in Main; a component-level event handler, if in another component; or a node-level event handler, if in a node.

Element Type Description
id String UUID of the event handler
eventId String UUID of the event to handle
transition Transition object Transition to perform when the specified event is thrown
reserved Boolean true for a predefined event handler; otherwise false
projectId String ID of the project
componentId String For global and component-level event handlers: UUID of the component
nodeId String For node-level event handlers: UUID of the node

Node

Node example

{
    "id": "8ca23120-bd08-464f-93b8-c2264b989e89",
    "parentComponentId": "fe8418b9-9448-4ec8-a21d-b74cc7118af7",
    "controllerNode": {
        // content specific to the question router node...
    "projectId": "893",
    "eventHandlers": [],
    }
}

Represents a node in a component.

Element Type Description
id String UUID of the node
parentComponentId String UUID of the parent component
node Object One of the supported node types
projectId String ID of the project
eventHandlers Array of event handlers Node-level event handlers—override component-level event handlers, and global event handlers

Supported node types

Mix.dialog supports these types of nodes:

Element key Node type
recognitionNode Question and answer node
messageNode Message node
decisionNode Decision node
dataAccessNode Data access node
controllerNode Question router node
intentMapperNode Intent mapper node
componentNode Component call node
startNode Start node
externalactionNode External actions node
endNode End node—deprecated
transferNode Transfer node—deprecated

Question and answer node

Question and answer node example (intent collection)

{
    "name": "GetIntent",
    "description": "",
    "initialMessage": {
        "id": "cdb79788-d2f8-4966-9577-6591a8af27f7",
        "channelProcessingItemsMap": {
            "3134bc95-e755-4a9a-9b53-85107be634d7": {
                "processingItems": [{
                        "condition": {
                            "id": "35ecce91-f0c2-4c6c-b5d3-edf37032aacb",
                            "statementType": "ALWAYS_TYPE",
                            "processingItems": [{
                                    "promptGroup": {
                                        "id": "c375839a-1385-4939-871b-fad0cd962608",
                                        "name": "HuoyolLaROIK_prompt",
                                        "prompts": [{
                                                "payload": {
                                                    "displayText": "How can I help you today?",
                                                    "ttsText": "",
                                                    "audioFile": ""
                                                },
                                                "language": "en-US",
                                                "channel": "3134bc95-e755-4a9a-9b53-85107be634d7",
                                                "lastModified": "2019-10-22T22:36:55.157Z"
                                            }
                                        ],
                                        "projectId": "480",
                                        "lastModified": "2019-10-22T22:36:55.154Z"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        "projectId": "480",
        "lastModified": "2019-10-22T22:36:55.546Z",
        "parentNodeId": "389bba31-9825-4406-8e45-e7b0d2e38561"
    },
    "collectionType": "INTENT_TYPE",
    "asrGrammarfileReferences": [],
    "actionConfigurations": [],
    "inputManagerReferenceId": "",
    "conceptId": "",
    "confirmationActionConfigurations": [],
    "commandActionConfigurations": [],
    "recoRecoveryBehaviors": [],
    "settings": {},
    "defaultIntentProcessingItem": {
        "id": "aace46be-c49f-4678-b719-31ff84989c97",
        "channelProcessingItemsMap": {
            "3134bc95-e755-4a9a-9b53-85107be634d7": {
                "processingItems": [{
                        "condition": {
                            "id": "37688967-a85a-4fcb-a849-fbf9f2daa55c",
                            "statementType": "ALWAYS_TYPE",
                            "processingItems": [{
                                    "transition": {
                                        "id": "c0ef79e4-0e70-4983-96d2-ca1ce049fdfa",
                                        "transitionType": "GO_TO",
                                        "event": "",
                                        "label": "Collect Intent",
                                        "projectId": "480",
                                        "nodeId": "7f5c4335-7f4f-4d44-8904-bd06830f23ea"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        },
        "projectId": "480",
        "lastModified": "2019-10-22T01:58:35.972Z",
        "parentNodeId": "389bba31-9825-4406-8e45-e7b0d2e38561"
    },
    "conceptName": "",
    "clickables": [],
    "view": {
        "name": "",
        "style": ""
    }
    "inputVariablesConcepts": [],
    "timestamp": "2019-10-22T22:35:35.448Z"
}

A question and answer node is the basic node type in dialog applications. It recognizes user input. In a node object, the question and answer node element is identified with this key: recognitionNode.

Element Type Description
name String Name of the node
description String Description of the node
initialMessage Processing item group object Processing items to perform before recognition
collectionType String Type of data to collect—for example, INTENT_TYPE, CONCEPT_LIST_TYPE, YES_NO, nuance_ORDINAL_NUMBER; empty for a menu-type entity
asrGrammarfileReferences Array of grammar reference objects Specifies the grammars for each combination of language, channel, and library
actionConfigurations Array of action configurations Processing items to perform for each entity value or ASR value of a menu-type, yes/no or Boolean entity; blank for list-type entities
inputManagerReferenceId String UUID of the question router node handling any user input that is not recognized as the entity this question and answer node is to collect, if any; blank if collectionType is INTENT_TYPE
conceptId String UUID of the entity to collect, if any; blank if collectionType is INTENT_TYPE
confirmationActionConfigurations Array of objects Key-value pairs mapping a processing item group for each entity value or ASR value
commandActionConfigurations Array of objects Key-value pairs mapping a processing item group for each entity value or ASR value
recoRecoveryBehaviors Array of local recovery behaviors Local recovery behaviors for handling nomatch events
settings Object Key-value pairs of settings for this node
defaultIntentProcessingItem Processing item group object Only present if collectionType is INTENT_TYPE; processing items to perform after intent recognition
defaultConceptProcessingItem Processing item group object Only present if collectionType is not INTENT_TYPE; processing items to perform after entity recognition
conceptName String Name of the entity to collect, if any; blank if collectionType is INTENT_TYPE
initialProcessingItem Processing item group object Processing items to perform before the value-specific processing items—only present if collectionType is empty, YES_NO or nuance_BOOLEAN
clickables Array of interactive elements Interactive elements for each possible value of the entity to collect, if collectionType is CONCEPT_LIST_TYPE, YES_NO or nuance_BOOLEAN; otherwise empty
view View object Formatting information to pass to the client application—Future use
inputVariablesConcepts Array of inputs Key-value pairs representing variables and entities to be passed on to a client application
reentryMessage Processing item group object Optional processing items to perform before recognition—instead of initialMessage—, when the dialog flow reenters this node
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

Action configuration

Maps a value from a finite set of valid values, and the value-specific actions to perform after this value is collected.

Element Type Description
processingItems Processing item group object Processing items to perform for the entity value (or ASR value)
One of conceptValue or asrValue String Entity value (or ASR value) associated with the processing items

Local recovery behavior

Local recovery behavior example

{
    "event": "nomatch",
    "escalationLevel": 1,
    "processingItems": {
        // processing items to perform...
    }
}

Represents a local recovery behavior for handling nomatch events.

Element Type Description
event String Event ID—nomatch, for example
escalationLevel Number Escalation level of the event—1, 2 or 3
processingItems Processing item group object Processing items to perform

Interactive element

Interactive element example (a Yes button)

{
    "entityValue": "yes",
    "clickableDescription": "The Yes button",
    "imageUrl": "https://my.image.com/icon-check.png",
    "label": "YES",
    "channel": "81c6395e-db29-409d-8fdd-cd4707fba667",
    "language": "",
    "enabled": false
}

Represents an element the user can click to answer a question.

Element Type Description
entityValue String Value collected for the entity when a user clicks this element
clickableDescription String Description of the interactive element—optional
imageUrl String Link (URL or relative path) for an image to show on the interactive element—optional if label is specified
label String Text label for the interactive element—optional if imageUrl is specified
channel String Channel profile that support interaction for this question and answer node
language String Language that support interaction for this question and answer node
enabled Boolean true if the interactive element is enabled; otherwise false

View

Represents formatting information to pass to the client application for messages and interactive elements, in question and answer nodes, and in message nodes.

Element Type Description
name String Type of message or interactive element (such as Buttons, List, or Carousel)
style String Name of a class or inline CSS code to format the message or the interactive elements

Message node

Message node example

{
    "name": "Welcome",
    "description": "",
    "processingItems": {
        "id": "ec94f561-0e8a-4af2-b2d8-8f4c4759cc14",
        "channelProcessingItemsMap": {
            "0c1c26a3-2873-4636-9441-b32833bf5d4f": {
                "processingItems": [{
                        "condition": {
                            "id": "1b105707-6882-4223-8dab-fe426982f67b",
                            "statementType": "ALWAYS_TYPE",
                            "processingItems": [{
                                    "promptGroup": {
                                        "id": "1020d012-164f-4a9e-937a-112c0059644d",
                                        "name": "welcome_to_coffee_prince_",
                                        "prompts": [{
                                                "payload": {
                                                    "displayText": "Welcome to Coffee Prince!",
                                                    "ttsText": "",
                                                    "audioFile": "",
                                                    "displayTextAnnotations": [],
                                                    "ttsTextAnnotations": [],
                                                    "ttsAudioBackup": "",
                                                    "ttsAudioBackupAnnotations": []
                                                },
                                                "language": "en-US",
                                                "channel": "0c1c26a3-2873-4636-9441-b32833bf5d4f",
                                                "lastModified": "2020-05-26T22:59:11.430Z"
                                            }
                                        ],
                                        "projectId": "14174",
                                        "lastModified": "2020-05-26T23:09:20.161Z"
                                    },
                                    "id": "1ebdbf70-86de-4c80-b428-3facf5db9a4b",
                                    "note": ""
                                }
                            ]
                        },
                        "id": "1a436ce3-89de-4de6-9661-2a796f891207",
                        "note": ""
                    }, {
                        "condition": {
                            "id": "07ea3b38-6e99-4137-bf49-b0ccf06fc5ce",
                            "statementType": "ALWAYS_TYPE",
                            "processingItems": [{
                                    "transition": {
                                        "id": "d239bdad-f482-4eac-a6cf-21231d7f2a04",
                                        "transitionType": "GO_TO",
                                        "eventId": "",
                                        "label": "GoTo",
                                        "projectId": "14174",
                                        "eventLog": "",
                                        "nodeId": "a871dba9-96e0-4931-9fad-f90348411d4b"
                                    },
                                    "id": "352b3006-f970-4021-b0c7-0250fac00ba3",
                                    "note": ""
                                }
                            ]
                        },
                        "id": "29c3a960-3ba1-45f8-82e2-07277fc42347",
                        "note": ""
                    }
                ]
            }
        },
        "projectId": "14174",
        "lastModified": "2020-05-26T23:09:21.061Z",
        "parentNodeId": "4cac2516-7001-4f05-969d-e0ff284ebd9b"
    },
    "view": {
        "name": "",
        "style": ""
    },
    "timestamp": "2020-05-26T22:53:00.591Z"
}

A message node is used to play or display a message. In a node object, the message node element is identified with this key: messageNode.

Element Type Description
name String Name of the node
description String Description of the node
processingItems Processing item group object List of processing items
view View object Formatting information to pass to the client application—Future use
timestamp String Date and time of the last modification

Decision node

Decision node example

{
    "name": "Collect special coffee types?",
    "description": "",
    "processingItems": {
        "id": "0b375e09-a5b6-42a3-9a0b-241eebfdc5a3",
        "channelProcessingItemsMap": {
            "3a48fded-7e74-4586-9cbc-34ed7e25d051": {
                "processingItems": [{
                        "condition": {
                            "id": "03db128d-a155-44c7-b71e-13a8d6295e07",
                            "statementType": "IF_TYPE",
                            "expression": {
                                "id": "c2a21080-a6ab-4cc9-9783-c547a54cbd86",
                                "leftVariable": {
                                    "id": "2ad47c75-5668-40a5-a16b-763a4ff8993a",
                                    "name": "gotSpecial",
                                    "description": "Look up special coffee types (only required once per session)",
                                    "possibleValues": ["true", "false"],
                                    "projectId": "16996",
                                    "uiDefaultValue": "",
                                    "isReserved": false,
                                    "simpleVariableType": "BOOLEAN_TYPE",
                                    "timestamp": "2020-07-20T22:12:50.177Z"
                                },
                                "projectId": "16996",
                                "relationalOperator": "EQUAL_OPERATOR",
                                "rightConstant": "false",
                                "lastModified": "2020-07-20T22:11:13.918Z"
                            },
                            "processingItems": [{
                                    "transition": {
                                        "id": "4271412d-8462-451e-9401-08ecf415fa0e",
                                        "transitionType": "GO_TO",
                                        "eventId": "",
                                        "label": "Look up special coffee types",
                                        "projectId": "16996",
                                        "eventLog": "",
                                        "nodeId": "ccc935bb-d134-4cd2-b035-ffaceecc91fd"
                                    },
                                    "id": "f1e5ea6d-d2dd-4cc8-ac0b-84c67d7bf564",
                                    "note": ""
                                }
                            ]
                        },
                        "id": "75d63d76-c5f8-4af5-9126-98ae607664be",
                        "note": ""
                    }, {
                        "condition": {
                            "id": "5ce31bd7-1f7f-473a-9d99-5c53af0b0397",
                            "statementType": "ELSE_TYPE",
                            "processingItems": [{
                                    "transition": {
                                        "id": "34682dfe-e653-421b-ba22-54ad1fdc66a3",
                                        "transitionType": "GO_TO",
                                        "eventId": "",
                                        "label": "Special types already available",
                                        "projectId": "16996",
                                        "eventLog": "",
                                        "nodeId": "57531148-1ed8-40d2-b4a5-88bf5ea9f5bb"
                                    },
                                    "id": "fa5dc485-b9bb-4f89-b6ef-14c7c1bf8259",
                                    "note": ""
                                }
                            ]
                        },
                        "id": "bd75e136-6666-465e-8c25-3b753cdeab67",
                        "note": ""
                    }
                ]
            }
        },
        "projectId": "16996",
        "lastModified": "2020-07-21T01:07:54.431Z",
        "parentNodeId": "14745f1e-2821-459e-8183-62ef6fbead87"
    },
    "timestamp": "2020-07-20T22:10:54.245Z"
}

In a decision node, the application applies logic or conditions to determine what to do next, without doing a data access call, and without speaking/providing output to the user. In a node object, the decision node element is identified with this key: decisionNode.

Element Type Description
name String Name of the node
description String Description of the node
processingItems Processing item group object List of processing items
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

Data access node

Data access node example

{
 "name": "CityServedLookup",
 "description": "",
 "outputVariables": [{
         "id": "7e2f3b11-acb5-44ea-b32a-161f57709d4d",
         "name": "isValid",
         "description": "",
         "possibleValues": ["true", "false"],
         "projectId": "4826",
         "uiDefaultValue": "",
         "isReserved": false,
         "simpleVariableType": "BOOLEAN_TYPE",
         "timestamp": "2020-02-21T23:13:09.919Z"
     }, {
         "id": "339f0ed7-e1bb-49d7-997e-7e5e20451b96",
         "name": "returnCode",
         "description": "The return code variable for data access nodes",
         "possibleValues": [],
         "projectId": "4826",
         "uiDefaultValue": "",
         "isReserved": true,
         "simpleVariableType": "STRING_TYPE",
         "timestamp": "2020-02-21T20:03:17.100Z"
     }
 ],
 "serviceName": "CityServedLookup",
 "externalFetchEnabled": true,
 "successNodeId": "f58ff2aa-2799-42be-b767-921e8c362d05",
 "failureNodeId": "d51890ba-4966-4944-8842-7624089526f9",
 "inputVariablesConcepts": [{
         "concept": {
             "id": "49bba22e-e66b-44e4-b097-813f3991276b",
             "projectId": "4826",
             "name": "CITY",
             "isInBaseOntology": false,
             "valuesCount": 0,
             "dialogTypeId": "",
             "isDialogType": false,
             "predefinedConceptId": "",
             "isDeprecated": false
         }
     }
 ],
 // backend connection overrides...
 "timestamp": "2020-02-22T00:08:36.748Z"
}

A data access node exchanges information with an external system, typically by retrieving information from a database or application. In a node object, the data access node element is identified with this key: dataAccessNode.

Element Type Description
name String Name of the node
description String Description of the node
inputVariables Array of variables Deprecated
outputVariables Array of variables One or more variables to be returned by the backend system
processingItems Processing item group object Deprecated
serviceName String Service name of the data access node
externalFetchEnabled Boolean true if the data access layer uses an external service to get the data; otherwise false
successNodeId String UUID of the node to transition to if the query to the backend system succeeded
failureNodeId String UUID of the node to transition to if the query to the backend system query failed
inputVariablesConcepts Array of inputs Key-value pairs representing the input variables and entities to pass on to the backend system
urlExtension String URL extension
fetchTimeout Number Fetch timeout in milliseconds
connectTimeout Number Connection timeout in milliseconds
methodType String Method; one of: POST, GET, PUT, DELETE, PATCH, NOT_SET
dressAliasId String Numeric ID of the connection profile for the backend system—Future use
dressName String Deprecated (superseded by dressAliasId)
headers Object Headers used to query the backend system, as key-value pairs
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

Input

Represents information to send to a backend system (from a data access node) or to the client application (from an external actions node or from a question and answer node).

Element key Value type Description
concept Entity Entity to pass on to the backend system
variable Variable Variable to pass on to the backend system

Question router node

Question router node example

{
    "name": "Get Order Details",
    "description": "",
    "initialTransition": {
        "id": "1c5a3cc6-fa36-4c25-8342-85006df9e1a1",
        "channelProcessingItemsMap": {
            "ad2f4be3-9cf6-413c-99c0-9e0d2a60d706": {
                "processingItems": []
            }
        },
        "projectId": "3402",
        "lastModified": "2020-02-10T22:38:51.301Z",
        "parentNodeId": "fd8d80d6-9968-4b21-a7e7-41bbaf54161a"
    },
    "finalTransition": {
        "id": "0ac6d1db-2649-41f2-b66e-89b1b00cd085",
        "channelProcessingItemsMap": {
            "ad2f4be3-9cf6-413c-99c0-9e0d2a60d706": {
                "processingItems": [{
                        "transition": {
                            "id": "739ce6d9-4138-4c5c-80c7-6c80676e1754",
                            "transitionType": "RETURN",
                            "event": "",
                            "label": "Complete",
                            "projectId": "3402"
                        },
                        "id": "cba5ee27-a228-47f7-a11c-59307991b710",
                        "note": ""
                    }
                ]
            }
        },
        "projectId": "3402",
        "lastModified": "2020-02-10T22:38:51.355Z",
        "parentNodeId": "fd8d80d6-9968-4b21-a7e7-41bbaf54161a"
    },
    "concepts": [{
            "conceptId": "f38ee7a6-4296-4d1c-b7c7-7b3bb6c8e0e2",
            "collectGotoNodeId": "30797a51-69e5-4100-b7ea-e8929e1fe775",
            "processGotoNodeId": "30797a51-69e5-4100-b7ea-e8929e1fe775",
            "conceptName": "",
            "manualComplete": false
        }, {
            "conceptId": "01276cef-e847-4598-bc6b-0f949eec3f3a",
            "collectGotoNodeId": "53c825aa-27cc-4cd6-be1b-08fa7532e273",
            "processGotoNodeId": "53c825aa-27cc-4cd6-be1b-08fa7532e273",
            "conceptName": "",
            "manualComplete": false
        }
    ],
    "timestamp": "2020-02-10T22:38:51.411Z"
}

A 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. In a node object, the question router node element is identified with this key: controllerNode.

Element Type Description
name String Name of the node
description String Description of the node
initialTransition Processing item group object Optional transition to execute prior to collection
finalTransition Processing item group object Mandatory transition specifying where the flow will proceed after collection is completed
concepts Array of entity references Entities to handle
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

Entity reference

Represents an entity to handle in a question router node.

Element Type Description
conceptId String UUID of the entity
collectGotoNodeId String UUID of the node to go to for collecting the entity
processGotoNodeId String UUID of the node to go to after collection
multiConceptExpression Expression object Optional expression used to determine if the question router node must support multiple mentions for the entity
collectExpression Expression object Optional expression used to determine that the question router node must not skip collection for the entity
conceptName String Name of the entity—legacy element, supported for backward compatibility only
manualComplete Boolean false (default) if the question router node automatically sets the completion status for the entity; otherwise true

Intent mapper node

Intent mapper node example

{
    "name": "Intent Mapper",
    "description": "",
    "intentMappings": {
        "c19a0bcb-3bd9-4f7a-b5fa-80926cd25476": {
            "componentId": "ca53b46a-e54f-4ffb-aca3-e565a263a091"
        },
        "68f5cd24-1cb3-4b61-80e5-6f25d0cf0564": {
            "componentId": "0a33bd61-ee9e-4cf9-a3d9-b550af78864b"
        },
        "bacfe612-d642-47df-8942-266880013dd6": {
            "nodeId": "3241a66b-96cb-4a54-8baa-fe4cbbc5d19d"
        },
        "5d39f071-f958-46e7-a6c0-2c038779ae4e": {
            "componentId": "d0d9900e-8881-4b9d-a545-ec844cf10bdb"
        }
    },
    "transition": {
        "id": "c2ef0247-2b69-4570-8807-a9685e0013cc",
        "transitionType": "GO_TO",
        "event": "",
        "label": "On Return",
        "projectId": "480",
        "nodeId": "389bba31-9825-4406-8e45-e7b0d2e38561"
    },
    "intentNames": {
        "bacfe612-d642-47df-8942-266880013dd6": "Goodbye",
        "5d39f071-f958-46e7-a6c0-2c038779ae4e": "LostBaggage",
        "68f5cd24-1cb3-4b61-80e5-6f25d0cf0564": "FlightStatus",
        "c19a0bcb-3bd9-4f7a-b5fa-80926cd25476": "BookFlight"
    },
    "timestamp": "2019-10-22T22:56:00.726Z"
}

The intent mapper node handles data for NLU/call routing menus. In a node object, the intent mapper node element is identified with this key: intentMapperNode.

Element Type Description
name String Name of the node
description String Description of the node
intentMappings Object Key-value pairs mapping intent UUIDs to their destination (UUID of an intent component)
transition Transition object Specifies what happens when the dialog flow returns from an intent component after the interaction associated with a specific intent is complete
intentNames Object Key-value pairs mapping intent UUIDs to their name
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

Component call node

Component call node example

{
    "name": "Call USER_AUTH",
    "description": "",
    "componentId": "51763ab1-6f4e-4e51-86a1-999298c069ba",
    "processingItems": {
        "id": "7b5394bc-ce0c-4c64-b92b-88cf19525b2a",
        "channelProcessingItemsMap": {
            "7bd3a008-1ad6-4d7f-9d3d-1a484e0061a9": {
                "processingItems": [{
                        "condition": {
                            "id": "a6f79077-d545-41c7-b6c0-50acf16e7ca4",
                            "statementType": "ALWAYS_TYPE",
                            "processingItems": [{
                                    "transition": {
                                        "id": "77739eca-6eca-45e9-9984-b4515b096761",
                                        "transitionType": "GO_TO",
                                        "event": "",
                                        "label": "GoTo",
                                        "projectId": "3773",
                                        "nodeId": "4423288f-55f6-4687-bc75-9ad69ffd797a"
                                    },
                                    "id": "558d508f-72de-4a05-b860-d87c5394aaf1",
                                    "note": ""
                                }
                            ]
                        },
                        "id": "fb57e02c-a85d-456c-8ac5-879f7bd7163a",
                        "note": ""
                    }
                ]
            }
        },
        "projectId": "3773",
        "lastModified": "2020-04-22T22:55:03.485Z",
        "parentNodeId": "4b9ca886-1fc3-4ed9-95e5-703039edc374"
    },
    "timestamp": "2020-04-22T22:55:03.521Z"
}

A component call node allows a dialog flow to enter another component and is also the point of a return from that component. In a node object, the component call node element is identified with this key: componentNode.

Element Type Description
name String Name of the node
description String Description of the node
componentId String UUID of the component to invoke
processingItems Processing item group object List of processing items
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

Start node

Start node example

{
    "name": "start",
    "description": "",
    "processingItems": {
        "id": "57adfcf2-13cc-4ab8-b307-052ce5f103e8",
        "channelProcessingItemsMap": {},
        "projectId": "480",
        "lastModified": "2019-10-21T20:51:08.470Z",
        "parentNodeId": "f3a2ba66-a61f-47b6-bcad-74047a5abb09"
    },
    "nodeId": "375b8e57-2241-44ef-83df-6daa706d38a5",
    "timestamp": "2019-10-22T01:57:37.328Z"
}

The Start node represents the beginning of an application. In a node object, the start node element is identified with this key: startNode.

Element Type Description
name String Name of the node
description String Description of the node
processingItems Processing item group object List of processing items
nodeId String UUID of the next node in the dialog flow
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

External actions node

External actions node example

{
    "inputVariablesConcepts": [],
    "outputVariables": [],
    "successTransition": {
        "id": "7100ec91-2a80-404f-b7b0-50f8b574aacd",
        "transitionType": "GO_TO",
        "eventId": "",
        "label": "Success",
        "projectId": "10610",
        "eventLog": "",
        "nodeId": "1019f0c6-5e94-42b0-93be-798647b78c01"
    },
    "failureTransition": {
        "id": "f1399b28-0302-406b-b526-69854688e831",
        "transitionType": "GO_TO",
        "eventId": "",
        "label": "Failure",
        "projectId": "10610",
        "eventLog": "",
        "nodeId": "85695b1f-05b9-457b-844c-6ee867dc484c"
    },
    "name": "Transfer",
    "actionType": "ESCALATE",
    "description": "",
    "timestamp": "2020-04-17T19:05:26.632Z"
}

The external actions node represents actions to be performed when ending a conversation, transferring to another system, or escalating to a live agent. In a node object, the external actions node element is identified with this key: externalactionNode.

Element Type Description
name String Name of the node
actionType String Either END or ESCALATE
description String Description of the node
inputVariablesConcepts Array of inputs Key-value pairs representing the input variables and entities to be passed on to a client application
outputVariables Array of variables One or more variables to be returned by the client application
successTransition Transition object Only present if actionType is ESCALATE; transition to perform if the client application returns with a success status
failureTransition Transition object Only present if actionType is ESCALATE; transition to perform if the client application returns with a failure status—Not yet supported
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

End node

The end node is a deprecated element, supported for backward compatibility only. Use external actions nodes instead. In a node object, the end node element is identified with this key: endNode.

Transfer node

The transfer node is a deprecated element, supported for backward compatibility only. Use external actions nodes instead. In a node object, the transfer node element is identified with this key: transferNode.

Variable

Variable example

{
    "id": "e7c2b41d-66d9-4af7-a052-56de8d52b488",
    "name": "firstTime",
    "description": "",
    "possibleValues": ["true", "false"],
    "projectId": "1064",
    "uiDefaultValue": "",
    "isReserved": false,
    "simpleVariableType": "BOOLEAN_TYPE",
    "timestamp": "2020-01-29T02:28:30.677Z"
}

Represents a variable used in the project.

Element Type Description
id String UUID of the variable
name String Name of the variable
description String Description of the variable
possibleValues Array of strings Valid values for the variable
projectId String ID of the project
uiDefaultValue String Value to be used during preview in the in Mix.dialog Try tab
isReserved Boolean true for reserved variables; otherwise false
simpleVariableType String Only present for simple variables; one of: STRING_TYPE, BOOLEAN_TYPE, DATE_TYPE, TIME_TYPE, DECIMAL_TYPE, INTEGER_TYPE, LIST_TYPE, DYNAMIC_ENTITY_DATA
simpleGenericType String Only present for simple variables where simpleVariableType is LIST_TYPE; indicates the type of the items in the list
complexVariableTypeId String Only present for complex variables; UUID of the schema for this complex variable
timestamp String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z

Schema

Schema example

{
    "id": "5f044809-ffad-44cc-ad58-773d6b04bcd3",
    "name": "myOrder",
    "description": "item, quantity, unitPrice, isReady",
    "fields": [
            //   one or more simple variables...
    ],
    "projectId": "1064",
    "isReserved": false
}

Represents a complex variable schema in the project.

Element Type Description
id String UUID of the schema
name String Name of the schema
description String Description of the schema
fields Array of variables One or more simple variables
projectId String Unique ID of the parent project
isReserved Boolean True for a reserved schema; otherwise false

Prompt group

Prompt group example

{
    "id": "0f124266-6863-4f76-9ff3-bf6311393119",
    "name": "EQvRcimT7cLH_prompt",
    "prompts": [{
            "payload": {
                "displayText": "Would you like beef, chicken, mushroom, or pepperoni?",
                "ttsText": "",
                "audioFile": ""
            },
            "language": "en-US",
            "channel": "93219d83-768f-4bff-bbe2-07c24a9b5d96",
            "lastModified": "2019-10-12T01:01:48.800Z"
        }
    ],
    "projectId": "903",
    "lastModified": "2019-10-12T01:01:48.800Z"
}

Represents a group of related prompts used in the project.

Element Type Description
id String UUID of the prompt group
name String Name of the prompt group
prompts Array of prompts Prompts in the prompt group
projectId String ID of the project
lastModified String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-10-17T20:55:38.488Z

Prompt

Prompt example

{
    "payload": {
        "displayText": "Would you like beef, chicken, mushroom, or pepperoni?",
        "ttsText": "",
        "audioFile": ""
    },
    "language": "en-US",
    "channel": "93219d83-768f-4bff-bbe2-07c24a9b5d96",
    "lastModified": "2019-10-12T01:01:48.800Z"
}

Represents a prompt in a prompt group.

Element Type Description
payload Prompt payload object Payload of the prompt
language String Locale of the prompt, as a 4-letter language code (for example, en-US)—refer to Languages and Voices for the list of languages available in the current version of Nuance Mix
channel String UUID of the channel
lastModified String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-10-17T20:55:38.488Z

Prompt payload

Prompt payload example

{
    "displayText": "How can I help you today?",
    "ttsText": "",
    "audioFile": "",
    "displayTextAnnotations": [],
    "ttsTextAnnotations": [],
    "ttsAudioBackup": "",
    "ttsAudioBackupAnnotations": []
}

Represents the payload of a prompt.

Element Type Description
displayText String Text to display; the string may include dynamic placeholders in this format: [placeholder text|uuid of a variable], where the variables are listed in the displayTextAnnotations element
ttsText String Text to render using text-to-speech; the string may include dynamic placeholders in this format: [placeholder text|uuid of a variable], where the variables are listed in the ttsTextAnnotations element
audioFile String Audio file to play
displayTextAnnotations Array of annotations Dynamic content to include in the text to display
ttsTextAnnotations Array of annotations Dynamic content to render using text-to-speech
ttsAudioBackup String Audio backup text to render using text-to-speech; the string may include dynamic placeholders in this format: [placeholder text|uuid of a variable], where the variables are listed in the ttsAudioBackupAnnotations element
ttsAudioBackupAnnotations Array of annotations Dynamic content to include in the audio backup text

Annotation

Annotation example

{
    "variable": {
        "id": "5b8382ef-ce06-45e3-9c2b-e488ffd745c2",
        "name": "customerFirstName",
        "description": "",
        "possibleValues": [],
        "projectId": "824",
        "uiDefaultValue": "",
        "simpleVariableType": "STRING_TYPE",
        "timestamp": "2019-11-26T23:11:43.065Z"
    },
    "type": "",
    "properties": {
        "string": "customer"
    }
}

Represents an dynamic placeholder in a prompt payload.

Element Type Description
variable Variable object Variable that contains dynamic content to include in the message
type String
properties Object Key-value pair where the key is “string” and the value is the placeholder text in the message

Processing item group

Processing item group example, with transition, condition, and prompt items

{
    "id": "202141ef-2d18-429c-b1ca-7ee7c74dac56",
    "channelProcessingItemsMap": {
        "f0ae55f8-e38f-47d2-9c69-bfe7ea3c6b51": {
            "processingItems": [{
                    "condition": {
                        "id": "5a64610d-849e-4950-8311-a03998495b28",
                        "statementType": "ALWAYS_TYPE",
                        "processingItems": [{
                                "promptGroup": {
                                    "id": "0388213d-e1a2-486c-9eb3-593d1b6f3017",
                                    "name": "yDAWO6Wd5PXH_prompt",
                                    "prompts": [{
                                            "payload": {
                                                "displayText": "Where are you flying from?",
                                                "ttsText": "Where are you flying from?",
                                                "audioFile": "",
                                                "displayTextAnnotations": [],
                                                "ttsTextAnnotations": []
                                            },
                                            "language": "en-US",
                                            "channel": "f0ae55f8-e38f-47d2-9c69-bfe7ea3c6b51",
                                            "lastModified": "2019-11-06T20:12:09.643Z"
                                        }
                                    ],
                                    "projectId": "568",
                                    "lastModified": "2019-11-06T20:12:09.663Z"
                                },
                                "id": "c6b63702-3314-4744-9918-45b4c10b4934"
                            }
                        ]
                    },
                    "id": "0f937bbb-b820-43b7-9e7b-eb0a3f3fab9c"
                }
            ]
        }
    },
    "projectId": "568",
    "lastModified": "2019-11-06T20:12:05.154Z",
    "parentNodeId": "02a889a3-dea2-4663-8ddb-59caa738a084"
}

Represents processing items to perform.

Element Type Description
id String UUID of the processing item group
channelProcessingItemsMap Object Processing items to perform for each channel; contains elements of type prompt, action, condition, and transition
projectId String ID of the project
lastModified String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-08-21T08:34:27Z
parentNodeId String UUID of the parent node

Processing item

Processing item example of type condition, with an assign action and a prompt group

{
    "condition": {
        "id": "f5d2e1dc-4e25-4420-910f-744032b920e5",
        "statementType": "IF_TYPE",
        "expression": {
            "id": "dc9031d3-8149-4f79-85a8-bac70510689e",
            "leftVariable": {
                "id": "75a80a41-1a28-4c3d-b9d5-74593df99d1f",
                "name": "firstTime",
                "description": "",
                "possibleValues": ["true", "false"],
                "projectId": "3785",
                "uiDefaultValue": "",
                "simpleVariableType": "BOOLEAN_TYPE",
                "timestamp": "2019-12-11T02:57:47.541Z"
            },
            "projectId": "3785",
            "relationalOperator": "EQUAL_OPERATOR",
            "rightConstant": "true",
            "lastModified": "2019-12-11T03:16:30.327Z"
        },
        "processingItems": [{
                "action": {
                    "assign": {
                        "lhsVariable": {
                            "id": "75a80a41-1a28-4c3d-b9d5-74593df99d1f",
                            "name": "firstTime",
                            "description": "",
                            "possibleValues": ["true", "false"],
                            "projectId": "3785",
                            "uiDefaultValue": "",
                            "simpleVariableType": "BOOLEAN_TYPE",
                            "timestamp": "2019-12-11T02:57:47.541Z"
                        },
                        "constant": "false"
                    }
                },
                "id": "1d7d0fae-22c3-4a1f-ae7e-1ee1f831e602",
                "note": ""
            }, {
                "promptGroup": {
                    "id": "7d4fe223-be8c-45e5-ad86-240780fbf273",
                    "name": "BypiLk2FGAvv_prompt",
                    "prompts": [{
                            "payload": {
                                "displayText": "How can I help?",
                                "ttsText": "",
                                "audioFile": "",
                                "displayTextAnnotations": [],
                                "ttsTextAnnotations": []
                            },
                            "language": "en-US",
                            "channel": "18b287ca-7427-4bcc-bb61-2d405261c6e8",
                            "lastModified": "2019-12-11T03:16:54.539Z"
                        }
                    ],
                    "projectId": "3785",
                    "lastModified": "2019-12-11T03:16:54.536Z"
                },
                "id": "d2b4683b-1411-4e3a-8010-02866cb8ff13",
                "note": ""
            }
        ]
    },
    "id": "d5c6e2e2-a331-46ed-b464-96cc4edbd591",
    "note": ""
}

Represents a processing item in a processing item group.

Element Type Description
processing item Object One of the supported processing item types
id String UUID of the processing item
note String Designer’s notes such as a description or reminders (maximum 4000 characters)

Supported processing item types

Mix.dialog supports these types of processing item:

Element key Processing item type Description
condition Condition Sets a condition (such as if, else if, else) to control the dialog flow
action Action Performs one of these actions: assign a value to a variable or set a log message
promptGroup Prompt group Sets a prompt
transition Transition Sets a transition to another node

Expression

Expression example

{
    "id": "f11100d5-13d5-4310-9628-d8911c3b133e",
    "leftExpression": {
        "id": "a114fb86-209b-4d2d-8068-2850d0867ca0",
        "projectId": "3534",
        "relationalOperator": "EQUAL_OPERATOR",
        "rightConstant": "ristretto",
        "lastModified": "2020-04-18T01:24:17.138Z",
        "leftConceptId": "48515a0c-b1f9-44c4-ac0b-2f7f2bad82e6"
    },
    "rightExpression": {
        "id": "4e38c0cc-3422-4591-9b00-55023a8e80df",
        "projectId": "3534",
        "relationalOperator": "NOT_EQUAL_OPERATOR",
        "lastModified": "2020-04-18T01:32:24.337Z",
        "leftConceptIdLiteral": "48515a0c-b1f9-44c4-ac0b-2f7f2bad82e6",
        "rightSpecialOperand": "NULL"
    },
    "projectId": "3534",
    "logicalOperator": "AND_OPERATOR",
    "lastModified": "2020-04-18T01:32:41.619Z"
}

Represents an expression used in the project. An expression can be evaluated in the code. It is usually part of a condition and is composed of:

Element Type Description
id String UUID of the expression
leftExpression Expression object Expression used as the left operand
leftVariable Variable object Variable used as the left operand
leftConceptId String UUID of the entity whose value is used as the left operand
leftConceptIdLiteral String UUID of the entity whose literal is used as the left operand
leftSpecialOperand String Special value used as the left operand (only supported is NULL)
logicalOperator String One of: NO_LOGICAL_OPERATOR, AND_OPERATOR, OR_OPERATOR
mathematicalOperator String One of: NO_OP, PLUS, MINUS, TIMES, DIVIDE, MOD
relationalOperator String One of: NO_RELATIONAL_OPERATOR, EQUAL_OPERATOR, NOT_EQUAL_OPERATOR, LESS_OPERATOR, GREATER_OPERATOR, LESS_EQUAL_OPERATOR, GREATER_EQUAL_OPERATOR
rightConstant String Constant used as the right operand
rightExpression Expression object Expression used as the right operand
rightVariable Variable object Variable used as the right operand
rightSpecialOperand String Special value used as the right operand (only supported is NULL)
projectId String ID of the project
lastModified String Date and time of the last modification, in this format: YYYY-MM-DD hh:mm:ssZ—for example, 2019-10-17T20:55:38.488Z

Action

In a processing item, an action element is identified with this key: action.

An action object represents an assign action, an entity update action, or a log action.

Assign action

Assign action example, where the Boolean variable isNew is set to true

{
    "lhsVariable": {
        "id": "65cd23c6-91d7-4de2-ab4e-95263a65ccd1",
        "name": "isNew",
        "description": "",
        "possibleValues": ["true", "false"],
        "projectId": "29960",
        "uiDefaultValue": "",
        "isReserved": false,
        "simpleVariableType": "BOOLEAN_TYPE",
        "timestamp": "2020-04-15T16:51:59.437Z"
    },
    "constant": "true"
}

Assigns a value to a variable or entity.

In an action object, an assign action is identified with this key: assign.

Element Type Description
lhsVariable Variable object Variable to set
value to set String This can be a constant, a specialOperand (only supported is NULL), another variable or an expression

Entity update action

Entity update action example, where an entity is cleared

{
    "conceptId": "1a5559c6-07b8-49af-b150-1a924f6b78f5",
    "clearConcept": true
}

Entity update action example, where the .isCompleted attribute of an entity is set to false

{
    "conceptId": "4282658e-34af-4cec-8e22-d92d953e34d9",
    "conceptUpdate": {
        "requiredStatus": "UNCHANGED",
        "completeStatus": "FALSE",
        "confirmStatus": "UNCHANGED"
    }

Updates the .isRequired, .isCompleted, or .isConfirmed attribute of an entity, or clears the entity completely.

In an action object, an entity update action is identified with this key: conceptAction.

Element Type Description
conceptId String UUID of the entity
clearConcept Boolean Only present if the action is to clear the entity; always true
conceptUpdate Object Key-values pair where the keys requiredStatus, completeStatus, and confirmStatus represent the three entity attributes .isRequired, .isCompleted, and .isConfirmed; and the values are one of UNCHANGED, TRUE, or FALSE.

Note: Clearing an entity sets its value to NULL, .isRequired to true, .isConfirmed and .isCompleted to false.

Log action

Sets a formatted log message and includes variables to pass into the log message.

In an action object, a log action is identified with this key: log.

Element Type Description
msg String Log message
variable Array of variables Variables to use for the log message

Condition

Condition example

{
    "id": "870fedef-5f96-4565-82be-1d06c506dee0",
    "statementType": "IF_TYPE",
    "expression": {
        "id": "8b098b8a-5554-4265-93ba-204144c75100",
        "leftVariable": {
            "id": "287f8839-94ce-4e29-85d5-f718402cc66b",
            "name": "returnCode",
            "description": "",
            "possibleValues": [
                "0",
                "1"
            ],
            "projectId": "893",
            "simpleVariableType": "STRING_TYPE",
            "timestamp": "2019-09-09T17:58:44.917Z"
        },
        "projectId": "893",
        "relationalOperator": "EQUAL_OPERATOR",
        "rightConstant": "0",
        "lastModified": "2019-09-09T17:58:46.224Z"
    },
    "processingItems": [{
            "transition": {
                "id": "8a2d6399-05f5-4f11-80cc-c5b20059b03b",
                "transitionType": "GO_TO",
                "event": "go to",
                "label": "Success Payment",
                "nodeId": "71c93541-dbde-450f-a153-f2409de26705"
            }
        }
    ]
}

Represents a condition in a processing item.

Element Type Description
id String UUID of the condition
statementType String Type of condition—one of: NO_TYPE, IF_TYPE, ELSEIF_TYPE, ELSE_TYPE, ALWAYS_TYPE
expression Expression object Expression to evaluate (for IF_TYPE and ELSEIF_TYPE conditions)
processingItems Array of processing items Processing items to run if the condition is true

Transition

Transition example (GoTo)

{
    "id": "6ea55136-0879-487f-af10-62b83389b2c3",
    "transitionType": "GO_TO",
    "eventId": "",
    "label": "Always",
    "projectId": "480",
    "nodeId": "97a91ff7-6e98-49a7-ae2e-f8dc62c9a8b3"
}

Transition example (throw)

{
    "id": "8347f5c0-b755-4526-a3f4-24720e253428",
    "transitionType": "THROW",
    "eventId": "295420a0-7675-4917-9329-35e26654ed05",
    "label": "",
    "projectId": "3534",
    "eventLog": "Caught generic event"
}

Represents a transition in a processing item, or in an event handler.

Element Type Description
id String UUID of the transition
transitionType String Type of transition; one of: GO_TO, GO_BACK_TO, RETURN,RETURN_TO_INTENT_MAPPER, THROW, NO_TRANSITION_TYPE
eventId String For transition type THROW: event string to be thrown and then caught elsewhere
eventLog String For transition type THROW: description or text to be logged when the event is thrown
label String Descriptive label for the transition; limited to 63 characters
projectId String ID of the project
nodeId String For transition type GO_TO and GO_BACK_TO: UUID of the destination node

Refer to the Mix.dialog documentation for more information on the transition types.

Ontology

Ontology example

{
    "projectId": "2942",
    "intents": [{
            "id": "9ac597e9-450f-47a5-a3de-a6a9fd0cc2c6",
            "projectId": "2942",
            "name": "NO_INTENT",
            "conceptIds": [],
            "isInBaseOntology": true,
            "lastModified": "1970-01-01T00:00:00Z"
        }, {
            "id": "8397e323-1964-4843-91e8-e11717c4553e",
            "projectId": "2942",
            "name": "ORDER_COFFEE",
            "conceptIds": ["fc5b8a5e-440b-4460-9e29-f8fafa546abd", "7a282252-f57f-4b30-8b92-25129c363490"],
            "isInBaseOntology": false,
            "lastModified": "1970-01-01T00:00:00Z"
        }
    ],
    "concepts": [{
            "id": "ce1aea9d-4825-4041-b2fa-b19e6f8159de",
            "projectId": "2942",
            "name": "AND",
            "isInBaseOntology": true,
            "valuesCount": 0,
            "dialogTypeId": "",
            "isDialogType": false,
            "predefinedConceptId": "",
            "isDeprecated": false,
            "lastModified": "1970-01-01T00:00:00Z"
        }, {
            "id": "523e9a85-d807-4f6b-a76a-772b26b3645c",
            "projectId": "2942",
            "name": "CC_EXP_DATE",
            "isInBaseOntology": false,
            "valuesCount": 0,
            "dialogTypeId": "",
            "isDialogType": true,
            "predefinedConceptId": "",
            "isDeprecated": false,
            "numberOfTypeUsages": 0,
            "isA": "cd0d3edb-2b03-4e3e-bf56-1d773cd94c88",
            "lastModified": "1970-01-01T00:00:00Z"
        }, {
            "id": "fc5b8a5e-440b-4460-9e29-f8fafa546abd",
            "projectId": "2942",
            "name": "COFFEE_SIZE",
            "isInBaseOntology": false,
            "valuesCount": 4,
            "dialogTypeId": "",
            "isDialogType": false,
            "predefinedConceptId": "",
            "isDeprecated": false,
            "numberOfTypeUsages": 0,
            "lastModified": "1970-01-01T00:00:00Z"
        },  // more entity types...
           {
            "id": "572bcd5c-e65d-4a5d-b12c-9e6e85f56973",
            "projectId": "2942",
            "name": "nuance_TEMPERATURE",
            "isInBaseOntology": true,
            "valuesCount": 0,
            "dialogTypeId": "",
            "isDialogType": false,
            "predefinedConceptId": "",
            "isDeprecated": false,
            "numberOfTypeUsages": 0,
            "lastModified": "1970-01-01T00:00:00Z"
        }
    ],
    "lastModified": "1970-01-01T00:00:00Z"
}

Represents the ontology used for this project.

Element Type Description
projectId String ID of the project
intents Array of intents Intents in the project
concepts Array of entities Entities in the project
lastModified String Future use

Intent

Represents an intent in the project.

Element Type Description
id String Unique ID of the intent
projectId String ID of the project
name String Name of the intent
conceptIds Array UUIDs of the entities for the intent
isInBaseOntology Boolean true for a predefined intent; false for a custom intent
lastModified String Not used

Entity

Represents an entity in the project.

Element Type Description
id String UUID of the entity
projectId String ID of the project
name String Name of the entity
isInBaseOntology Boolean true for a predefined entity; false for a custom entity
valuesCount Number Number of values for the entity
dialogTypeId String For an isA relationship entity of a predefined dialog entity, UUID of the highest-level parent entity
isDialogType Boolean true for a predefined dialog entity; otherwise false
predefinedConceptId String For an isA relationship entity of a predefined entity, UUID of the highest-level parent entity
isDeprecated Boolean true for a deprecated dialog entity; otherwise false
numberOfTypeUsages Number For a predefined entity or dialog entity, number of custom entities that have an isA relationship to this entity; otherwise 0
isA String Only present for relationship entities; UUID of the parent entity
lastModified String Not used

Change log

Below are changes made to the Dialog Application Specification documentation since the initial Beta release.

2020-07-20

Added JSON example for decision node

2020-07-13

2020-05-26

2020-05-14

2020-05-06

2020-05-01

Added eventHandlers to Node

2020-04-30

2020-04-01

2020-03-04

2020-02-19

2020-02-05

Updated Variable, Schema, and Project object sections to match changes in the dialog model structure supporting reserved variables and schemas.

2019-12-11

Updated Processing item section.

2019-12-02

Updated to match changes to the dialog model structure.

2019-11-15

Content reorganized and revised to match changes to the dialog model structure.