Handling dates and times in the bot

• FormatDate Helper →
• Date variable →
• Format variable →
• Examples →
• Unix-time →
• Choosing the formatting language, lang parameter →
• Time zone selection, timezone parameter →
• Using an arbitrary date format, fromFormat parameter →
• Getting and formatting the current time and date →
• Regular expressions for date conversion →
• How to configure the bot's response depending on the user's current time →
• How to compare dates →
• How to read dates from the user →

FormatDate Helper

You need it to change the date format.

Sometimes you need to format and show the date in some format, or turn the date into a day of the week, or convert one date format to another.

You can do all these things using the formatDate helper.

The helper can be used like this:

{{formatDate date format}}

• date is the name of a variable with a date
• format is the name of a variable with a valid template for the date format

Date variable

It must contain a date written in a suitable format.

formatDate accepts dates of the following forms:

• 2020-05-01
• 2020/05/01
• 2020.05.01
• 05.01.2020
• 05-01-2020

In all cases, the date of May 1, 2020 is recorded.

If you need to specify hours, minutes and seconds, write them through a colon, separate from the date by a space, for example:

2020-05-01 12:45:30.

formatDate is also able to work with exact computer dates and times received by Requests from some APIs:

2020-05-01T12:45:30.900Z

The following date is recorded here: May 1, 2020, 12 hours, 45 minutes, 30 seconds, 900 milliseconds.

Format variable

This is a string in which you can write the format into which we want to turn the date.

Years, months, days, hours, minutes and many, many other parameters can the format.

format does not have to be written to a variable, it can be written directly in the helper.

Let's say we have a date in the date variable: 2020-05-01, and we want to show it in the format familiar to the Russian language: 01.05.2020.

This can be done with such a helper record:

{{formatDate date "DD.MM.YYYY"}}

"DD.MM.YYYY" is a string with the format:

• DD means the day of the month with a leading zero;
• MM means the ordinal number of the month in the year with a leading zero;
• YYYY means the year written in four digits.

Records such as DD, MM, YYYY are called date format sequences, and formatDate supports a large number of them.

Of the most frequent, it is also worth noting:

• HH is the hours with a leading zero from 00 to 23;
• mm is the minutes with a leading zero from 00 to 59;
• ss is the seconds with a leading zero from 00 to 59.

Full list of possible sequences

Examples are given for the default language — English.

Examples

Here are some examples of working with dates using data from the table.

So you can output the day of the week as an ordinal number:

{{format Date "d"}}

In this format, days will be counted from 0 to 6, where 0 is Sunday, 1 is Monday, etc.

You can output the days of the week in the format "Mo", "Tu", etc. like this:

{{format Date "dd"}}

By default, the names of the days of the week are output in English:

{{format Date "dddd"}}

The date will be converted depending on what day of the week the user logged in.

So you can output the name of the month:

{{format Date "MMM"}}

With the help of the capitalize helper, the month will be displayed with a capital letter:

{{capitalize (format Date "MM")}}

So you can output the serial number of the week in the year:

{{formatDate 'w'}}

Together with formatDate, you can use helpers. For example, using addDate, you can add days, weeks, years and other time intervals to the current date.

So one day will be added:

{{add Date (format Date "DD.MM.YYYY HH:mm:ss") 1 "days" "DD.MM.YYYY HH:mm:ss"}}

You can change 1 to the desired number of days, which are added:

{{add Date (format Date "DD.MM.YYYY HH:mm:ss") 15 "days" "DD.MM.YYYY HH:mm:ss"}}

If you change "days"

to "months", months will be added:

{{add Date (format Date "DD.MM.YYYY HH:mm:ss") 1 "months" "DD.MM.YYYY HH:mm:ss"}}

to "weeks" , weeks will be added:

{{add Date (format Date "DD.MM.YYYY HH:mm:ss") 1 "weeks" "DD.MM.YYYY HH:mm:ss"}}

to "years", years will be added:

{{add Date (format Date "DD.MM.YYYY HH:mm:ss") 1 "years" "DD.MM.YYYY HH:mm:ss"}}

to "quarters", quarters will be added:

{{add Date (format Date "DD.MM.YYYY HH:mm:ss") 1 "quarters" "DD.MM.YYYY HH:mm:ss"}}

to "hours" , hours will be added:

{{add Date (format Date "DD.MM.YYYY HH:mm:ss") 2 "hours" "DD.MM.YYYY HH:mm:ss"}}

to "minutes", minutes will be added:

{{add Date (format Date "DD.MM.YYYY HH:mm:ss") 2 "minutes" "DD.MM.YYYY HH:mm:ss"}}

to "seconds" , seconds will be added:

{{add Date (format Date "DD.MM.YYYY HH:mm:ss") 2 "seconds" "DD.MM.YYYY HH:mm:ss"}}

Unix-time

Also often referred to as Unix timestamp or simply timestamp.

This is a special way to record the exact date and time as a number.

The number shows how many milliseconds have passed since the beginning of the Unix epoch — 00:00:00 on January 1, 1970 GMT.

For example, on May 1, 2020, 12 hours, 45 minutes, 30 seconds, 900 milliseconds in timestamp will be equal to 1588337130900 milliseconds.

Unix-time can often be obtained in requests from different APIs.

Unix time can be used in formatDate. For example, we can easily verify when the Unix era began with such formatting:

{{formatDate 0 "DD.MM.YYYY HH:mm:ss:SSS"}}

If you run such a template, you will see: 01.01.1970 03:00:00:000.

Three o'clock in the morning on January 1, 1970. 3 a.m., because formatDate uses the Moscow time zone by default.

The parameters in the example are simple:

