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.

Specification

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": [
        // channels in the project...
    ],
    "supportedCustomChannels": [],
    "richTextChannels": [],
    "globalConfirmations": [],
    "components": [{
            "id": "718ced73-350f-4ed9-b389-823fb405a096",
            "name": "Main",
            "description": "Main component",
            "nodes": [
                //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": [
        // prompt groups (messages) in the project...
    ],
    "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...
    ],
    "dressAliases": [],
    "globalSettingOverrides": [
        // overrides to global settings in the project...
    ],
    "ndfVersion": "",
    "projectIntentMappings": [
        // global intent mappings...
    ],
    "enginePackVersion": "",
    "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 Deprecated (superseded by globalSettingOverrides)
backendConfig Array of backend connection presets 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
dressAliases Array of data host aliases Data host aliases
globalSettingOverrides Array of global setting overrides Overrides to the default global settings for the project
ndfVersion String Version of the Dialog runtime service to target when building the application—Future use
projectIntentMappings Array of project intent mapping objects Global mappings from intents to components
enginePackVersion String Engine pack version for projects in self-hosted Mix environments (default is hosted; assumed to be hosted if not specified)—Future use
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

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 Deprecated (event includes the escalation level)
processingItemsList Processing item group object Processing items to perform
enabled Boolean true if the global recovery behavior is enabled; otherwise false

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

Global setting override

Global setting override example

{
    "id": "8c049c86-3ea4-4ef6-810f-ae1ba17efac3",
    "projectId": "8268",
    "settingName": "extension",
    "settingType": "AUDIO_SETTINGS",
    "channelId": "3a45d5e0-e0da-4236-98cd-d39cf2881bb7",
    "predefinedName": "PREDEFINE_NOT_SET",
    "value": ".ulaw",
    "language": "",
    "entityId": ""
}

Represents an override to the global settings defaults in the project.

Element Type Description
id String UUID of the setting override
projectId String ID of the project
settingName String Name of the setting
settingType String Setting category—one of: COLLECTION_SETTINGS, CONFIRMATION_SETTINGS, DTMF_SETTINGS, TTS_SETTINGS, SPEECH_SETTINGS, CONVERSATION_SETTINGS, AUDIO_SETTINGS, GRAMMAR_SETTINGS
channelId String UUID of the channel for the override
predefinedName String For an entity-level setting override: type of entity—one of: CUSTOM_LIST_TYPE, REGEX, FREE_FORM, DATE, TIME, YES_NO, NUANCE_AMOUNT, NUANCE_BOOLEAN, NUANCE_CARDINAL_NUMBER, NUANCE_DISTANCE, NUANCE_DOUBLE, NUANCE_EXPIRY_DATE, NUANCE_GENERIC_ORDER, NUANCE_NUMBER, NUANCE_ORDINAL_NUMBER, NUANCE_TEMPERATURE; otherwise PREDEFINE_NOT_SET
value String Override value
language String Language to which the override applies, 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
entityId String For an entity-level setting override: UUID of the entity to which the override applies; otherwise empty

Project intent mapping

Project intent mapping example

{
    "id": "95573456-5c8e-4de1-93e2-190fe13a80a7",
    "projectId": "17512",
    "intentId": "3478f442-8f6e-483d-8efd-8cb53208c49e",
    "destination": {
        "componentId": "ae6c8b59-f7bf-4bae-824f-0ed4e054f35a"
    }
}

Represents the global mapping of one intent to a component. Intent mapper nodes inherit these global mappings and can override them if needed.

Element Type Description
id String UUID of the mapping
projectId String ID of the project
intentId String UUID of the intent being mapped
destination Object Key-value pair where the key is componentId and the value is the UUID of the component to which the intent is mapped

Backend connection preset

Backend connection preset example

{
    "id": "895f3667-b02f-4448-84af-2520a4785004",
    "projectId": "24856",
    "name": "myBackend",
    "urlExtension": "/coffee/price",
    "fetchTimeout": 0,
    "connectTimeout": 0,
    "method": "POST",
    "dressName": "525",
    "headers": [{
            "key": "mytoken",
            "variable": {
                "id": "106de6cc-e3ac-457e-bb92-6ae06ef2e1b5",
                "name": "myToken",
                "description": "",
                "possibleValues": [],
                "projectId": "24856",
                "uiDefaultValue": "",
                "isReserved": false,
                "masked": false,
                "timestamp": "2021-04-14T02:55:09.340Z"
            }
        }, {
            "key": "apikey",
            "constant": "5678"
        }
    ],
    "dressAliasId": "525"
}

Represents a backend connection preset to be applied to a data access node for server-side integration.

Element Type Description
id String UUID of the preset
projectId String ID of the project
name String Name of the preset
urlExtension String URL extension (maximum 2000 characters)
fetchTimeout Number Fetch timeout in milliseconds (default: 0)
connectTimeout Number Connection timeout in milliseconds (default: 0)
method String Method; one of: POST, GET, PUT, DELETE, PATCH, NOT_SET (default)
dressName String Deprecated (superseded by dressAliasId)
headers Array of headers Headers used to query the backend system, as key-value pairs
dressAliasId String Numeric ID of the connection profile for the backend system

Data host alias

Data host alias example

{
    "id": "525",
    "alias": "COFFEE_APP",
    "defaultValue": "https://coffee.app.com:443"
}

Represents a data host alias for server-side integration.

Element Type Description
id String Numeric ID of the connection profile for the backend system
alias String Alias name for a web service used for backend access in a server-side integration
defaultValue String Default URL for the alias (optional)

Component

Component example (intent component)

{
    "id": "b5e8c00c-6fb4-4a71-9760-1656e303c8d4",
    "name": "BOOK_FLIGHT",
    "description": "intent",
    "nodes": [
        // one or more nodes...
    ],
    "projectId": "28661",
    "eventHandlers": [],
    "intentId": "9030425b-1c69-45b1-9de2-ef65fc1656a6",
    "timestamp": "2021-04-13T16:31:34.128Z"
}

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 “intent” if the component is an intent component; otherwise, empty
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
intentId String UUID of the intent that is mapped to the component, if this is an intent component; otherwise, empty
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 Only in 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 (controllerNode) 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 type content Object The key for this field specifies one of the supported node types, and the value is content specific to a node of that type
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

Dialog models support these types of nodes:

Element key Node type
recognitionNode2 Question and answer node
messageNode Message node
decisionNode Decision node
dataAccessNode Data access node
controllerNode Question router node
intentMapperNode2 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": "",
    "entityId": "",
    "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": [],
    "nodeCommandOverrides": [],
    "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: recognitionNode2.

Element Type Description
name String Name of the node
description String Description of the node (maximum 1000 characters)
initialMessage Processing item group object Processing items to perform before recognition
collectionType String Type of data to collect—for example, INTENT_TYPE, CUSTOM_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
entityId 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 collection events, such as no match, max no match
settings Object Deprecated (superseded by nodeSettingOverride)
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
reentryMessage Processing item group object Optional processing items to perform before recognition—instead of initialMessage—, when the dialog flow reenters this node
clickables Array of interactive elements Optional interactive elements for values of the entity to collect, if collectionType is CUSTOM_LIST_TYPE, YES_NO or NUANCE_BOOLEAN, and for values of the global command entity for which an override is defined at this node; otherwise, empty
view View object Formatting information to pass to the client application for messages and interactive elements
inputVariablesConcepts Array of inputs Key-value pairs representing variables, entities, and other objects to pass on to the client application
nodeSettingOverride Array of node setting overrides Overrides to the default global settings for this node
recoConfirmationBehaviors Array of local confirmation behaviors Local behaviors for handling confirmation events, such as a no match, a positive or negative response to a confirmation prompt
dtmfToEntityValueMapping Array of DTMF mappings Mappings between DTMF keys and values of the entity to collect, if collectionType is CUSTOM_LIST_TYPE, YES_NO or NUANCE_BOOLEAN; otherwise, empty
nodeCommandOverrides Array of local command overrides Local handling for specified values of the global command entity
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

{
    "id": "9dea0ea8-9269-400e-ab7e-cf7a0ecb05fb",
    "event": "nomatch1-prompt",
    "escalationLevel": 0,
    "processingItems": {
        // processing items to perform...
    },
    "disabledChannelIds": [],
    "projectId": "22778",
    "nodeId": "4a2e1934-cfb5-4d71-9ff6-7076e4c60ba2"
}

Represents a local recovery behavior for handling collection events such as no match, max no match.

Element Type Description
id String UUID of the local behavior
event String Event ID—nomatch1-prompt, for example
escalationLevel Number Deprecated (event includes the escalation level)
processingItems Processing item group object Processing items to perform
disabledChannelIds Array of strings UUIDs of the channels for which the behavior is disabled at this node for the specified event
projectId String ID of the project
nodeId String UUID of the node

Local confirmation behavior

Local confirmation behavior example

{
    "id": "ec54c30c-2b9f-40b6-8161-9b3f6d70758f",
    "event": "yes-prompt",
    "processingItems": {
        // processing items to perform...
    },
    "disabledChannelIds": ["085dab9e-0f72-46af-bbac-d234e5f4dc0e"],
    "projectId": "22737",
    "nodeId": "f0a76820-dfa3-4ff1-bf53-f9d9221fbffb"
}

Represents a local behavior for handling confirmation events, such as a no match, a positive or negative response to a confirmation prompt.

Element Type Description
id String UUID of the local behavior
event String Event ID—yes-prompt, for example
processingItems Processing item group object Processing items to perform
disabledChannelIds Array of strings UUIDs of the channels for which the behavior is disabled at this node for the specified event
projectId String ID of the project
nodeId String UUID of the node

Interactive element

Interactive element example (a Yes button)

{
    "id": "34c60614-4c9e-43c5-8931-e9ee17d7ebb5",
    "order": 0,
    "entityValue": "yes",
    "clickableDescription": "The Yes button",
    "imageUrl": "https://my.image.com/icon-check.png",
    "label": "YES",
    "channel": "2f15016c-8809-48ec-9103-4f6673aa371e",
    "language": "",
    "enabled": true,
    "entityId": "b1cb5c79-0640-4220-91b6-a1bdd59e08e7"
}

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

Element Type Description
id String UUID of the interactive element
order Number Sequence number of the interactive element
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 that supports interactivity for this question and answer node
language String Language of the interactive element—Future use
enabled Boolean true if the interactive element is enabled; otherwise, false
entityId String UUID of the global command entity, if this interactive element is for a local command override; otherwise, UUID of the entity being collected at this question and answer node

View

Represents formatting information to pass to the client application for messages and interactive elements in question and answer nodes, and for messages in message nodes and in data access nodessupported via Dialog gRPC API only.

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

DTMF mapping

DTMF mapping example

{
    "id": "2c9fbbdb-23dc-44ee-8f57-b3dcc6719395",
    "nodeId": "4e2de976-63a8-41f5-854c-7f8bfabf8d42",
    "channelId": "df1789df-7329-4472-8b1f-3d731affb4a7",
    "projectId": "7998",
    "dtmfValue": "9",
    "entityValue": "DIRECTORY",
    "entityId": "7b6c37d9-36d7-4b28-abe5-a7329724be51"
}

Represents the mapping between a DTMF key and a value of the entity to collect at this node.

Element Type Description
id String UUID of the mapping
nodeId String UUID of the node
channelId String UUID of the channel for the mapping
projectId String ID of the project
dtmfValue String DTMF key being mapped
entityValue String Entity value being mapped
entityId String UUID of the global command entity, if this mapping is for a local command override; otherwise, UUID of the entity being collected at this question and answer node

Node setting override

Node setting override example

{
    "id": "d6720d24-2147-4d94-bb8f-58f46f746268",
    "nodeId": "a543a69f-c83c-4216-8dc9-0442dd2e7d53",
    "projectId": "22738",
    "settingType": "SPEECH_SETTINGS",
    "channelId": "390c240c-3bb7-40db-bff1-11b59131a434",
    "value": "false",
    "settingName": "bargein",
    "language": ""
}

Represents an override to the global settings defaults for a specific question and answer node or for a message node.

Element Type Description
id String UUID of the setting override
nodeId String UUID of the node
projectId String ID of the project
settingType String Setting category—one of: COLLECTION_SETTINGS, CONFIRMATION_SETTINGS, DTMF_SETTINGS, TTS_SETTINGS, SPEECH_SETTINGS, CONVERSATION_SETTINGS, AUDIO_SETTINGS, GRAMMAR_SETTINGS
channelId String UUID of the channel for the override
value String Override value
settingName String Name of the setting
language String Language to which the override applies, 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

Local command override

Local command override example

{
    "id": "6600fa54-4a36-45df-a9db-f42b8f57a9b5",
    "projectId": "22924",
    "nodeId": "1bbfdc61-da14-41af-a0b1-053c634a4e41",
    "entityId": "64f0af61-8977-4ac6-bf7b-a391bcc860e7",
    "entityValue": "agent",
    "processingItems": {
        // processing items to perform...
    },
    "enabled": true
}

Represents the local handling for a value of the global command entity at this node.

Element Type Description
id String UUID of the override
projectId String ID of the project
nodeId String UUID of the node
entityId String UUID of the global command entity (same as globalCommandsEntityId in Project object)
entityValue String Entity value being overridden
processingItems Processing item group object Processing items to perform
enabled Boolean true if local handling is enabled for the specified value of the global command entity; otherwise, false

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",
                                        "audioFileId": "",
                                        "bargeinDisabled": false,
                                        "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": ""
    },
    "nodeSettingOverride": [],
    "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 (maximum 1000 characters)
