Working with Dates and Times in VisualMaker¶

VisualMaker offers powerful tools for handling dates and times. These capabilities allow you to format dates, perform time calculations, and customize the behavior of your bots based on time.

Date and Time format¶

In VisualMaker, dates and times are represented in the format:

DD-MM-YYYY HH:MM:SS

DD: Day of the month (01-31).
MM: Month of the year (01-12).
YYYY: Year (4 digits).
HH: Hour in 24-hour format (00-23).
MM: Minutes (00-59).
SS: Seconds (00-59).

For example:

19-01-2025 12:01:55

Date variables¶

Date type variables can store dates to be reused in your bot.

Creating a date variable¶

First, create the variable by going to:

🔑 Manage → 🗃 Variables → 💠 Create variable 💠
In ➡️ Data type:, select date 📅.
Enter the variable name.

Using date variables¶

Date variables allow you to store dates for validation purposes. For example, if you want a button to be pressed only once every 15 minutes, a date variable will make this possible. We will see examples of this later.

Displaying a date variable¶

Once the variable is created and a date is saved inside it (we'll see how later), you can display its content in messages and actions as follows:

{my_variable}

Assuming you created a variable called my_variable, this will display something like:

19-01-2025 14:05:30

What are variables?

For more information about variables, click here.

Dates in UTC¶

It is recommended to work with dates and times in UTC (Coordinated Universal Time). You can use the date_now() function to get the current date and time without local adjustments. This is the function you will use most when working with dates in VisualMaker.

Displaying Dates and Times in messages¶

You can insert dates and times in messages using functions within expressions:

Basic example:

The current date and time is: {date_now()}

This will display something like:

The current date and time is: 20-01-2025 15:45:12

Expressions

Functions are represented using expressions, so they must be enclosed in curly braces { }.

Functions for working with Dates and Times¶

1. date_now()¶

Returns the current date and time in UTC.

{date_now()} ➔ "20-01-2025 15:48:00"

2. date_now_tz()¶

Returns the current date and time according to the configured time zone.

{date_now_tz()} ➔ "20-01-2025 13:48:00"

3. apply_tz()¶

Applies the bot's time zone to a given date and time.

{apply_tz("01-03-2024 00:07:48")} ➔ "01-03-2024 02:07:48"

4. date_format()¶

Formats a date and time to a specific format.

{date_format("20-01-2025 15:30:00", "%d/%m/%Y")} ➔ "20/01/2025"

5. time_passed()¶

Calculates the time elapsed from a given date until now.

{time_passed("19-01-2025 15:30:00", "hours")} ➔ "24"

6. time_left()¶

Calculates the time remaining until a given date.

{time_left("21-01-2025 15:30:00", "days")} ➔ "1"

7. time_add()¶

Adds a specified amount of time to a given date.

{time_add("20-01-2025 15:30:00", 2, "days")} ➔ "22-01-2025 15:30:00"

8. time_diff()¶

Calculates the difference between two dates.

{time_diff("20-01-2025", "22-01-2025", "days")} ➔ "2"

Comparing Dates and Times¶

VisualMaker allows you to compare dates and times to check specific conditions and see if an event has occurred or if there is still time left for it to happen.

You can compare using:

Textual dates, e.g., 01-03-2024 02:07:48
Functions, e.g., {date_now()}
Variables, e.g., {my_variable}

You can also use comparison operators:

== Equal to
!= Not equal to
> Greater than
< Less than
>= Greater than or equal to
<= Less than or equal to

This is extremely useful for performing comparisons in actions such as the Condition action.

Example 1: Comparing two textual dates¶

{"02-01-2024 01:02:03" > "01-01-2024 01:02:03"}

This checks if the first date is later (greater) than the second. It will return True, since 02-01-2024 01:02:03 is later than 01-01-2024 01:02:03.

Example 2: Comparing using a variable¶

{"02-01-2024 01:02:03" < my_variable}

This compares if the first date is earlier (less) than the date stored in the variable. It will return True or False, depending on the date stored in the variable.

Example 3: Comparing using a function¶

{time_passed("15-01-2025 01:01:01", "hours") > 3}

The time_passed() function with the "hours" parameter is used here to check how many hours have passed since 15-01-2025 01:01:01. It will return a number indicating the hours that have passed.
Then, it checks if that number is greater than 3. If so, it means more than 3 hours have passed, and it will return True. Otherwise, it will return False.

Example 4: Comparing using a function and a variable¶

{time_left(variable_date, "days") == 0}

The time_left() function with the "days" parameter is used to check how many days are left until the date stored in the variable_date variable. It will return a number indicating the remaining days.
It then checks if that number equals 0. If so, it means the date has already arrived, and it will return True. Otherwise, it will return False.

Note

When using time_left(), once the date has passed, it will always return 0 and will NEVER return negative numbers.

Bot's time zone¶

Set your bot's time zone in:

🔑 Manage → ⚙️ Settings → 🕒 Time zone
The date_now_tz() and apply_tz() functions will respect this setting.

Practical example: Claim button with time condition¶

In this example, we will create a button called Claim that:

Increases the user's balance by 1 when pressed every 15 minutes.
Saves the claim date.
If the button is pressed before 15 minutes have passed since the last claim, an error will be triggered.

Prerequisites¶

Premium subscription: These configurations require the use of actions and variables, which are exclusive to the premium subscription in VisualMaker.
Required actions:
- Condition: To evaluate whether 15 minutes have passed.
- Change variable: To save and modify data in variables.
- Send message: To send messages to the user.

Steps to set it up:¶

1. Create the date variable¶

Go to 🔑 Manage → 🗃 Variables → 💠 Create variable 💠
In ➡️ Data type:, select date 📅.
Enter the variable name, e.g., last_claim.
Exit the manage menu by pressing ↙️ Back ↘️, then ⬅️ Exit.

2. Create the `Claim` button¶

Enter the bot editor by pressing 🛠 Edit.
Create a new button by pressing ✳️ New button | command and name it Claim.
Press Actions 🌟 to configure the button's actions.

3. Configure the actions¶

a) Action 1: Condition¶

