Predefined variables and schemas

Mix.dialog provides several predefined variables and predefined schemas, which you can see in the Variables resource panel.

Predefined variables

All dialog projects have these predefined variables:

• channel
• channelIntegration
• CopilotResponse (preview)
• language
• returnCode, returnMessage
• Active Intent Value, Active Intent Literal, Active Intent Formatted Literal, Active Intent Confidence
• Current Entity Value
• Last Message Object
• Last Collection Interpretation, Last Confirmation Interpretation
• lastCollectionResultObject, lastConfirmationResultObject
• userData
• ExternalResourceReferences

channel

Name of the current channel of the application. Use this variable to switch to another channel at runtime when required—for example, to switch from an IVR channel that supports both voice and DTMF input to a DTMF-only channel, when the noise level in the caller’s environment prevents successful voice recognition.

channelIntegration

Channel integration information provided by the client application—not to be confused with channels in your dialog design. For example, a “Social VA” channel might apply to multiple channel integrations, such as WhatsApp, or Facebook Messenger. In a dialog design, you can use this variable to define integration-specific conditions, or for reporting purposes (for example, to report metrics per channel integration).

CopilotResponse

Applies to projects that use Answers, a Copilot feature.

Response from Answers when the end user asked a question that your application has otherwise not been designed to answer. Used in a message to be displayed from the dedicated Copilot_Answers intent component.

language

Language code (for example, en-US, fr-CA) that represents the current interaction language. Use this variable to switch to another language at runtime when required.

When using an assign action to set this variable, make sure your project supports the new language and that the value is in the correct format. See Geographies for the list of supported languages in all geographies.

Making the assignment in a question and answer node is a good practice. When the dialog service sends messages to the TTS service for synthesis, it sends all messages accumulated since the last question and answer node or data access node at once, and only the latest value of this variable applies.

If your design requires changing the language or the TTS voice mid-stream—for example, in the middle of a message, or between messages in a single node or in message nodes upstream from the question and answer node—use SSML tags in the message text. If your project uses standard or enhanced voices, see SSML tags for more information. If your project uses neural voices, see SSML input for more information.

returnCode

Return code for data access nodes and external actions nodes.

• Success: A return code of “0” means that the dialog was able to communicate with the backend. This doesn’t mean that the expected data was returned. Use conditions to verify that the returned data is not null (or not null and not empty, in the case of string data).
• Failure: Any value other than “0” means that communication with the backend failed.

returnMessage

Message that describes the meaning of the return code.

Active Intent Value

Value of the active intent. This value is set by an intent mapper node and it primarily comes from the last NLU interpretation result, either at a question and answer node collecting an NLU intent, or at question and answer nodes collecting entities subject to a question router node where intent switching is enabled. Use this variable to switch to another intent programmatically at runtime, when required—for example, in a disambiguation context when the dialog needs to prompt the user for more details in order to correctly identify their intent. See Active Intent behavior for more details.

Active Intent Literal

Literal for the active intent from the last NLU interpretation result.

Active Intent Formatted Literal

Formatted version of the literal for the active intent from the last NLU interpretation result.

Active Intent Confidence

Confidence score for the active intent from the last NLU interpretation result.

Current Entity Value

Only available in the Confirmation default messages section of the Project Settings panel.

Current entity value from the last NLU interpretation result. Use this variable to create dynamic confirmation default messages.

Last Message Object

Self-hosted environments: This feature requires engine pack 2.3 (or later) for Speech Suite deployments; engine pack 3.11 (or later) for self-hosted Mix deployments.

Messages from the last visited message node, or question and answer node. This variable is updated at every message node, and at every applicable step (collection, confirmation, recovery, system actions) of question and answer nodes.

Refer to Message actions, in the Dialog as a Service gRPC API documentation, for details about the content structure of this variable.

Always masked in dialog event logs. Only available in the Send data section of data access nodes and external actions nodes, and under the advanced properties of question and answer nodes.

Last Collection Interpretation

Interpretation result from the last collection operation, including literal, formatted literal, possible intents, the confidence score for each possible intent, possible entities, if any, including value and confidence score. Last Collection Interpretation is updated each time recognition happens upon user input at a question and answer node, recovery, global command, or intent switch, including when recognition generates a nomatch event. You could use this, for example, to analyze the literals that generated nomatch events in your application. Use a data access node, an external actions node, or a question and answer node, to send this variable to the client application or to an external system for further processing. If you want to use the last interpretation literal—for example, to use its length in a condition—use the complex variable lastCollectionResultObject.

Last Confirmation Interpretation

Interpretation result from the last confirmation operation, including literal, formatted literal, possible intents, possible entities, and confidence scores. Last Confirmation Interpretation is updated each time the dialog prompts the user for confirmation. Use a data access node, an external actions node, or a question and answer node, to send this variable to the client application or to an external system for further processing. If you want to use the last confirmation literal—for example, to use its length in a condition—use the complex variable lastConfirmationResultObject.

lastCollectionResultObject

Complex variable based on the interpretationResult schema. Interpretation result from the last collection operation, including literal, formatted literal, possible intents, and the confidence score for each possible intent. You can use this variable to reference the intent literal’s length, for example, in conditions. For logging purposes, this complex variable is always considered sensitive.

lastConfirmationResultObject

Complex variable based on the interpretationResult schema. Interpretation result from the last confirmation operation, including literal, formatted literal, possible intents, and the confidence score for each possible intent. For logging purposes, this complex variable is always considered sensitive.

userData

Complex session variable based on the userData schema.

See Exchanging session data, in the Dialog as a Service gRPC API documentation, for more information.

ExternalResourceReferences

Simple session variable to store references to external NLU and ASR precompiled resources. This variable holds a JSON string to be fetched at runtime from an external system, to support dynamic list entities based on compiled wordsets, for example. When this variable is set, the Dialog service automatically relays the information to the ASR and NLU services, to augment and improve recognition and interpretation results.

See Referencing compiled resources, in the Dialog as a Service gRPC API documentation, for more information.

Active intent behavior

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

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

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

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

Last interpretation behavior

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

Last interpretation specification

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

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

Intent interpretation

Entity interpretation

Predefined schemas

All dialog projects have these predefined schemas:

• DynamicMessageReference
• interpretationResult
• interpretation (used in interpretationResult)
• userData
• location (used in userData)

DynamicMessageReference schema

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

interpretationResult schema

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

interpretation schema

This schema has two fields:

userData schema

Represents data collected from the current end user.

location schema

Represents geographic coordinates.

Workflow for using a dynamic audio file reference

1. Create a complex variable based on the DynamicMessageReference schema.
2. Set up a data access node using your complex variable to get the required audio file reference, from the appropriate external system, at runtime.
3. Add a dynamic message for the Audio Script modality, and use your complex variable as a dynamic placeholder.
4. Preview your dialog design for a channel that supports the Audio Script modality (for example, IVR/Voice VA).
5. When the dialog reaches the data access node that is meant to return the dynamic file reference, use the fields that appear to enter an audio filename (including the extension), and alternative text.
   Notice that the alternative text appears in the chat pane when the dialog reaches the node that has the message with the dynamic audio file reference.