Intro to flows & variables
Learn about the components of flows and variables and how they operate in NLX
Last updated
Learn about the components of flows and variables and how they operate in NLX
Last updated
When communicating with your conversational AI, a user's intention can be as simple as getting an answer to their question or wanting to complete a series of tasks (e.g., cancel a flight, file an insurance claim, etc.). The user's goal or intent is handled by a flow, which defines the appropriate response or action your conversational application should follow.
An example of your conversational AI application at work:
A user says, “I want to book a room”
Using , an AI model recognizes "I want to book a room" as an expression that suggests the user's intent should match to the flow, BookRoom
Your conversational application then responds by following the conversation logic defined within the BookRoom
flow
Flows are triggered in conversation in one of four ways:
Application default: When assigned to one of the available default behaviors, a flow is invoked during certain events the NLX NLU tracks (the start of a conversation session, fallback/failure events, unrecognized intent and therefore unmatched flows, etc.)
MCP extension: When a flow is exposed to an LLM client via Model Context Protocol, the LLM invokes it as a tool when user intent is matched
The core functionality of flows are comprised of the following:
Nodes: Carefully sequenced across the Canvas builder of a conversation flow, nodes represent a single step executed in a turn
Turn: A single exchange between the conversational AI and the user. A turn stops when a specific node is reached (either a User choice/input node, Generative Journey node, or node that is disconnected to any subsequent node)
Workspace name: A brief descriptive name for the flow that an NLP engine uses when constructing the stack of flows that make up your conversational application. Must be unique and must avoid spaces or special characters (e.g., BookRoom
)
AI description: Context on the purpose of the flow so an LLM model understands when to invoke the flow through intent recognition
Training phrases: A sample of phrases (utterances) users might say so an NLP model understands when to invoke the flow
Variables: Pieces of information that are required to successfully complete the flow and may be extracted from the user or defined from data gathered externally. Variables extracted from users are captured via Slots or Data requests
External actions: Events triggered that send or retrieve data outside NLX. These may be triggered via Data request or Action nodes
Every conversation between your application and a user is unique with details that change from session to session based on user choices, context, and external or generated data that changes in real time. Since this information can't be hardcoded into your flow's messaging or logic, variable placeholders are used to handle it dynamically.
To reference variables created, you may bring up the placeholder menu in supported text fields of your flow using an open curly brace {
:
Each dynamic placeholder (variable) is distinguishable by color:
Purple: Local flow variables
Green: Custom or built-in Slots
Orange: Data requests and their data variables
Local variable
Slot
Data request variable
Retained throughout a conversation session after variables are fetched. If the data may become outdated and the node is expected to be revisited during the session, enable the Always retrigger toggle on the Data request node to fetch updated values
Usable across any flow, these are empty on their own and are set or defined by other variables
Variables that begin empty and can be set either by externally-fetched data (via Data requests or Lifecycle hooks set to 'Start' lifecycle) or by internal values you've defined or captured in a flow. If not using lifecycles, use a state modification to set or alter these variables first. Tracked and retained throughout a conversation session
Model Context Protocol (MCP) variables
Externally set by an LLM and passed along to NLX via MCP
Created at the workspace and usable across any flow in Data request node payloads
Set when integrated in the workspace and retained throughout a conversation session
System variable
Tracked automatically by NLX
Set and tracked by the system and retained throughout the conversation session
NLX system variables are helpful when referenced in conditional logic in Split nodes, adding dynamic placeholders in messages, or providing context to Generative nodes for more tailored responses.
System.capturedIntent
Set by the User input node
Use in a Split node using conditional rules from the match edge of a User input node
System.conversationId
The unique id for the current conversation
Pass to Data requests to identify a unique interaction
System.channelType
Provides the channel the user is currently using
Use in a Split node to route the user based on the channel used in conversation
System.currentTimestamp
Indicates the time (in UTC) recorded by the system when triggered in conversation (returns the number of milliseconds elapsed since the epoch, defined as midnight at the beginning of January 1, 1970, UTC)
Use in a Split node to route the user if their query is time sensitive or for changes to verbiage (e.g., “Good morning”) or processes during or outside of hours of operation
System.environment
Provides the environment the application is deployed to (Dev/Prod)
Use in a Split node to route users based on the production environment
System.language
The ISO 639-1 designated language (e.g., en
)
Parameterize URLs sent in messaging to support localized versions of a webpage by language/region
System.languageCode
The ISO 3166-1 Alpha-2 language code that the conversation session is in (e.g., en-US
)
Pass to Data requests as a parameter to support translation in the Data request response
System.lastIntent
The last flow visited by the user in the conversation session
Use in a Split node at the beginning of a flow to route the path of a user based on the context of where they were in a conversation
System.locale
The ISO 639-1 designated locale code (e.g., US
)
Parameterize URLs sent in messaging to support localized versions of a webpage by language/region
System.voicePlusTimeoutType
Timeout occurring from a Voice+ experience. Reference in a Split node condition: blank
= no timeout occurred; sessionStart
= user didn't tap SMS link; inactivity
= Voice+ started but inactivity between steps occurred
Use in a Split node to route users that may need to be escalated based on timeout condition
System.nlpConfidenceScore
The value (out of 100) that the NLP confidently matched a user's input to a flow
Use to ask clarifying questions if below a threshold to ensure the correct flow has been matched
System.resumeIntentMessage
The message relayed to a user when a flow is resumed from a previous interruption
Enabled on the Start node of a flow to pick up where a user left off
System.sentiment
Use in a Split node to provide empathetic responses
System.transcript
Provides the complete exchange between the human and the conversational AI application. Any sensitive information will be redacted
Use as a payload field in a Data request that creates a ticket in a help desk system
System.userId
The user ID identifying the human in the conversation. Value varies by channel
Pass to Data requests to look up information on the user's phone number over a voice channel
System.utterance
The most recent message received from the human
Use in a Split node and the Contains operator to determine if the user said a specific keyword
System.timezone
The user's detected time zone in the conversation
In a BookRoom
flow, for example, variables that need to be resolved could include check-in and check-out dates, room type, number of guests, etc.
In the sample utterance, "I want to book a King room for Saturday," two variables are given by the user: room type and check-in date. These variables can be captured using a custom slot type named {RoomType}
and a built-in date slot named {CheckInDate}
.
For example, with a BookRoom
flow, available room types can be retrieved from a Data request node and then presented in a User choice node, since these variables are likely to change regularly.
Additional methods for passing variables from another system to NLX, include:
Lifecycle hook: Passes variables captured from a system or channel provider to NLX (at the time your conversational application is called) through the use of context. Must assign the Lifecycle hook created to the application's start lifecycle
User invocation: Through the use of a that captures a user's utterance and sends it to your application's AI model for intent recognition. When intent is recognized and is matched to a flow, the user is redirected to it (using an accompanying Redirect node set to Recognized flow). also support intent recognition and routing automatically in cases where user utterances don't match the assigned choices and new intent is detected
Redirect node: When deliberately directed to via a in another flow
Pink: Context variables, Secrets, or
Light teal:
Includes named outputs from nodes, nodes, nodes, and nodes.
Retained locally in a flow where they are created/generated while a user is active in the flow. If a user leaves the flow and revisits the flow later, they are reset. If a user is looped through the same flow without leaving, these variables may be cleared via a to avoid auto-traversal. To preserve the variable in one flow for use in other flows, use a to set the variable as a Context variable
Captured through user utterance. Slots allow you to restrict the accepted "value" of the user's utterance using types
Retained locally to the flow where attached. If a user revisits a flow during a session, slots may be cleared via a to avoid auto-traversal. To preserve a slot selection in one flow for reference in other flows, use a to set the slot as a Context variable
External data retrieved first through a node
Passed from the LLM interfacing with a user when an is invoked. Retained throughout a conversation session
To use a system variable while , type an open curly brace {
and start typing system
to choose from the available options.
The sentiment of the user (Positive, Neutral, Negative) for the current exchange. Note: sentiment analysis for the application
Determine the real time a user means for slotswhen passing to a Data request
Slots are used to extract specific information from the user, especially if the variables are custom and static (e.g, yes/no, small/medium/large, etc.) or if the variables are abstract or infinite in range (e.g., time, cities, names). They may be used in to better route to flows or asked by the conversational AI when assigned to or nodes.
For variables that must first be fetched externally in real-time to provide to users as options or to relay dynamic data, nodes are used.
: Passes variables captured from an MCP Client (LLM service) to NLX when the LLM invokes the flow. Must have MCP setup completed for your application