DateTime is a special data type that stores date and time.

DateTime API contains a list of methods used to manipulate DateTime in order to:

• format date and time to show or read them to the user in responses,
• compare and change DateTime by adding or substracting years, months, days or minutes,
• get specific properties from DateTime as Numbers: a year, a month, a day, an hour or a minute.

📘

Understanding and displaying DateTime

DateTime data type is, technically, a specific kind of Object. This Object contains all of the information needed to display and manipulate date and time.

But, there is no way to actually see this 'DateTime Object'. For example, if you print out the current DateTime using {system.currentTime} in the response, the bot will respond with something like that: 2023-05-24 13:36. This doesn't look like an Object - it's because this is actually an already formatted String which represents 'DateTime Object' stored in system.currentTime.

And so, the only way to access, manipulate, and format specific information from 'DateType Objects' is by using DateTime API methods listed below 👇

List of DateTime methods

🚧

DateTime methods listed below cannot be used on any data type except for DateTime, so make sure that you don't try using them on a String or a Number.

Obtaining and creating DateTime

You can only use DateTime methods on values of DateTime type, and not Strings nor Numbers. For example, "1998/04/04".getYear() will throw an error.

There are 3 ways to obtain or create DateTime:

Get current time with system.currentTime

To get current date and time, use system.currentTime. This System API property gets a current time and date as a DateTime. This is why you can use DateTime methods directly on it, eg. system.currentTime.formatAsTime().

Get DateTime from user input using NLU

To get date and time recognized in the user input, use nlu.variables.time.value. This NLU API property obtains a DateTime value from "time" entity recognized in the user input.

You can also use nlu.variablesList.filter(el=>el.name=time) to get an array of all of the "time" entities recognized in the user input.

Create DateTime with toDateTime()

toDateTime() is one of the String methods. It converts a String into a DateTime value. This is the only way to create DateTime value on your own. For this method to work, the given String has to have a specific format:

Date: YYYY-MM-DD

Date with time: YYYY-MM-DDTHH:mm

Full DateTime String: YYYY-MM-DDTHH:mm:ss.SSS+Z

Where:

YYYY - year
MM - month
DD - day of the month
HH - hours
mm - minutes
ss - seconds
SSS - miliseconds
Z - time zone offset

You can either specify both date and time (YYYY-MM-DDTHH:mm) or just a date (YYYY-MM-DD) . The following code snippet contains a few examples of correct expressions that use toDateTime() to convert Strings into DateTime:

"1990-10-30".toDateTime()

"1990-10-30T11:00".toDateTime()

("1990" + "-10-" + system.currentTime.getDay()).toDateTime()

When you get a date and time formatted as a String (eg. from REST API integration), you can use available String methods to achieve a format that is acceptable by toDateTime() method.

For example, to convert memory.response.date into DateTime if memory.response.date = "1997/07/20", use:

memory.response.date.replace("/","-").toDateTime()

DateTime methods

getYear()

Returns the year for the given DateTime.

Result: Number

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.getYear()

//Result:
1975

//for:
//system.currentTime = "2023-05-24 13:36"

//Response input:
The year is {system.currentTime.getYear()}.

//Bot's response:
"The year is 2023."

getMonth()

Returns the Number of the month for the given DateTime.

Result: Number from 1 to 12

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.getMonth()

//Result:
5

//for:
//system.currentTime = "2023-05-24 13:36"
//memory.months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]

//Response input:
The current month is the {system.currentTime.getMonth()}th month of the year.
In English, we call it {memory.months[system.currentTime.getMonth() - 1]}

//Bot's response:
"The current month is the 5th month of the year. In English, we call it May."

This method returns Numbers instead of month names so that it can be used with any language. To print out the name of the month:

1. Create an array containing the names of the months (in any language imaginable).
2. Access an element of the array by index with the index equal to .getMonth() - 1.

Here is an example:

//for:
//system.currentTime = "2023-05-24 13:36"
//memory.months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]

memory.months[system.currentTime.getMonth() - 1]

//Result:
"May"

getDay()

Returns the day of the month for the given DateTime.

Result: Number from 1 to 31

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.getDay()

//Result:
24

//for:
//system.currentTime = "2023-05-24 13:36"

//Response input:
Today is {system.currentTime.getDay()}th day of the month.

//Bot's response:
"Today is 24th day of the month."

getHour()

Returns the hour for the given DateTime in the 24-Hour Time Format.

Result: Number from 0 to 23

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.getHour()

//Result:
13

//for:
//system.currentTime = "2023-05-24 13:36"

//Response input:
Your request will be reviewed in about an hour, until {system.currentTime.getHour() + 1}:{system.currentTime.getMinute()}.

//Bot's response:
"Your request will be reviewed in about an hour, until 14:36."

getMinute()

Returns the minute for the given DateTime.

Result: Number from 0 to 59

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.getMinute()

//Result:
36

//for:
//system.currentTime = "2023-05-24 13:36"

//Response input:
{system.currentTime.getMinute()} minutes have passed since 1pm.

//Bot's response:
"36 minutes have passed since 1pm."

getDayOfWeek()

Returns the day of the week (as a Number) for the given DateTime.

Result: Number from 1 to 7, where 1 is Monday and 7 is Sunday.

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.getDayOfWeek()

//Result:
3

//for:
//system.currentTime = "2023-07-25 15:20"
//memory.weekDays = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
//memory.weekDayIndex = system.currentTime.getDayOfWeek()