• 0 — zero milliseconds, since the beginning of the Unix epoch
• "DD.MM.YYYY HH:mm:ss:SSS" — Days.Months.Years Hours:Minutes:Seconds:Milliseconds format

Note that in PHP, timestamp is the time in seconds,

and to use it in formatDate, you need to multiply it by 1000 with the multiply helper:

{{formatDate (multiply timestampFromPHP 1000) "DD.MM.YYYY"}}

Choosing the formatting language, lang parameter

For some sequences, the choice of language is important. The default language is English, but it can be changed, for example, to Russian.

If we use a helper like this:

{{formatDate date "DD MMMM YYYY"}}

without changing the language, we will get such a result: 01 May 2020.

Let's say we want the date to be shown in Russian, not in English.

This can be done using the lang parameter:

{{formatDate date "DD MMMM YYYY" lang="ru"}}

now the language will be Russian: 01 мая 2020.

Time zone selection, timezone parameter

By default, the helper uses the Moscow time zone.

This may be inconvenient if you need to support another region or even several.

To change the time zone, you can use the timezone parameter:

 {{formatDate date "HH:mm" timezone="America/New_York"}}

In the example above, we specified the New York time zone, and it changed the hours and minutes when formatting the date.

Using an arbitrary date format, fromFormat parameter

formatDate itself can only work with standardized dates.

But sometimes dates are in other formats.

For example, in Russian a date is usually written as Day.Month.Year, but formatDate recognizes such a date incorrectly — as a Month.Day.Year. Fortunately, this can be easily changed using the fromFormat parameter.

Let's say we have such a date in the date variable — May 1, 2020 — in the form of a string:

01.05.2020

If we just try to convert it to another form, for example, to separate a month:

{{formatDate date "MM"}}

we will get the wrong month: 01, i.e. January.

To tell formatDate the exact format in which our date is recorded, you can use the special fromFormat parameter:

{{formatDate date "MM" fromFormat="DD.MM.YYYY"}}

So we specified exactly in what format the original date is stored, and now we can work with it.

In the fromFormat parameter, you can use any date formatting sequences to create an incoming date format that will be convenient for you.

Getting and formatting the current time and date

Using formatDate, you can get the formatted current time and date.

There are two ways to do this.

Using the helper now

This helper gets Unix time back in milliseconds.

We can use it to get, for example, today's date:

{{formatDate (now) "DD.MM.YYYY"}}

Or the day of the week:

{{formatDate (now) "dddd" lang="ru"}}

Or hours and minutes:

{{formatDate (now) "HH:mm"}}

Or make up any other date format from possible sequences.

Using only the format

Now is not necessary to use. If you do not pass the date to formatDate, and use only the format, it will understand that you want to use a template for the current time:

{{formatDate "DD.MM.YYYY"}}

{{formatDate "dddd" lang="ru"}}

{{formatDate "HH:mm"}}

All these three examples completely coincide with the use of the now helper.

Regular expressions for date conversion

To get the date in the required format, use regular expressions:

^\d\d\.\d\d\.\d\d\d\d$  — for dates in the format dd.mm.yyyy, for example 15.05.2000

^\d\d\d\d\/\d\d\/\d\d$  — for dates in yyyy/mm/dd format, for example 2000/05/15

How to configure the bot's response depending on the user's current time

Get and convert the current time to required format

Get the current date and time with helper:

{{formatDate "DD.MM.YYYY HH:mm"}}

Set a value to Time variable with Assign a variable component. Since we only want to know when user entered the bot, we need to remove the date from the helper and leave only hours and minutes:

{{formatDate "HH:mm"}}

Process the time and translate to set screens

Put Fork component to the screen. Set The variable name to Time.

It’s easier to make the regular expression for the first interval — 10 to 19:

^1[0-8]\:[0-5][0-9]$

Add this regular expression to the Fork value. In Data Type select Regular expression. The default target is 19 to 10 interval.

Format the bot reply screens and we’re done.

((10|11|12):[0-9]{2}:[0-9]{2}\s(am)|([1-6]{1}):[0-9]{2}:[0-9]{2}\s(pm))

How to compare dates

Let’s make the users who wrote less than 15 days after the purchase and the ones who wrote after the 15-day period get messages with different texts.

This can be useful if the discount on the product is valid only 15 days after purchase or for other similar cases.

1. Ask the user when he made the last purchase.

2. Write the answer to Usday variable with the Input from the user. Select Date data type.

3. Convert today's date into seconds with the helper

{{now}}

4. Convert the date on which the last purchase was made into milliseconds using another helper:

{{formatDate Usday 'x'}}

Thus, we overwrite the variable Usday.

5. Subtract from today the date on which the last purchase was made:

{{subtract today Usday}}

Let's write the result of the subtraction to diff variable

6. Using gt comparison helper, determine whether more or less than 15 days passed:

{{#gt (toInt diff) 1296000000}}More than 15 days{{else}}Less than 15 days{{/gt}}

7. Check days variable with a fork and direct users to different screens depending on the time passed.

8. Design separate screens for those who wrote later than in 15 days and those who wrote earlier.

How to read dates from the user

This way of reading the date will be useful in the case when a date in the format 01.01.2000 or 01\01\2000 is required from the user and the bot should not skip numbers that are not a date.

The correctness of the date that the user sent can be checked using User Input with the Regular Expression data type, the regular expression should be like this:

\d{2}.\d{2}.\d{4}

Then add Fork.

The variable name from which the fork will take the value should be the same as in User Input. So we will check this variable in the Fork.

Add one Goal with the Date data type to Fork. Expand Fork settings and add Name of the variable where the date entered by the user will be recorded. In the message after Fork, you can output this date or use it in the further scenario of the bot.