processingItems Processing item group object List of processing items
view View object Formatting information to pass to the client application for messages
nodeSettingOverride Array of node setting overrides Indicates whether barge-in is disabled at this message node; otherwise, empty
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 (maximum 1000 characters)
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": "getCoffeePrice",
    "description": "",
    "outputVariables": [{
            "id": "47261b77-e96a-426d-a625-c7b6c7f2b405",
            "name": "priceAmount",
            "description": "",
            "possibleValues": [],
            "projectId": "24420",
            "uiDefaultValue": "{\"number\":\"3.25\",\"unit\":\"CAD\"}",
            "isReserved": false,
            "masked": false,
            "simpleVariableType": "AMOUNT_TYPE",
            "timestamp": "2021-03-25T23:16:20.760Z"
        }
    ],
    "serviceName": "getCoffeePrice",
    "externalFetchEnabled": false,
    "successNodeId": "f4041e98-688c-470c-8713-cd56a0e830f7",
    "failureNodeId": "8037e018-9b53-4f58-ab91-edb96d707018",
    "inputVariablesConcepts": [{
            "concept": {
                "id": "8e675ac5-1955-4cf1-b754-689e2c11f043",
                "projectId": "24420",
                "name": "COFFEE_TYPE",
                "isInBaseOntology": false,
                "valuesCount": 0,
                "isDialogType": false,
                "predefinedConceptId": "",
                "isDeprecated": false
            }
        }, {
            "concept": {
                "id": "715740fb-41af-4f01-bef0-358e32366756",
                "projectId": "24420",
                "name": "COFFEE_SIZE",
                "isInBaseOntology": false,
                "valuesCount": 0,
                "isDialogType": false,
                "predefinedConceptId": "",
                "isDeprecated": false
            }
        }
    ],
    "view": {
        "name": "",
        "style": ""
    },
    "backendConfig": {
        "id": "",
        "urlExtension": "/coffee/price",
        "fetchTimeout": 0,
        "connectTimeout": 0,
        "method": "POST",
        "dressName": "522",
        "headers": [{
                "key": "mytoken",
                "variable": {
                    "id": "b25fa304-1f04-4213-afc5-b90586574d29",
                    "name": "myToken",
                    "description": "",
                    "possibleValues": [],
                    "projectId": "24420",
                    "uiDefaultValue": "",
                    "isReserved": false,
                    "masked": false,
                    "simpleVariableType": "STRING_TYPE",
                    "timestamp": "2021-03-30T16:49:43.391Z"
                }
            }, {
                "key": "apikey",
                "constant": "5678"
            }
        ],
        "dressAliasId": "522"
    },
    "timestamp": "2021-04-13T18:53:21.399Z"
}

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 (maximum 1000 characters)
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 exchange data (client-side integration); otherwise false (server-side integration)
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 variables, entities, and other objects to pass on to a backend system
urlExtension String Deprecated
fetchTimeout Number Deprecated
connectTimeout Number Deprecated
methodType String Deprecated
sourceExpression String Deprecated
headers String Deprecated
view View object Formatting information to pass to the client application for messages—supported via Dialog gRPC API only
backendConfig Backend connection data object Information required by the dialog service to interact directly with a backend system—used when externalFetchEnabled is false (server-side integration)
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

