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), parameter presets, and webhook header values 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)

APPEND

You can use the APPEND function to append value(s) to the end of a list.

The function takes the following arguments:

  • the list to append values.

  • an arbitrary number of values to be appended to the end of the list.

    If the value is a list, the values inside the list will be appended one by one.

For example:

Expression Result
$sys.func.APPEND([1, 2, 3], 4) [1, 2, 3, 4]
$sys.func.APPEND(["a", "b", "c"], "d", ["e", "f"]) ["a", "b", "c", "d", "e", "f"]
$sys.func.APPEND(null, 1, 2, [3, 4]) [1, 2, 3, 4]

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

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

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"

GET

You can use the GET function to get the value from a list based on index.

The function takes the following arguments:

  • the list to get values

  • the index (0-indexed) of the desired value

For example:

Expression Result
$sys.func.GET([1, 2, 3], 0) 1
$sys.func.GET(["a", "b", "c"], 2) "c"

IDENTITY

The IDENTITY function returns the same composite object as its argument.

The function takes one argument:

  • the value to return

The function is particularly useful when you want to pass a composite object parameter value to a new parameter through parameter presets.

When referencing a composite object parameter that has a field named original (for example, an intent parameter that matches an entity at runtime, in which the original field captures the value written or spoken by the end-user), the default behavior is to return a scalar string that is present in the original field.

For instance, if an object currency-object representing the @sys.unit-currency system entity is:

    {
        "original" : "$400",
        "amount": 400,
        "currency": "USD"
    }

The following parameter preset configuration will set new-currency-object to be "$400" at runtime:

Parameter Value
new-currency-object $session.params.currency-object

In some cases, you need the full composite object, rather than the scalar representation, and you can then use the IDENTITY function to help pass the full object.

For example, the following parameter preset configuration will set new-currency-object to be the same object as currency-object at runtime, which contains fields original, amount, and currency:

Parameter Value
new-currency-object $sys.func.IDENTITY($session.params.currency-object)

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)

JOIN

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

If the elements in the list are not strings, the result of the function is equivalent to applying the TO_TEXT function to each element before joining.

The function takes the following arguments:

  • the delimiter
  • the list to join
  • (optional) the final delimiter

For example:

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

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

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

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)

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)

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

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

REMOVE

You can use the REMOVE function to remove value(s) from a list.

The function takes the following arguments:

  • the list to remove values.

  • an arbitrary number of values to be removed from the list.

    If the value is a list, the values inside the list will be removed one by one.

    All occurrences of the values will be removed from the list.

For example:

Expression Result
$sys.func.REMOVE([1, 2, 3, 2, 1], 2) [1, 3, 1]
$sys.func.REMOVE([1, 2, 3], 4) [1, 2, 3, 4]
$sys.func.REMOVE(["a", "b", "c", "a", "d"], "a", ["b", "c"]) ["d"]
$sys.func.REMOVE(null, 1, 2) null

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", "/")

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

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)