How to Use Variables in Atmosphere® SmartFlows

Variables are a very powerful tool in SmartFlows and can be used for a number of purposes. A variable is a named placeholder for information. It can be used to customize messaging, build business logic in flows, or send data to external systems or analytics.

Most actions have a section in the right-side navigation called Available Variables. This section will list variables that can be used in that action. When a variable is invoked in the course of a flow being executed, it will be replaced with the value it contains at that time. Here are some examples:

  • When a person calls a phone number with an Inbound Call trigger, their phone number is stored in a variable called $ANI. Use the $ANI variable to send an SMS follow-up message to the caller after the call wraps up.
  • When someone texts an Inbound SMS flow, the message is stored in a variable like this: $ISMS_1.message. Use this variable as the ‘Text Feed’ on the Sentiment action to analyze the message for positive or negative sentiment.
  • Add variables to the Body of a post request in the External Web Call to send the information they contain into another system; use them to build a URL in a GET request to bring back specific information about a particular record (ex. Find customer account balance based on the $ANI).

System-Wide Variables

The following is a list of system variables available in SmartFlows to support use cases like holiday and time of day routing, or read back in text-to-speech within a flow. Date- and time-specific system variables can be customized to a specific time zone in the Flow Configuration Settings section (click anywhere on the board to open).

Note: Not all of these variables appear on the screen, but all are available for use.

Variable Definition Format
$DateTime.CurrentTimeText Current time of day, in 24-hour format, at the time that the variable is used in an action. 16:10
$DateTime.currentDateText Current month, day, and year. October 14, 2020
$DateTime.currentMonthText Literal name of the current month. October
$DateTime.currentDayText Current day of the month. 14
$DateTime.currentYearText Current year. 2020
$DateTime.currentDayOfWeekText Literal name of the current day of the week. Wednesday
$DateTime.currentTime Current time of day, in 24-hour format, at the time that the variable is used in an action, without the colon separating the hours and minutes. 1610
$DateTime.currentDate Numeric representation of the current date. YYYYMMDD. Users should note that this format may be different than the standard in their country as many countries use YYYYDDMM. 20201014
$DateTime.currentMonth Numeric representation of the current month. 10
$DateTime.currentDay Current Day. No different from currentDayText other than a simpler variable name. 14
$DateTime.currentYear Current Year. No different from currentYearText other than a simpler variable name. 2020
$DateTime.currentDayOfWeek Cardinal numbers 1 through 7 representing the days of the week, beginning Monday. 3 (Wednesday)

Where to Find Variables

Drag-and-Drop Variables in Available Variables Section

Most of the time, variables will appear in the Available Variables section of an action’s configuration panel to be dropped into input fields or free-form messages.

Variable Drop-Downs

In some cases, variables are not drag-and-drop but must be chosen from a drop-down. This is the case on the Switch and Condition actions.

Setting Variables

There are several areas in SmartFlows that allow or require users to set their own variables. When setting variables, remember to keep these constraints in mind:

  • Cannot contain spaces
  • Cannot contain underscores
  • Case sensitive
  • If the variable is updated, it must be manually updated everywhere else it is used in the flow; changes to variable names do not propagate automatically

Set Variable Action

The Set (Variable) action offers users the ability to create their own custom variables or rename existing variables.

This can be used in several ways:

  • Create a ’store address’ variable to avoid having to retype the same value in multiple text-to-speech areas
  • Rename $DateTime.currentDateText to $date to avoid having to retype
  • For text-to-speech controls, such as ‘breathiness’ or ‘pace’, set the tags as variables so they can be controlled across all TTS in the flow from one place for a consistent voice sound

Setting Variables in the External Web Call

There are also other areas of the application where users must create variables. One example is when using the GET request type on the External Web Call, which is designed to retrieve information from an external source. The Response Variables section prompts to user to store this retrieved information in a variable. In the diagram below, the query expression (input box on the right) is the JSON text written to work with the external system; the name for the new variable goes on the left.

Setting Variables in the Inbound API

The Inbound API can also be set up to accept inputs from an external source and store them in variables that can be used in other parts of the flow. To do this, the incoming POST request to SmartFlows should include the Flow ID for the flow being called by the API (found in the Flow Configuration section) and the required values in the selected format (JSON or XML). In addition, the inbound API currently requires a value for an ANI and a DNIS in the request, though these need not be used in the flow.

Any values needed in the flow should be configured in the Expected Input section on the Inbound API as shown in the diagram below (FIRSTNAME, LASTNAME, PHONE, BIRTHDAY).

Setting Variables in the Jump To and Jump From Actions

Variables from a source flow (a flow containing a Jump To action) can be passed to a destination flow (a flow containing a Jump From action, connected to a source flow). They must be explicitly configured in the Send Variables section on the source flow (a), and they must also be explicitly configured as Expected Variables on the Jump From action in the destination flow (b).