Backend connection data

Represents the information to access a backend web service from a data access node.

Element Type Description
id String Not used
urlExtension String URL extension (maximum 2000 characters)
fetchTimeout Number Fetch timeout in milliseconds (default: 0)
connectTimeout Number Connection timeout in milliseconds (default: 0)
method String Method; one of: POST, GET, PUT, DELETE, PATCH, NOT_SET (default)
dressName String Deprecated (superseded by dressAliasId)
headers Array of headers Headers used to query the backend system, as key-value pairs
dressAliasId String Numeric ID of the connection profile for the backend system

Supported header types

Represents a header in the backend connection data for a data access node, or in a backend connection preset.

Element key Value type Description
constant String Static header data (maximum 255 characters)
variable Variable object Variable used as dynamic header data
variableExpression Variable expression object Complex variable field, used as dynamic header data

Supported input types

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). Dialog models support these input types:

Element key Value type Description
variable Variable Variable to pass on to the backend system
concept Entity Entity to pass on to the backend system
intent String One of: INTENT_VALUE (active intent value), INTENT_LITERAL (active intent literal), INTENT_FORMATTED_LITERAL (formatted version of the active intent literal), INTENT_CONFIDENCE (active intent confidence score)
specialOperand String One of: LAST_COLLECTION_INTERPRETATION (last collection interpretation), LAST_CONFIRMATION_INTERPRETATION (last confirmation interpretation)

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 (maximum 1000 characters)
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": [{
        "id": "95573456-5c8e-4de1-93e2-190fe13a80a7",
        "projectId": "17512",
        "nodeId": "5b5fb24c-8bcb-4c88-bbf5-136f861724cb",
        "intentId": "3478f442-8f6e-483d-8efd-8cb53208c49e",
        "destination": {
            "componentId": "ae6c8b59-f7bf-4bae-824f-0ed4e054f35a"
        }
    }],
    "transition": {
        "id": "c2ef0247-2b69-4570-8807-a9685e0013cc",
        "transitionType": "GO_TO",
        "event": "",
        "label": "On Return",
        "projectId": "480",
        "nodeId": "389bba31-9825-4406-8e45-e7b0d2e38561"
    },
    "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: intentMapperNode2.

