System entities reference

This reference section provides complete information about the available system entities. For more information about system entities and how to use them, refer to Defining entities and search for "Enabling system entities".

System entities are available in Brazilian Portuguese, English, French, Italian, Spanish, and German.

@sys-number entity

The @sys-number system entity detects numbers that are written using either numerals or words. In either case, a numeric value is returned.

Recognized formats

  • 21
  • twenty one
  • 3.13

Metadata

  • .numeric_value - the canonical numeric value as an integer or a double

Returns

  • For the input twenty or 1,234.56, @sys-number returns these values:

    Attribute Type Returned for twenty Returned for 1,234.56
    @sys-number string 20 1234.56
    @sys-number.literal string twenty 1,234.56
    @sys-number.location array [0,6] [0,8]
    @sys-number.numeric_value number 20 1234.56
  • For the input veinte or 1.234,56, in Spanish, @sys-number returns these values:

    Attribute Type Returned for veinte Returned for 1.234,56
    @sys-number string 20 1234.56
    @sys-number.literal string veinte 1.234,56
    @sys-number.location array [0,6] [0,8]
    @sys-number.numeric_value number 20 1234.56

    You get equivalent results for other supported languages.

@sys-currency entity

The @sys-currency system entity detects monetary currency values that are expressed in an utterance with a currency symbol or currency-specific terms. A numeric value is returned.

Recognized formats

  • 20 cents
  • Five dollars
  • $10

Metadata

  • .numeric_value: the canonical numeric value as an integer or a double, in base units
  • .unit: the base unit currency code (for example, 'USD' or 'EUR')

Returns

  • For the input twenty dollars or $1,234.56, @sys-currency returns these values:

    Attribute Type Returned for twenty dollars Returned for $1,234.56
    @sys-currency string 20 1234.56
    @sys-currency.literal string twenty dollars $1,234.56
    @sys-currency.numeric_value number 20 1234.56
    @sys-currency.location array [0,14]
    @sys-currency.unit string USD* USD

    *@sys-currency.unit always returns the 3-letter ISO currency code.

  • For the input veinte euro or €1.234,56, in Spanish, @sys-currency returns these values:

    Attribute Type Returned for veinte euro Returned for €1.234,56
    @sys-currency string 20 1234.56
    @sys-currency.literal string veinte euro €1.234,56
    @sys-currency.numeric_value number 20 1234.56
    @sys-currency.location array [0,11] [0,9]
    @sys-currency.unit string EUR* EUR

    You get equivalent results for other supported languages and national currencies.

    *@sys-currency.unit always returns the 3-letter ISO currency code.

@sys-percentage entity

The @sys-percentage system entity detects percentages that are expressed in an utterance with the percent symbol or written out using the word percent. In either case, a numeric value is returned.

Recognized formats

  • 15%
  • 10 percent

Metadata

.numeric_value: the canonical numeric value as an integer or a double

Returns

  • For the input 1,234.56%, @sys-percentage returns these values:

    Attribute Type Returned for 1,234.56%
    @sys-percentage string 1234.56
    @sys-percentage.literal string 1,234.56%
    @sys-percentage.location array [0,9]
    @sys-percentage.numeric_value number 1234.56
  • For the input 1.234,56%, in Spanish,@sys-currency returns these values:

    Attribute Type Returned for 1.234,56%
    @sys-percentage string 1234.56
    @sys-percentage.literal string 1.234,56%
    @sys-percentage.location array [0,9]
    @sys-percentage.numeric_value number 1234.56

    You get equivalent results for other supported languages.

@sys-date and @sys-time entities

The @sys-date system entity extracts mentions such as Friday, today, or November 1. The value of this entity stores the corresponding inferred date as a string in the format "yyyy-MM-dd" e.g. "2016-11-21". The system augments missing elements of a date (such as the year for “November 21”) with the current date values.

The @sys-time system entity extracts mentions such as 2pm, at 4, or 15:30. The value of this entity stores the time as a string in the format "HH:mm:ss". For example, "13:00:00."

Date-time mentions

