Intro to flows & variables

Learn about the components of flows and variables and how they operate in NLX

Flows and user intent

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 training data, 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

Intent recognized from user utterance and matched to a flow

---

Flow invocation

Flows are triggered in conversation in one of four ways:

• User invocation: Through the use of a User input node 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). User choice nodes also support intent recognition and routing automatically in cases where user utterances don't match the assigned choices and new intent is detected
• 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.)
• Redirect node: When deliberately directed to via a Redirect node in another flow
• 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

---

How flows are defined in NLX

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)

• Flow 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 user 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

• External actions: Events triggered that send or retrieve data outside NLX. These may be triggered via Data request or Action nodes

---

Variables in flows

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 {:

Using a variable in a flow via the placeholder menu

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
• Pink: Context variables, Secrets, or MCP inputs
• Light teal: System variables

Flow variable	Description	Memory
Local variable	Includes named outputs from Define nodes, Loop nodes, Generative nodes, and Knowledge Base nodes.	Retained locally in a flow where they are created/generated while a user is active in the flow. If a user leaves and revisits the flow, they are reset. If a user is looped through the same flow without leaving, these variables may be cleared via a state modification to avoid auto-traversal. To preserve the variable in one flow for use in other flows, use a state modification to set the variable as a Context variable
Slot	Captured through user utterance. Slots allow you to restrict the accepted "value" of the user's utterance using custom or built-in slot types	Retained locally to the flow where attached. If a user revisits a flow during a session, slots may be cleared via a state modification to avoid auto-traversal. To preserve a slot selection in one flow for reference in other flows, use a state modification to set the slot as a Context variable
Data request variable	External data retrieved first through a Data request node	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
Context variable	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	Passed from the LLM interfacing with a user when an MCP-enabled flow is invoked. Retained throughout a conversation session
Secrets	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

List of System variables

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.

To use a system variable while configuring a node, type an open curly brace { and start typing system to choose from the available options.

System variable	Description	Example
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.isVoice	Indicates whether the user is communicating through text or voice interface. Applicable to all channels, including API with Touchpoint Voice	Use in a Split node with True/False check to route the user based on whether voice or text channel
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	The sentiment of the user (Positive, Neutral, Negative) for the current exchange. Note: sentiment analysis must be enabled for the application	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	Determine the real time a user means for NLX.Date or NLX.Time slots when passing to a Data request

---

Capturing variables from users

User utterance containing required variables for flow completion

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 training data to better route to flows or asked by the conversational AI when assigned to User choice or Generative Journey nodes.

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}.

Externally defined

For variables that must first be fetched externally in real-time to provide to users as options or to relay dynamic data, Data request nodes are used.

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
• MCP input: 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