//Response input:
Today is {memory.weekDays[memory.weekDayIndex - 1]}. It is the {memory.weekDayIndex}th day of the week.

//Bot's response:
"Today is Thursday. It is the 4th day of the week."

This method returns Numbers instead of weekday names so that it can be used with any language. To print out the name of the weekday:

1. Create an array containing the names of the weekdays (in any language imaginable).
2. Access an element of the array by index with the index equal to .getDayOfWeek() - 1.

Here is an example:

//for:
//system.currentTime = "2023-05-24 13:36"
//memory.weekDays = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]

memory.weekDays[system.currentTime.getDayOfWeek() - 1]

//Result:
"Wednesday"

formatAsTime()

Returns a String representing the time for the given DateTime in the HH:mm format.

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.formatAsTime()

//Result:
"13:36"

//for:
//system.currentTime = "2023-05-24 13:36"

//Response input:
Your request has been sent at {system.currentTime.formatAsTime()}.

//Bot's response:
"Your request has been sent at 13:36."

formatAsDate()

Returns a String representing the date for the given DateTime in the yyyy-MM-dd format.

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.formatAsDate()

//Result:
"2023-05-24"

//for:
//system.currentTime = "2023-05-24 13:36"

//Response input:
Your request has been sent on {system.currentTime.formatAsDate()}.

//Bot's response:
"Your request has been sent on 2023-05-24."

format(custom)

Returns a String representing the given DateTime in a custom, pattern-based format.

The method's argument is a pattern (String) according to which DateTime will be formatted. For example, system.currentTime.format("dd.MM.yyyy") will return a String formatted like that: "24.05.2023".

If an argument is omitted, the method will return a full, unformatted String representing DateTime. For example, system.currentTime.format() will return such String: "2023-05-24T10:24:15.476+02:00"

The following tables contains all of the symbol patterns which you can use to custom format date and/or time. Below the table, you'll find many examples of using format() method.

Pattern-based formatting

Full list available on joda.org.

format(custom) examples

//for:
//system.currentTime = "2023-05-26 06:05"

system.currentTime.format("MMM yy")
//Result:
"May 26"

{system.currentTime.format("dd/MM/y")}
//Result:
"26/05/2023"

{system.currentTime.format("d/M (EEEE)")}
//Result:
"26/5 (Friday)"

{system.currentTime.format("'week' w 'of year' y")}
//Result:
"week 21 of year 2023"

{system.currentTime.format("D'th day of year' yy")}
//Result:
"146th day of year 23"

//for:
//system.currentTime = "2023-05-26 16:11"

{system.currentTime.format("H.mm")}
//Result:
"16.11"

{system.currentTime.format("h:mm a")}
//Result:
"4:11 PM"

{system.currentTime.format("after h a")}
//Result:
"after 4 PM"

{system.currentTime.format("m'th minute of an hour'")}
//Result:
"11th minute of an hour"

Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '?' will appear in the resulting time text even they are not embraced within single quotes.

plusYears(Number)

Returns new DateTime increased or decreased by the Number of years given as an argument.

To increase DateTime, use positive Numbers. To decrease DateTime, use negative Numbers.

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.plusYears(1)
//Result:
"2024-05-24 13:36"
system.currentTime.plusYears(-2)
//Result:
"2021-05-24 13:36"

//for:
//system.currentTime = "2023-05-24 13:36"
//memory.courseYears = 5

//Response input:
If you start the course now, you will finish it in {system.currentTime.plusYears(memory.courseYears).getYear()}.

//Bot's response:
"If you start the course now, you will finish it in 2028."

plusMonths(Number)

Returns new DateTime increased or decreased by the Number of months given as an argument.

To increase DateTime, use positive Numbers. To decrease DateTime, use negative Numbers.

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.plusMonths(5)
//Result:
"2023-10-24 13:36"
system.currentTime.plusMonths(-10)
//Result:
"2022-07-24 13:36"

//for:
//system.currentTime = "2023-05-24 13:36"

//Response input:
The results of your application will be published on {system.currentTime.plusMonths(2).formatAsDate()}.
//Bot's response:
"The results of your application will be published on 2023-07-24".

plusDays(Number)

Returns new DateTime increased or decreased by the Number of days given as an argument.

To increase DateTime, use positive Numbers. To decrease DateTime, use negative Numbers.

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.plusDays(10)
//Result:
"2023-06-03 13:36"
system.currentTime.plusMonths(-4)
//Result:
"2022-07-20 13:36"

//for:
//system.currentTime = "2023-05-24 13:36"
//memory.dateGiven = "2023-06-03T00:00:00.000+02:00"

//Response input:
The date given is {if (system.currentTime.plusDays(7) < memory.dateGiven) "not " else ""}within the next week.

//Bot's response:
"The date given is within not the next week.

plusMinutes(Number)

Returns new DateTime increased or decreased by the Number of minutes given as an argument.

To increase DateTime, use positive Numbers. To decrease DateTime, use negative Numbers.

//for:
//system.currentTime = "2023-05-24 13:36"

system.currentTime.plusMinutes(60)
//Result:
"2023-05-24 14:36"
system.currentTime.plusMonths(-4)
//Result:
"2023-05-24 13:32"

//for:
//system.currentTime = "2023-05-24 13:36"

//Response input:
Your test results will be ready in two hours, until {system.currentTime.plusMinutes(120).formatAsTime()}.

//Bot's response:
Your test results will be ready in two hours, until 15:56.