Mentions of date and time, such as now or two hours from now are extracted as two separate entity mentions - one @sys-date and one @sys-time. These two mentions are not linked to one another except that they share the same literal string that spans the complete date-time mention.

Multi-word date-time mentions such as on Monday at 4pm are also extracted as two @sys-date and @sys-time mentions. When mentioned together consecutively they also share a single literal string that spans the complete date-time mention.

Date and time ranges

Mentions of a date range such as the weekend, next week, or from Monday to Friday are extracted as a pair of @sys-date entity mentions that show the start and end of the range. Similarly, mentions of time ranges such as from 2 to 3 are extracted as two @sys-time entities, showing the start and end times. The two entities in the pair share a literal string that corresponds to the full date or time range mention.

Time zones

Mentions of a date or time that are relative to the current time are resolved with respect to a chosen time zone. By default, this is UTC (GMT). This means that by default, REST API clients located in time zones different from UTC will observe the value of now extracted according to the current UTC time.

Optionally, the REST API client can add the local timezone as the context variable $timezone. This context variable should be sent with every client request. For example, the $timezone value should be America/Los_Angeles, EST, or UTC. For a full list of supported time zones, see Supported time zones.

When the $timezone variable is provided, the values of relative @sys-date and @sys-time mentions are computed based on the client time zone instead of UTC.

Examples of mentions relative to time zones:

  • now
  • in two hours
  • today
  • tomorrow
  • 2 days from now

Recognized formats

  • November 21
  • 10:30
  • at 6 pm
  • this weekend

Returns

  • For the input November 21 @sys-date returns these values:

    Attribute Type Returned for November 21
    @sys-date.literal string November 21
    @sys-date string 20xx-11-21 *
    @sys-date.location array [0,11]
    @sys-date.calendar_type string GREGORIAN
    • @sys-date always returns the date in this format: yyyy-MM-dd.
    • * Returns the next matching date. If that date has already passed this year, this returns next year's date.
  • For the input at 6 pm @sys-time returns these values:

    Attribute Type Returned for at 6 pm
    @sys-time.literal string at 6 pm
    @sys-time string 18:00:00
    @sys-time.location array [0,7]
    @sys-time.calendar_type string GREGORIAN
    • @sys-time always returns the time in this format: HH:mm:ss.

Date and Time methods

Several methods are available to work with date and time. Use these methods to work with the extracted mentions of @sys-date or @sys-time.

.before(String date or time)

  • For example:
    • @sys-time.before('12:00:00')
    • @sys-date.before('2016-11-21')
  • Determines whether the date/time value is before the date/time argument.
  • If comparing different items, such as time vs. date, date vs. time, and time vs. date and time, the method returns false and an exception is printed in the response JSON log output.log_messages.
    • For example, @sys-date.before(@sys-time).
  • If comparing date and time vs. time the method ignores the date and only compares times.

.after(String date/time)

  • Determines whether the date/time value is after the date/time argument.
  • Analogous to .before().

.sameOrBefore(String date/time)

  • Determines whether the date/time value is before or the same as the date/time argument.

.sameOrAfter(String date/time)

  • Determines whether the date/time value is after or the same as the date/time argument.
  • Analogous to .after().

.sameMoment(String date/time)

  • Determines whether the date/time value is the same as the date/time argument.

.reformatDateTime(String format)

  • Formats date and time strings to the format desired for user output.
  • Returns a formatted string according to the specified format:
    • MM/dd/yyy for 12/31/2016
    • h a for 10pm
  • Format follows the Java SimpleDateFormat rules.
  • When trying to format time only, the date is treated as 1970-01-01.

now()

  • Static function.
  • Returns a string with the current date and time in the format yyyy-MM-dd HH:mm:ss.
  • The other date/time methods can be invoked on date-time values that are returned by this function and it can be passed in as their argument.
  • If the context variable $timezone is set, this function returns dates and times in the client's time zone.

Example of a dialog node with now() used in the output field:

{
  "conditions": "#what_time_is_it",
  "output": {
    "text": "<? now() ?>" 
   }
}

Example of now() in node's conditions (to decide if it is still morning):

{
  "conditions": "now().before('12:00:00')",
  "output": {
    "text": "Good morning!"
   }
}