Expression syntax

Get the flexibility to use code syntax functions in your bot without the need of extensive coding skills.

Expression syntax refers to the structure of statements in code language used to incorporate dynamic content, variables, or specific built-in functions in your chatbot.

For existing bots Please note that expression syntax needs to be enabled on your account. To enable expression syntax on your account, please sign up to this form. For new bots Expression syntax is enabled by default.

Please also be aware about the breaking changes taking place for existing bots.

Unlike traditional code actions, which require JavaScript knowledge and can be resource-intensive, expression syntax on Chatlayer makes advanced functionalities accessible without the need for extensive coding skills.

In this article, the term 'expression' refers to combining identifiers by using functions, operators, constants, and values when coding. Therefore, it should not be confused with the concept of expressions in your NLP model.

How to use expression syntax

Expression syntax can be used inside Text steps and Conditions, using specific data types, operators and functions.

Use syntax functions in your bot

To use expression syntax in your chatbot:

  1. Open your block.

  2. Go to your text field.

  3. Type ‘{' inside a text field or type the name of a built-in function. Some use-cases are shown below.

Text step

Use expression syntax inside a text step to display the result inside your bot message.

Condition block

Use expression syntax within a Condition statement as a variable.

Read below for use case examples:

Functions

Functions, whether built-in or custom, form the backbone of expression syntax. They drive specific tasks and operations within the conversational flow of your chatbot.

Built-in functions

Here is the list built functions that you can use:

NameSummaryExample

ABS

Returns the absolute value of a number.

operation: (n: any) => Math.abs(n)

APPEND

Adds one or more items to the end of a list.

operation: (arr: any, ...items: any[]) => arr.concat(...items)

BASE64_DECODE

Decode Base64 encoded text.

operation: (text: any) => Buffer.from(text, 'base64').toString('utf8')

BASE64_ENCODE

Encode text using the Base64 encoding algorithm.

operation: (text: any) => Buffer.from(text + '', 'utf8').toString('base64')

CAPITALIZE

Makes the first character of text uppercase and converts the remaining characters to lowercase.

operation: (value: any) => lodash.capitalize(value)

CEIL

Rounds up and returns the smallest integer greater than or equal to a given number.

operation: (n: any) => Math.ceil(n)

DAY

Returns the day from the given date or the current day if no date given (1-12).

operation: (d: any) => DateTime.fromMillis(d || DateTime.now().toMillis()).day

DOWNCASE

Makes each character in text lowercase.

operation: (value: any) => lodash.toLower(value)

FIRST

Returns the first element of a list.

operation: (value: any) => lodash.first(value)

FLOOR

Rounds down and returns the largest integer less than or equal to a given number.

operation: (n: any) => Math.floor(n)

FORMAT

Returns the date formatted according to the format string.

operation: (d: any, format: any, locale: any) => DateTime.fromMillis(d).toFormat(format, { locale: locale || 'en' })

HOUR

Returns the hour from the given date or the current hour if no date given (0-23).

operation: (d: any) => DateTime.fromMillis(d || DateTime.now().toMillis()).hour

INCLUDES

Returns TRUE if target (which can be text, an object, or an array) includes value otherwise returns FALSE.

operation: (haystack: any, needle: string) => lodash.includes(haystack, needle)

JSON_PARSE

Parses a serialized JSON value.

operation: (value: any) => JSON.parse(value)

LAST

Returns the last element of a list.

operation: (value: any) => lodash.last(value)

MAX

Returns the max value from the given args.

operation: (...args: any) => Math.max(...args)

MD5

Calculates the hex encoded MD5 hash of some text.

operation: (t: any) => crypto.createHash('md5').update(t + '').digest('hex')

MINUTE

Returns the minute from the given date or the current minute if no date given (0-59).

operation: (d: any) => DateTime.fromMillis(d || DateTime.now().toMillis()).minute

MONTH

Returns the month from the given date or the current month if no date given (1-12).

operation: (d: any) => DateTime.fromMillis(d || DateTime.now().toMillis()).month

NOW

Returns the current date and time.

operation: () => DateTime.now().toMillis()

PARSE

Parses a date formatted according to the format string.

operation: (d: string, format: any, locale: any) => DateTime.fromFormat(d, format, { locale }).toMillis()

ROUND

Returns the value of a number rounded to the nearest precision.

operation: (n: any, precision = 0) => Math.round(n * Math.pow(10, precision)) / Math.pow(10, precision)

SPLIT

Divides the input text into a list using the delimiter as a separator.

operation: (text: any, delimiter: any) => (text + '').split(delimiter + '')

STRINGIFY

Serializes a value into a JSON string.

operation: (value: any) => stringify(value, null, 0)

TODAY

Returns today's date with time set to 00:00.

operation: () => DateTime.now().startOf('day').toMillis()

TOMORROW

Returns tomorrow's date with time set to 00:00.

operation: () => DateTime.now().startOf('day').plus({ days: 1 }).toMillis()

TO_NUMBER

Converts a value to a number.

operation: (value: any) => value - 0

TO_STRING

Converts a value to string.

operation: (value: any) => value?.toString()

UUID

Generates a universally unique identifier (V4).

operation: () => uuid()

WEEKDAY

Get the day of the week. 1 is Monday and 7 is Sunday.

operation: (d: any) => DateTime.fromMillis(d || DateTime.now().toMillis()).weekday

YEAR

Returns the year from the given date or the current month if no date given.

operation: (d: any) => DateTime.fromMillis(d || DateTime.now().toMillis()).year

YESTERDAY

Returns yesterday's date with time set to 00:00.

operation: () => DateTime.now().startOf('day').plus({ days: -1 }).toMillis()

Custom functions

You can create your own functions as you please, using the available operators.

Some examples of custom functions:

  • 1 + 2

  • 1 + (2 * 3)

  • MAX(1,2)

  • a ? b : c

  • a.b.c.d

Operators

Operations encompass a range of actions, calculations, and data manipulations in the code. Using operators provides more dynamic and context-aware responses to your chatbot.

PrecedenceOperatorDescriptionAssociativity

1

()

Function call

Left-to-right

.

Qualified name or field access

[]

Indexing

2

- (unary)

Negation

Right-to-left

!

Logical NOT

3

*

Multiplication

Left-to-right

/

Division

%

Remainder

4

+

Addition

- (binary)

Subtraction

5

== != < > <= >=

Relations

6

&&

Logical AND

7

?:

Conditional

Right-to-left

Data types

We support a subset of JavaScript types to provide flexibility in your bot-building journey:

  • number

  • string

  • boolean

  • map

  • list

  • null

Expression syntax use cases

In this section, find some use case examples where expression syntax is used

Get the time

There are multiple ways that you can return information about time with expression syntax functions.

Get the current time

Imagine that you your bot to know or display the current time. Time is easy to retrieve with the following functions:

  • FORMAT() returns the time according to a string.

  • NOW() returns the current date and time based on the UTC timezone.

Combine these to create a function that returns the time with hours and minutes:

 {FORMAT(NOW(), "T")}

To learn more about time formatting, have a look at this table.

Get a UTC+1 timezone

Imagine a scenario where your end-users are located on a UTC+1 timezone. For them to know if your store is open now, your bot needs to determine what time it is in Belgium.

You can use the functions:

  • NOW() returns the current date and time based on the UTC timezone.

  • HOUR() extracts the hour from the current time.

  • HOUR(NOW()) extracts the hour component from the current UTC timezone.

  • +1 adds 1.

Combine these functions into the following custom expression:

{HOUR(NOW())+1}

This expression extracts the hour of the current UTC timezone and adds 1 to it so that it fits the Belgian time.

Downcase

Let's say that your customer has given its name in capital letters. You want to convert all the input characters to lowercase so that it can follow a standardized process.

  • DOWNCASE() converts all characters in a given text to lowercase.

  • @username is the variable name under which your customer name is saved.

Combine these elements into a custom function which downcases all the characters in your user name:

DOWNCASE(@userName)

Create a list

Let's say you have a message that consists in a list of elements which you would like to handle separately, for instance a list of pieces of fruit.

Your example message would be the following string:

"Apple Banana Orange"
  • SPLIT() divides a string into a list

  • FIRST() and LAST() retrieve the first and last elements of a list, respectively

Combine those functions so that you return the first and last element of the fruit list:

{FIRST(SPLIT("Apple Banana Orange"," "))}
{LAST(SPLIT("Apple Banana Orange"," "))}

🚨 Breaking changes

To ensure a smooth transition to expression syntax, it's crucial to address some breaking changes that might impact your current bot flows.

Variable name restriction

Existing variable names like a-b, a b, number or using '-' under Go to variables are not compatible anymore.

Please make sure to adjust your variable names according to the new expression syntax.

JavaScript identifier requirement

Only valid JavaScript identifiers is supported. If your variables don't comply, tweak them now to avoid any hiccups. Refer to this documentation for detailed guidelines.

Removal of the| operator

The | operator is no longer supported. If it's part of your bot flow, make the necessary adjustments to align with the new syntax.

Before the upgrade, if your bot flow involved using the | operator, it might look like this:

notUnderstoodCounter|increment

With the expression syntax upgrade, the | operator is no longer be supported. Please modify your variable name.

JSON.stringif no longer compatible

Ensure to review your previous variables and confirm that none of them rely on JSON.stringify. Please use STRINGIFY or TO_STRING instead.

Last updated