How to Use Variables in 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 lists variables that can be used in that action. When a variable is invoked in the course of a flow being executed, it is 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 Text 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 (for example, 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).

The Setting section of the overall flow level Configurations Panel

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 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 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)

$DateTime.tzOffsetSeconds

Calculate the difference between your flow's time zone and UTC (i.e., Coordinated Universal Time). Can be positive or negative.

-36000

A sample Available Variables section of the Configuration Panel for an action, with system-wide variables highlighted

 

Where to Find Variables

Drag-and-Drop Variables in Available Variables Section

Most of the time, variables appear in the Available Variables section of an action’s configurations 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.

The Inputs section of the Configuration Panel for a Switch action

 

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.

On the left is the Set action on the board, and on the right is the Inputs section of the Configurations Panel for a Set action

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 text to speech (TTS) in the flow from one place for a consistent voice sound

 

Setting Variables in the Menu Tree and Press or Say Actions

You can also create a custom variable associated with the Menu Tree or Press or Say actions.

Select the Set Custom Variable check box in the Inputs section to reveal the Custom Variables field.

Example of the Set Custom Variable and Custom Variable Input fields for Menu Tree and Press or Say actions

You can then use your custom variable downstream in your flow with subsequent actions.

 

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 following diagram, 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.

The Response Variables field in the Configurations Panel for an External Web Call action

 

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 following diagram (FIRSTNAME, LASTNAME, PHONE, BIRTHDAY).

On the left is the Inbound API action on the board, and on the right is the Inputs section of the Configurations Panel for the Inbound API action with four sample Expected Inputs added

 

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

On the left is a sample flow with the Jump To action highlighted, and on the right is the Inputs section of the Configurations Panel for the Jump To action with the Send Variables field highlighted

On the left the Jump From action is selected, and on the right the Inputs section of the Configurations Panel for the Jump From action shows the Epected Variables field highlighted

 

Using Variables in Audio Settings

A variety of actions (Menu Tree, Transfer, Play Audio, etc.) allow you to play audio during a call. Click the blue Configure Audio button in the configurations panel to open the Audio Settings pop-up.

A sample of the Audio Settings pop-up

Here you have the option to configure Text-to-Speech (via the Audio Text (TTS) option) or use previously recorded audio files (via the Audio Library option). And you can use variables with each!

Audio Text (TTS) Variables

Add variables in your TTS message via the text box. You can type in a variable or drag and drop from the Available Variables section at the top of the Audio Settings pop-up.

A sample of the Audio Settings pop-up for a Transfer action with the Available Variables section collapsed and then expanded

Note: The variable acts as a placeholder. Therefore, you must define the variable you plan to include in your message upstream in the flow (e.g., using the Set Variable action). This ensures the correct word/phrase replaces the variable when the flow reaches the audio action.

For example, if you wanted to tailor a Transfer message with a specific department, you can drag and drop a custom variable (created with a Set (Variable) action upstream in your flow) into your TTS message.

Sample Audio Settings pop-up for the Transfer action with a sample Audio Text (TTS) message containing a variable

Audio Library Variables

The Variable field appears above any previously added audio files.

A sample Audio Settings pop-up with the Audio Library option selected and the Variable field highlighted

Here you can use variables to dynamically select and "create" the appropriate audio file. In the Variable field, add a file name with a variable inside.

Note: You must include the Set (Variable) action upstream in your flow and define the variable you plan to include in the file name. This ensures that the correct file can be found when your flow reaches the audio action.

For example, you may want to include a variable file name if you have one prompt that could be played in multiple languages. In this scenario the English, Spanish, and French versions of your prompt are all already loaded to your Audio Library (EN_prompt.wav, SP_prompt.wav, FR_prompt.wav ). A Set (Variable) action upstream acts as a flag to decide which language is appropriate for each caller using the $LANG variable. In your audio action, you would use the $LANG_prompt.wav file to dynamically select the appropriate prompt language audio file, depending on the caller.

A sample Audio Settings pop-up with the Audio Library option selected and a sample value in the Variable field

Once your variable audio file is added, don't forget to drag and drop it over to the appropriate section on the left side of the Audio Settings pop-up.

Note: If your variable is not populated correctly, the audio file will not be found or played. Make sure to test all audio functionality thoroughly.

Check out Configure Audio Settings for more information about audio capabilities.