Element Type Description
name String Name of the node
description String Description of the node (maximum 1000 characters)
intentMappings Array of node intent mapping objects Intent mappings specific to this intent mapper node (override any corresponding global intent mappings)
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
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

Node intent mapping

Node intent mapping example

{
    "id": "95573456-5c8e-4de1-93e2-190fe13a80a7",
    "projectId": "17512",
    "nodeId": "5b5fb24c-8bcb-4c88-bbf5-136f861724cb",
    "intentId": "3478f442-8f6e-483d-8efd-8cb53208c49e",
    "destination": {
        "componentId": "ae6c8b59-f7bf-4bae-824f-0ed4e054f35a"
    }
}

Represents the mapping of one intent to a component or node as defined within an intent mapper node.

Element Type Description
id String UUID of the mapping
projectId String ID of the project
nodeId String UUID of the Intent mapper node
intentId String UUID of the intent being mapped
destination Mapping destination object Key-value pair mapping the intent and a component or node

Node intent mapping destination

Intent mapping destination example

{
    "componentId": "ae6c8b59-f7bf-4bae-824f-0ed4e054f35a"
}

Dialog models support these destination types for node-level intent mapping overrides:

Element key Value type Description
componentId String UUID of a component
nodeId String UUID of a node

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 (maximum 1000 characters)
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 (maximum 1000 characters)
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 (maximum 1000 characters)
inputVariablesConcepts Array of inputs Key-value pairs representing variables, entities, and other objects to pass on to the 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,
    "masked": 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 (maximum 255 characters)
