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

Example of expression syntax within a text message.

For existing bots Please note that expression syntax needs to be enabled on your account. To enable expression syntax on your account, please contact support. 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.

Use functions of expression syntax inside a Text step

Use variable of expression syntax inside a Text step

Condition block

Use expression syntax within a Condition statement as a variable.

Use a variable of expression syntax as a variable inside a Condition statement.

Read below for use case examples:

• Get the current time
• Downcase
• Create a list

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:

Name	Summary	Example
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.

Precedence	Operator	Description	Associativity
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.

Use expression syntax to return the current time within a conversation.

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.

Use a custom expression syntax to get the current time in your customer's timezone.

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)

Use expression syntax to standardize your user input.

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

Retrieve list elements by using expression syntax.

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

Examples of variable names that are not compatible anymore with 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.