Press 🎯 New action → 🧭 Condition.
For now, don't do anything here (we'll configure it later).

b) Action 2: Change variable (`balance`)¶

Press 🎯 New action → 🗃 Change variable.
Press Configure 🛠 and set the following:
- Select variable: Enter the name of the variable to modify:
```
balance
```
- Type of modification:
```
🔺 Increment 🔺
```
- Value to save: Specify the value to increment:
```
1
```
Return to the actions menu and activate the action by pressing ✅ Activate.

c) Action 3: Change variable (`last_claim`)¶

Press 🎯 New action → 🗃 Change variable.
Press Configure 🛠 and set the following:
- Select variable: Enter the name of the variable to modify:
```
last_claim
```
- Type of modification:
```
💢 Set 💢
```
- Value to save: Specify the date 15 minutes in the future:
```
{time_add(date_now(), 15, "minutes")}
```
Return to the actions menu and activate the action by pressing ✅ Activate.

d) Action 4: Send message¶

Press 🎯 New action → Send message.

Press Configure 🛠 → 💬 Set message 💬 and enter:

✅ You have claimed 1 coin, you now have {balance} coins.

🕒 Come back in 15 minutes.

Return to the actions menu and activate this action by pressing ✅ Activate.

e) Add a separator¶

Press New separator 📍 to add a separator at the end and create a new block of actions. See what separators are.

f) Action 5: Send message¶

Press 🎯 New action → Send message.
Press Configure 🛠 → 💬 Set message 💬 and enter:
```
❌ It's not time yet, come back in {floor(time_left(last_claim, "minutes"))} minutes and {ceil(time_left(last_claim, "seconds") % 60)} seconds.
```
We've used the floor() and ceil() functions to round the number down and up respectively, and time_left() to determine the remaining time in minutes. You can see all functions here.
Return to the actions menu and activate this action by pressing ✅ Activate.
Copy the ID of this action, you will need it soon.

g) Configure the `Condition` action¶

Return to the Condition action (action 1) and press Configure 🛠.
- New condition:
```
{date_now() > last_claim}
```
- If true: Select continue.
- If false:
  - Press 🆔 Execute action by ID 🆔.
  - In ➡️ After action:, make sure stop is selected.
  - Enter the ID of the Send message action you copied earlier.
Return to the actions menu and activate this action by pressing ✅ Activate.

Final result¶

The user presses the Claim button.
The bot checks if 15 minutes have passed since the last claim:
- If yes:
  1. It increments the user's balance by 1.
  2. Sets a date in the last_claim variable 15 minutes into the future.
  3. Displays a message to the user like:
```
✅ You have claimed 1 coin, you now have 3 coins.

🕒 Come back in 15 minutes.
```
- If no: It displays a message like:
```
❌ It's not time yet, come back in 9 minutes and 32 seconds.
```

The actions are set up like this¶

Date and time example (VisualMaker)

With these tools, you can efficiently manage dates and times in VisualMaker, from simple calculations to advanced settings in your bots.