possibleValues Array of strings Valid values for the variable—Future use
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
masked Boolean true for sensitive variables to be masked in application logs; otherwise false
simpleVariableType String Only present for defined simple variables; one of the supported variable types
simpleGenericType String Only present for variables where simpleVariableType is LIST_TYPE; indicates the type of the items in the list
complexGenericTypeId String Only present for variables where simpleVariableType is LIST_TYPE, and the list items are complex variables; UUID of the schema for 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

Supported variable types

Dialog models support these types of variables:

Value Type
STRING_TYPE String
ALPHANUM_TYPE String of alphanumeric characters
DIGITS_TYPE String of digits
BOOLEAN_TYPE Boolean
INTEGER_TYPE Integer
DECIMAL_TYPE Decimal-point number
AMOUNT_TYPE Amount, including currency (example: “USD 234.56”)
DATE_TYPE Date, in this format: YYYYMMDD (example: “20201030”)
TIME_TYPE Time, in this format: HHMM (example: “2359”)
DISTANCE_TYPE Distance, including unit and modifier (example: “123.4567 km LT”)
TEMPERATURE_TYPE Temperature, including unit (examples: “-12.3 C”, “273.15 K”)
LIST_TYPE List
DYNAMIC_ENTITY_DATA Dynamic entity data—not supported for list items and schema fields

Schema

Schema example

