System functions reference

This document provides a reference for all system functions provided by Dialogflow.

You can apply inline system functions in your agent's conditions, static response messages (such as text responses, custom payloads, and conditional responses), and parameter presets to generate dynamic values during conversations.

Function syntax

All system functions follow the pattern of $sys.func.<FUNCTION NAME>(<ARGUMENT 1>, <ARGUMENT 2>, ...). For example, $sys.func.RAND(), $sys.func.ADD(1,2).

The names of the functions are all capitalized (except the random number generation function, which you can use with both RAND and the legacy name rand).

The arguments of the functions can be:

  • inline values (such as number 1, string "abc", boolean true, and list [1, 2, 3])
  • references to parameters (such as $session.params.a, check parameters guide for more details about the syntax of referencing parameters)

  • nested functions (such as $sys.func.ADD($sys.func.MINUS(2, 1), 3))

Check results of system functions

During the conversation, if Dialogflow evaluates any inline system function expressions to generate dynamic values, you can find the results of the evaluations in the QueryResult.

Specifically, there is a key called SystemFunctionResults in the DiagnosticInfo struct field, which logs the results (and errors) of system function evaluations.

Functions

Below are the system functions that Dialogflow currently supports.

ADD

You can use the ADD function to add multiple numbers together.

The function takes an arbitrary number of arguments. All arguments must be numbers.

For example, the following expression produces a value of 3.

$sys.func.ADD(1, 2)

MINUS

You can use the MINUS function to subtract one number from another.

The function takes two arguments:

  • the minuend (number to be subtracted from)
  • the subtrahend (number to subtract)

For example, the following expression produces a value of 1.

$sys.func.MINUS(3, 2)

RAND

The function takes no arguments.

You can use the RAND function to generate a random floating point number in the range [0,1), such as in the expression below.

$sys.func.RAND()

LOWER

You can use the LOWER function to turn a string to lowercase.

The function takes one argument:

  • the string to convert to lowercase

For example, the following expression produces a value of "abc".

$sys.func.LOWER("ABC")

SUBSTITUTE

You can use the SUBSTITUTE function to replace existing text with new text in a string.

The function takes three arguments:

  • the original string
  • the text segment to be replaced
  • the text for replacement

For example, the following expression produces a value of "google".

$sys.func.SUBSTITUTE("good", "d", "gle")

SPLIT

You can use the SPLIT function to divide text around a specified character or string and puts the fragments into a list.

The function takes two arguments:

  • the string to split
  • the delimiter

For example, the following expression produces a value of ["a", "b", "c"].

$sys.func.SPLIT("a/b/c", "/")

JOIN

You can use the JOIN function to concatenate the elements of a string list using a specified delimiter.

The function takes two arguments:

  • the delimiter
  • the list of values to join

For example, the following expression produces a value of "a, b, c".

$sys.func.JOIN(", ", ["a", "b", "c"])

CONCATENATE

You can use the CONCATENATE function to concatenate strings together.

The function takes an arbitrary number of arguments. All arguments must be strings.

For example, the following expression produces a value of "$100".

$sys.func.CONCATENATE("$", "100")

MID

You can use the MID function to get a segment of a string.

The function takes three arguments:

  • the string to extract a segment from
  • the starting position of the segment (1-indexed)
  • the length (number of characters) of the segment

For example, the following expression produces a value of "gl".

$sys.func.MID("google", 4, 2)

LEN

You can use the LEN function to get the length (number of characters) of a string.

The function takes one argument:

  • the specified string

For example, the following expression produces a value of 6.

$sys.func.LEN("google")

TO_TEXT

You can use the TO_TEXT function to convert a value of other types (such as a number or a list) to a string.

The function takes one argument:

  • the original value to turn into a string form, which can be of any type (e.g. number, list, object)

For example, the following expression produces a value of "3".

$sys.func.TO_TEXT(3)

CONTAIN

You can use the CONTAIN function to check if a list contains a certain element.

The function takes two arguments:

  • the specified list

  • the value for the existence check

For example, the following expression produces a value of true.

$sys.func.CONTAIN([1, 2, 3], 1)

COUNT

You can use the COUNT function to get the number of elements in a list.

The function takes one argument:

  • the list to count

For example, the following expression produces a value of 3.

$sys.func.COUNT([1, 2, 3])

IF

You can use the IF function to return one of the two values based on a logical condition.

The function takes three arguments:

  • the logical expression (whose syntax is the same as the syntax of condition)
  • the value to return if the expression is true
  • the value to return if the expression is false

For example, the following expression produces a value of 1.

$sys.func.IF("1 < 2", 1, 2)

NOW

You can use the NOW function to get the current time.

The function takes no arguments.

For example, the following expression produces an object of @sys.date-time entity type representing the current time in your agent's timezone.

$sys.func.NOW()

FORMAT_DATE

You can use the FORMAT_DATE function to represent a date / time using a specified format.

The function takes the following arguments:

  • the time that you want to format
  • the desired format represented as a string
  • (optional) the desired language tag for the output represented as a string

The time (first argument) that you want to format should either be of a time-related entity type (such as @sys.date, @sys.time, and @sys.date-time) or an object with some or all of the following fields:

  • year
  • month
  • day
  • hours
  • minutes
  • seconds
  • nanos

For example, the object may look like this:

    {
        "day" : 9,
        "hours": 15,
        "minutes" : 23,
        "month" : 8,
        "nanos" : 0,
        "seconds" : 10,
        "year" : 2021
    }

The format (second argument) you specify should be a string consisting of symbols with the following meanings:

Symbol Meaning Examples
y Year 2021; 21
M Month of year 06; 6; Jun; June
d Day of month 10
E Day of week Tuesday; Tue; T
a AM/PM of day PM
H Hour in day (0-23) 0
h Clock hour (1-12) 12
m Minute of hour 30
s Secound of minute 59
S Millisecond 978
z Time-zone name Pacific Standard Time; PST

The language (third argument) should be a tag such as en or fr-CA.

The language tag is optional, and if it is unspecified, the output is in English by default, which means the two expressions below are equivalent:

$sys.func.FORMAT_DATE(<time>, <format>)
$sys.func.FORMAT_DATE(<time>, <format>, "en")
If the language tag is invalid, the output is also in English.

For example, if session parameter time is an object representing 8:30AM PST on 2021/06/30, you can generate the following strings representing the time using the FORMAT_DATE function:

$sys.func.FORMAT_DATE($session.params.time, <format>, "en")

Formats Outputs
"dd/MM/yy" "30/06/21"
"dd MMM yyyy" "30 Jun 2021"
"yyyy-MM-dd" "2021-06-30"
"EEEE, MMMM dd" "Wednesday, June 30"
"MM-dd h:mm a" "06-30 8:30 AM"
"hh:mm:ss a, zzzz" "08:30:00 AM, Pacific Standard Time"
"hh:mm:ss.SSS" "08:30:00.000"