{
    "id": "5f044809-ffad-44cc-ad58-773d6b04bcd3",
    "name": "myOrder",
    "description": "item, quantity, unitPrice, isReady",
    "fields": [
            //   one or more 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 (maximum 255 characters)
fields Array of variables One or more variables
projectId String Unique ID of the parent project
isReserved Boolean True for a reserved schema (for example, DynamicMessageReference); otherwise false

Prompt group

Prompt group example

{
    "id": "0e1f1917-01cd-4779-a07d-db6963d0d95e",
    "name": "what_can_i_get_you_today?",
    "prompts": [{
            "payload": {
                "displayText": "What can I get you today?",
                "ttsText": "How may I help you?",
                "audioFile": "",
                "displayTextAnnotations": [],
                "ttsTextAnnotations": [],
                "ttsAudioBackup": "",
                "ttsAudioBackupAnnotations": []
            },
            "language": "en-US",
            "channel": "752f65fd-7215-4083-ad29-7fd8bf5ae38a",
            "lastModified": "2020-09-14T03:17:19.565Z"
        }
    ],
    "projectId": "1337",
    "bargeinDisabled": false,
    "audioFileId": "",
    "lastModified": "2020-09-14T05:40:26.962Z"
}

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
audioFileId String Name of the audio file to play for the Audio Script modality (maximum 255 characters)—the file extension is determined in the project settings
bargeinDisabled Boolean false if barge-in is enabled for this prompt group (default); otherwise true
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": "What can I get you today?",
        "ttsText": "How may I help you?",
        "audioFile": "",
        "displayTextAnnotations": [],
        "ttsTextAnnotations": [],
        "ttsAudioBackup": "",
        "ttsAudioBackupAnnotations": []
    },
    "language": "en-US",
    "channel": "752f65fd-7215-4083-ad29-7fd8bf5ae38a",
    "lastModified": "2020-09-14T03:17:19.565Z"
}

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": "What can I get you today?",
    "ttsText": "How may I help you?",
    "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 Deprecated
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 Backup text to render using text-to-speech when the specified audio file is unavailable; 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 for a simple variable of type string

{
    "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
variableExpression Variable expression object Complex variable field, or the result of a supported method against a variable, to include in the message
conceptId String UUID of the entity that contains dynamic content to include in the message
conceptIdLiteral String UUID of the entity whose literal is to include in the message
conceptIdFormattedLiteral String UUID of the entity whose formatted literal is to include in the message
currentEntity String One of: ENTITY_VALUE, ENTITY_LITERAL, ENTITY_FORMATTED_LITERAL, to include in a global confirmation message—Mix.dialog only supports ENTITY_VALUE (current entity value from the last NLU interpretation result)
Intent String One of: INTENT_VALUE (active intent value), INTENT_LITERAL (active intent literal), INTENT_FORMATTED_LITERAL (formatted version of the active intent literal),INTENT_CONFIDENCE (active intent confidence score), to include in the message
type String Controls the validation of output formatting properties, if applicable—possible values include alphaNum, currency, date, digits, cardinalNumber
properties Annotation properties object Display attributes for the annotation, and formatting parameters for the value associated with the annotation

Annotation properties

Annotation properties example to format a date value for German CPR playback

{
 "formType": "DATE_TYPE",
 "intonation": "medial",
 "string": "myDate",
 "partsOfDate": "mdy",
 "case": "nominative",
 "playDayOfTheWeek": "false"
}

Represents output formatting properties for the value associated with the annotation. Only string is required, all other elements are optional and depend on the data type. If only string is present, this means that the raw value is to be included in the message.

Element Type Description
formType String Determines the format editor to use in Mix.dialog for this annotation—one of: ALPHA_NUM_TYPE, CURRENCY_TYPE, DATE_TYPE, DECIMAL_TYPE, DIGITS_TYPE, DISTANCE_TYPE, CARDINAL_NUMBER_TYPE, TEMPERATURE_TYPE, DISTANCE_TYPE, TIME_TYPE
string String Display text for the placeholder in the message
advanced Boolean true if the advanced format editor is to be used in Mix.dialog for this annotation—only for date and time values (in Rich Text messages), and alphanumeric and digits (all message formats)—otherwise, false (default)
pattern String Pattern string to format the value in the message—only for date and time values (in Rich Text messages), and alphanumeric and digits (all message formats)
thousandSeparator Boolean Rich Text only, for amount, decimal, distance, integer, and temperature values: true (default) to show the value with the applicable thousands separator; otherwise, false
playZeroDollars Boolean Amount CPR playback only: true (default) to play “zero dollars” (in the session language), when the number of dollars (or selected currency) is zero; otherwise, false
playZeroCents Boolean Amount TTS and CPR playback only: true (default) to play “zero cents” (in the session language), when the number of cents (or sub-unit for the selected currency) is zero; otherwise, false
playPrehundred Boolean English (United States) CPR playback only, for amount values: true to use different audio recordings for hundreds prior to millions/thousands, and for hundreds prior to tens; false (default) to use the same audio recording for hundreds regardless of their position in amounts
currency String For display purposes only: currency to show on the annotation in Mix.dialog—at runtime (and in preview) the currency is part of the value
partsOfDate String Specifies which parts to play for a date, and the order—examples: mdy to play something like “February 17, 2021”, or my to play something like “August 2023”
playDayOfTheWeek Boolean true to display or play the day of the week (for example, “Sunday”); otherwise, false (default)—only for date values
decimalPlaces String Number of decimal places to show (0–7, default: 2)—only for decimal, distance, and temperature values
playZeroUnits Boolean Decimal CPR playback only: true (default) to play “zero point” (in the session language), when the value is zero; otherwise, false
playZeroDecimals Boolean Decimal TTS and CPR playback only: true (default) to play “point zero cents” (in the session language), when the value is zero; otherwise, false
distanceType String For display purposes only: Unit of distance to show on the annotation in Mix.dialog (km, m, cm, mm, mi, yd, ft, in)—at runtime (and in preview) the unit of distance is part of the value
tempType String For display purposes only: Unit of temperature to show on the annotation in Mix.dialog (C, F, K)—at runtime (and in preview) the unit of temperature is part of the value
intonation String CPR playback only: intonation to use for the value in the message: medial (default), or final
case String German CPR playback only, for amount, date, and decimal values—Grammatical case to use for the value in the message: nominative (default), or dative

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 notes such as a description or reminder (maximum 4000 characters)

Supported processing item types

Dialog models support 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 or throws an event
placeholderProcessingType String note for designer notes; action for an action that is not yet defined; prompt_tts, prompt_text, or prompt_ttsAudio for a message that is not yet defined

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. It can be part of a condition, an assign action, an entity reference, or another expression. It is composed of a left operand, an operator, and a right operand.

Element Type Description
id String UUID of the expression
left operand Object Key-value pair representing one of the supported left operand types.
operator Object Key-value pair representing one of the supported operator types
right operand Object Key-value pair representing one of the supported right operand types
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

Supported left operand types

Represents the left operand of an expression.

Element key Value type Description
leftVariable Variable object Variable used as the left operand
leftVariableExpression Variable expression object Complex variable field, or the result of a supported method against a variable, used as the left operand
leftExpression Expression object Expression 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
leftConceptIdFormattedLiteral String UUID of the entity whose formatted literal is used as the left operand
leftIntent String One of: INTENT_VALUE (active intent value), INTENT_LITERAL (active intent literal), INTENT_FORMATTED_LITERAL (formatted version of the active intent literal),INTENT_CONFIDENCE (active intent confidence score)
leftSpecialOperand String One of: LAST_COLLECTION_INTERPRETATION (last collection interpretation), LAST_CONFIRMATION_INTERPRETATION (last confirmation interpretation), NULL

Supported operator types

Represents the operator in an expression.

Element key Value type Description
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

Supported right operand types

Represents the right operand of an expression.

Element key Value type Description
rightConstant String Constant used as the right operand (maximum 255 characters)
rightVariable Variable object Variable used as the right operand
rightVariableExpression Variable expression object Complex variable field, or the result of a supported method against a variable, used as the right operand
rightExpression Expression object Expression used as the right operand
rightConceptId String UUID of the entity whose value is used as the right operand
rightConceptIdLiteral String UUID of the entity whose literal is used as the right operand
rightConceptIdFormattedLiteral String UUID of the entity whose formatted literal is used as the right operand
rightIntent String One of: INTENT_VALUE (active intent value), INTENT_LITERAL (active intent literal), INTENT_FORMATTED_LITERAL (formatted version of the active intent literal), INTENT_CONFIDENCE (active intent confidence score)
rightSpecialOperand String One of: LAST_COLLECTION_INTERPRETATION (last collection interpretation), LAST_CONFIRMATION_INTERPRETATION (last confirmation interpretation), NULL

Variable expression

Represents a complex variable field, or the result of a supported method against a variable.

Element Type Description
id String UUID of the variable expression
projectId String ID of the project
operations Array of variable operations Operations to be performed against the specified variable—multiple operations are chained, that is, each operation is applied to the result of the previous operation
variableId String UUID of the 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

Variable operation

Represents an operation in a variable expression.

Element key Value type Description
selectField Object Key-value pair, where the key is fieldVariableId and the value is the UUID of a field in the schema of a complex variable—to select a deeply nested field, use the required number of selectField operations, to be performed in sequence
callMethod Method call object Method to be applied to the specified variable or field

Method call

Represents a method call in a variable operation.

Element key Value type Description
methodName String Name of the method to call (for example, length, random, getDay)—the available methods depend on the type of the variable to which the method is to be applied
parameters Array of method parameters Key-value pairs that represent the parameters for the method, if any; otherwise empty

Method parameter

Represents a parameter in a method call.

Element key Value type Description
constant String Constant to be passed to the method
variableId String UUID of a variable to be passed to the method
conceptId String UUID of an entity to be passed to the method

Action

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

An action object represents an assign action, or an entity update 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, an entity, or the active intent.

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

Element Type Description
target Object Key-value pair representing one of the supported operand types for the left-hand side of an assignment
value Object Key-value pair representing one of the supported operand types for the right-hand side of an assignment

Left assignment operand types

Represents the target for an assign action.

Element key Value type Description
lhsVariable Variable object Variable being set
lhsVariableExpression Variable expression object Field being set in a complex variable
lhsConceptId String UUID of the entity whose value is being set
lhsIntent String Always INTENT_VALUE (active intent value)

Right assignment operand types

Represents the value for an assign action.

Element key Value type Description
constant String Constant used as the right operand (maximum 64000 characters)
variable Variable object Variable used as the right operand
variableExpression Variable expression object Complex variable field, or the result of a supported method against a variable, used as the right operand
expression Expression object Expression used as the right operand
intent String One of: INTENT_VALUE (active intent value), INTENT_LITERAL (active intent literal), INTENT_FORMATTED_LITERAL (formatted version of the active intent literal), INTENT_CONFIDENCE (active intent confidence score)
specialOperand String One of the supported special operands for the right-hand side

Supported special right operand

Assign actions support these special operands for the right-hand side:

Value Description
NULL Makes a variable or an entity null
NEW_OBJECT Initializes a complex variable as a new object with all fields null—not supported for complex variables with fields that are lists; use separate assign actions to preinitialize complex variable fields that are also complex variables

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-value 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 makes it null, sets .isRequired to true, and sets .isConfirmed and .isCompleted to false.

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 or a throw event action, in a processing item, or a transition 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,
            "isDialogType": false,
            "predefinedConceptId": "",
            "isDeprecated": false,
            "lastModified": "1970-01-01T00:00:00Z"
        }, {
            "id": "fc5b8a5e-440b-4460-9e29-f8fafa546abd",
            "projectId": "2942",
            "name": "COFFEE_SIZE",
            "isInBaseOntology": false,
            "valuesCount": 4,
            "isDialogType": false,
            "predefinedConceptId": "",
            "isDeprecated": false,
            "lastModified": "1970-01-01T00:00:00Z"
        },  // more entity types...
           {
            "id": "572bcd5c-e65d-4a5d-b12c-9e6e85f56973",
            "projectId": "2942",
            "name": "nuance_TEMPERATURE",
            "isInBaseOntology": true,
            "valuesCount": 0,
            "isDialogType": false,
            "predefinedConceptId": "",
            "isDeprecated": false,
            "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
isDialogType Boolean true for a predefined dialog entity; otherwise false
predefinedConceptId String For an isA relationship entity of a predefined entity or dialog entity, UUID of the highest-level parent entity
isDeprecated Boolean true for a deprecated dialog entity; otherwise false
isA String Only present for relationship entities; UUID of the parent entity
lastModified String Not used

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

Change log

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

2021-09-09

Added enginePackVersion in Project

2021-07-21

2021-07-14

Removed inputVariables from Data access node to reflect that this deprecated element no longer exists (Mix will skip this element when you import any legacy JSON files where it might appear)

2021-07-07

Removed dialogTypeId and numberOfTypeUsages from Entity to reflect that these elements no longer exist (Mix will skip these when you import any legacy JSON files where they might appear)

2021-06-23

Added placeholderProcessingType to cover designer notes in supported processing item types

2021-05-17

Added intentId to Component

2021-04-28

2021-04-13

2021-03-09

2021-02-17

Updated Annotation to cover output formatting properties for variables and entities in dynamic messages

2021-02-05

Updated Variable to mention that DYNAMIC_ENTITY_DATA is not a supported type for list items and schema fields

2021-01-26

2020-12-09

2020-10-28

2020-10-08

2020-10-01

Updated Expression and Supported input types to add elements that represent the last collection and last confirmation interpretations. Note: These representations do not yet include entity interpretations.

2020-09-04

2020-08-28

Minor updates in Project object

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.