# Робота з датами та часом

{% hint style="info" %}
MaviBot працює з такими форматами ДАТИ та ЧАСУ:

для дат – **"dd.mm.yyyy"**
\
для часу – **"HH:MM"**
{% endhint %}

### Змінні

Для роботи з датами та часом ви можете використовувати такі змінні:

**current\_date** - поточна дата у форматі dd.mm.yyyy, залежно від часового поясу проєкту\
**next\_day** - завтрашня дата у форматі dd.mm.yyyy; корисно для планування повідомлень\
**current\_time** - поточний час у форматі hh:mm, залежно від часового поясу проєкту\
**weekday** - день тижня як число: понеділок = 1, вівторок = 2 тощо.

**Швидкий доступ до описів функцій:**

* [Додати час до часу](#how-to-add-time-to-time) 
* [Порівняти час](#how-to-compare-time) 
* [Встановити часові інтервали](#how-to-set-time-intervals) 
* [Обчислити час до дня D ](#how-to-find-out-how-much-time-is-left-until-day-d)
* [Знайти наступний день народження](#how-to-find-out-the-next-birthday) 
* [Отримати дату певного дня тижня ](#how-to-get-the-date-of-a-specific-weekday)
* [Отримати дату певного дня місяця](#how-to-get-the-date-of-a-specific-day-of-month) 
* [Перевірити, чи в межах робочого часу](#how-to-check-if-the-current-time-is-within-working-hours)

### Як додати час до часу 

{% hint style="info" %}
Ви можете порівнювати дати та час за допомогою логічних операторів так само, як числа.
{% endhint %}

**addYear() | addMonth() | addDays() | addMinutes()**

<details>

<summary>Опис</summary>

**addYear(date, years\_to\_add) -** обчислює нову дату, додаючи до заданої дати вказану кількість років, з урахуванням високосних років. Використовуйте від’ємне число, щоб відняти роки.

**addMonth(date, months\_to\_add)** - обчислює нову дату, додаючи до заданої дати вказану кількість місяців, з урахуванням високосних років. Використовуйте від’ємне число, щоб відняти місяці.

**addDays(date, days\_to\_add) -** додає до дати вказану кількість днів. Використовуйте від’ємне число, щоб відняти дні. Приклад: `addDays(current_date, 20)` або `addDays('20.08.2019', -99)`

**addMinutes(time, minutes\_to\_add) -** додає до часу вказану кількість хвилин. Використовуйте від’ємне число, щоб відняти хвилини. Приклад: `addMinutes(current_time, 20)` або `addMinutes('20:08', -30)`

**'date' + days** - додає до дати вказану кількість днів

**'time' + minutes** - додає до часу вказану кількість хвилин

</details>

<details>

<summary>Приклади</summary>

Приклад додавання певної кількості років до дати:

<div data-with-frame="true"><figure><img src="/files/f6e93d3b45bc550900092522ac1f7ad81a97e1c6" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/f7bcf3ced18b612e3d429e1619476a8454a82a90" alt="" width="375"><figcaption></figcaption></figure></div>

Приклад додавання певної кількості місяців до дати:

<div data-with-frame="true"><figure><img src="/files/226b5e5019419c5f293fd73cd602227613881034" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/da6a914bf8db53a044e9b7eaafd335415561224e" alt="" width="375"><figcaption></figcaption></figure></div>

Приклад використання простої математичної операції — додавання днів до дати та хвилин до часу:

<div data-with-frame="true"><figure><img src="/files/d0c3f6e40ef979cc32140775905544531bfb3b1a" alt="" width="375"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/f9552ba5834cc77058f228b929d00e1cee28eef2" alt="" width="375"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Приклад коду для копіювання</summary>

`count = 2`\
`date = '29.02.2020'`\
`x = addYear(date, count)`\
`y = addYear('31.12.2021', -1*count)`

`count = 10`\
`date = '30.04.2019'`\
`x = addMonth(date, count)`\
`y = addMonth('31.12.2020', -1*count)`

`count = 10`\
`date = '30.04.2019'`\
`x = addMonth(date, count)`\
`y = addMonth('31.12.2020', -1*count)`

</details>

### Як порівнювати час&#x20;

<details>

<summary>Опис</summary>

Ви можете порівнювати дати та час за допомогою логічних операторів так само, як числа:
\
більше ніж > , менше ніж <
\
дорівнює == , не дорівнює !=
\
більше або дорівнює >= , менше або дорівнює <=

Умови порівняння також можна поєднувати за допомогою логічних операторів AND та OR.

{% hint style="warning" %}
**Умови порівняння мають бути логічно узгодженими**, тобто не можна створювати умови на кшталт a == 1 і a != 1, оскільки значення не може одночасно бути і рівним, і не рівним 1.
{% endhint %}

Умови порівняння вводяться в **) для збереження відповіді клієнта.** .

<div data-with-frame="true"><figure><img src="/files/276d237b3813e3b3f83bef797ef1129b508f5be1" alt="" width="563"><figcaption></figcaption></figure></div>

Обов’язково використовуйте затримки, коли вказуєте умови порівняння в стрілці.

<div data-with-frame="true"><figure><img src="/files/2f77897ad8fcac5f6efdff04203e0bbed4b98317" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Приклад</summary>

`'01.09.2020'`` `*`< '11.10.2020'`*&#x20;

*`'11.10.2020' >=`*` ``current_date`

`current_date == date`

`current_time >= '18:00'`&#x20;

`current_time <= '21:00'`

</details>

### &#x20;Як встановити часові інтервали

<details>

<summary>Опис</summary>

Дуже корисною функцією для роботи з часовими інтервалами є:

**time\_interval('start\_time', 'end\_time')**

Функція повертає логічне **True** або **False**.

Використовуйте цю функцію в блоках як умову в **"Variable to compare"** полі або в калькуляторі, використовуючи IF().

{% hint style="info" %}
Функція дає змогу перевірити, чи **поточний час** потрапляє в заданий інтервал.
{% endhint %}

</details>

<details>

<summary>Приклад</summary>

`time_interval('10:00','19:00') - перевіряє часовий інтервал з 10:00 до 19:00`

`time_interval('19:00','07:00') - перевіряє часовий інтервал з 19:00 до 07:00`

`time_interval('18.10.2021 10:00','25.10.2021 23:59:59') - перевіряє часовий інтервал між різними датами`

`time_interval('#{current_date} 10:00','#{date} 19:00') - перевіряє часовий інтервал, заданий за допомогою змінних`

Давайте детальніше розглянемо перший приклад. Функція читається так:

Якщо користувач надсилає повідомлення, що містить слово "time", у період з 10:00 до 19:00, умова повертає true; інакше — false.

Це дає змогу створювати різні відповіді залежно від часу звернення клієнта.
\
Наприклад, якщо поточний час між 10:00 і 19:00, клієнт отримає:
&#x20;***"Менеджер відповість вам найближчим часом."***

У будь-який інший час він отримає:
&#x20;***"Менеджер наразі недоступний; ви отримаєте відповідь у робочий час з 10:00."***

У полі Калькулятор введіть:

`response = if(time_interval('10:00','19:00'), "Менеджер відповість вам найближчим часом", "Менеджер наразі недоступний; ви отримаєте відповідь у робочий час з 10:00")`

У полі "Message" введіть: `#{response}`

<div data-with-frame="true"><figure><img src="/files/96a96b341c157990a365621742012aeb04a0f148" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/5dc4fa6d245eb6b461d6427a506ff9aa5c9d45cd" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Приклад коду для копіювання</summary>

`response = if(time_interval('10:00','19:00'), "Менеджер відповість вам найближчим часом", "Менеджер наразі недоступний; ви отримаєте відповідь у робочий час з 10:00")`

</details>

### Як дізнатися, скільки часу залишилося до дня D

<details>

<summary>Приклад</summary>

<div data-with-frame="true"><figure><img src="/files/7cafe020d2967913efe367a6d00afa33d3012adb" alt="" width="563"><figcaption></figcaption></figure></div>

Щоб обчислити, скільки часу залишилося до дня D:

Визначте дату й час цільового моменту, до якого ви хочете відраховувати час.

`date_D = 10.10.2021 time_D = 12:00`

Перетворіть це у **timestamp** формат:

`timestampD = convert_datetime("#{date_D} #{time_D}", "%d.%m.%Y %H:%M", "%s")`

Збережіть поточний час у **timestamp** формат:

`timestamp0 = #{timestamp}`

Округліть отримані значення до цілих чисел:&#x20;

`timeD = int(#{timestampD}) time0 = int(#{timestamp0})`

Обчисліть різницю в секундах:

`time = timeD - time0`

Поділіть на кількість секунд у добі та округліть результат:

`full_days = time/86400`&#x20;

`days = int(#{full_days})`

Обчисліть, скільки секунд залишилося від неповного дня:

`c = days*86400`&#x20;

`d = time - c`

Обчисліть, скільки годин це становить, і округліть значення:

`e = d/3600 hours = int(e)`

Обчисліть, скільки секунд залишилося від неповних годин:

`g = hours*3600`&#x20;

`h = d - g`

Перетворіть це на хвилини та округліть значення:&#x20;

`i = h/60`&#x20;

`minutes = int(i)`

Обчисліть, скільки секунд залишилося:

`k = minutes*60`&#x20;

`seconds = h - k`

І виведіть час у **«Текст повідомлення»** :

Час до початку: #{days} днів #{hours} годин #{minutes} хвилин і #{seconds} секунд

Ось код для вставки в **"Калькулятор"** :

```
timestampD = convert_datetime("#{date_D} #{time_D}", "%d.%m.%Y %H:%M", "%s")
timestamp0 = #{timestamp}
timeD = int(#{timestampD})
time0 = int(#{timestamp0})
time = timeD - time0
full_days = time/86400
days = int(#{days})
c = days*86400
d = time - c
e = d/3600
hours = int(e)
g = hours*3600 
h = d - g
i = h/60 
minutes = int(i)
k = minutes*60 
seconds = h - k
```

<figure><img src="/files/0d4e55a2277a9ae60890c5033ba2b4778ca0dcf3" alt="" width="563"><figcaption></figcaption></figure>

Поле **Калькуляторі** також підтримує віднімання дат і часу без перетворення типу. Наприклад:

`'11.12.2021' - '8.12.2021'  повертає 3 (дні)`

`'11:12' - '3:45'  повертає 447 (хвилин)`

</details>

### Як дізнатися наступний день народження &#x20;

<details>

<summary>Опис</summary>

Щоб бот надсилав привітання з днем народження, ви можете використати функцію:

**birthdate(date)** - повертає наступний найближчий день народження на основі дати народження людини: `reminder = birthdate('28.04.1994')`&#x20;

</details>

### Як отримати дату певного дня тижня

<details>

<summary>Опис</summary>

Якщо у вас є повторювані розсилки в певні дні тижня, ви можете отримати дату дня тижня, щоб запланувати розсилку.

**weekday\_date(weekday, b)** - повертає дату найближчого вказаного дня тижня. Вона приймає **два параметри**:

**Перший параметр — це** номер дня тижня, який потрібно знайти (від 1 до 7, де 1 = понеділок, 7 = неділя).

**Другий параметр** визначає, чи **повертати сьогоднішню дату, якщо вказаний день тижня — сьогодні**. Цей параметр необов’язковий і за замовчуванням має значення False.

Розгляньмо приклад, щоб зрозуміти, як працює другий параметр:

Ви хочете запланувати повідомлення на четвер.

Але що, якщо клієнт щойно зареєструвався в четвер?

Чи слід надсилати повідомлення цього четверга чи наступного?

Другий параметр, встановлений у False, означає, що повідомлення буде надіслано лише наступного четверга (сьогодні пропускається).

Другий параметр, встановлений у True, означає, що повідомлення буде надіслано цього четверга, якщо сьогодні четвер (включно з днем реєстрації).

У нашому прикладі користувач реєструється в четвер, 13.02.2025, і ми хочемо надіслати повідомлення наступного четверга.
&#x20;Отже, повернене значення буде "20.02.2025".

Наприклад, `weekday_date(4)` поверне '20.02.2025'.

Якщо ви хочете, щоб поточний день враховувався лише до певного часу, можна використати таку конструкцію:

`weekday_date(4, current_time < '13:00')`, де умову можна замінити на будь-яку потрібну вам умову.

<mark style="color:green;">**Ось приклад використання функції:**</mark>

Приклад використання функції в полі "Send date" у зв’язці

<div data-with-frame="true"><figure><img src="/files/89370143c9023d159740ab5dd4745f7b35d9ef61" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

### Як отримати дату певного дня місяця

<details>

<summary>Опис</summary>

Якщо у вас є повторювані дії в певний день місяця, ви можете отримати дату найближчого настання цього дня, щоб запланувати розсилку.

**month\_date(date, b)** - повертає найближчу дату місяця для вказаного номера дня. Вона приймає **два параметри**:

**date** - номер дня місяця, який потрібно знайти (від 1 до 31)

**b** - необов’язковий параметр; визначає, чи повертати сьогоднішню дату, якщо вона збігається з указаним днем. За замовчуванням має значення False.

Якщо ви передасте 31, але в поточному місяці лише 30 днів, функція поверне останній день місяця (наприклад, 30-те).

Наприклад:

Якщо сьогодні 05.04.2022 і ви викликаєте t = month\_date(1), результатом буде 01.05.2022 - найближче 1-ше число місяця після сьогодні.

</details>

### Як перевірити, чи поточний час у межах робочого часу

<details>

<summary>Опис</summary>

Наприклад, компанія працює з 9:00 до 18:00 і не працює в суботу та неділю. Давайте побудуємо перевірки крок за кроком:

1. Перевірте, чи час у межах робочого часу: current\_time >= '9:00' **AND** current\_time <= '18:00'&#x20;
2. Перевірте, чи час поза межами робочого часу: current\_time < '9:00' **OR** current\_time > '18:00'
3. Перевірте, чи сьогодні робочий день (не субота і не неділя): weekday != 6 AND weekday != 7
4. Об’єднайте умови для написання в робочий час: current\_time >= '9:00' **AND** current\_time <= '18:00' **AND** weekday != 6 **AND** weekday != 7
5. Об’єднайте умови для написання поза робочим часом: current\_time < '9:00' **OR** current\_time > '18:00' **OR** weekday == 6 **OR** weekday == 7

</details>

<details>

<summary>Приклад</summary>

<div data-with-frame="true"><figure><img src="/files/ddc9b1516e4359a3dc47feaf264959ad8a4c1cb2" alt=""><figcaption></figcaption></figure></div>

</details>

### Як конвертувати дату і час

<details>

<summary>Приклад</summary>

Формат дата-часу, що використовується, відрізняється в різних системах, і можливо, що один із інтегрованих ресурсів поверне час у форматі, який MaviBot не розпізнає. Вам потрібно буде його конвертувати.&#x20;

**convert\_datetime(date, fin, f\_out) -** конвертує дату й час

Є три параметри:

* Вхідний рядок дати
* Рядок формату введення
* Рядок формату виведення

Приклад: \
`convert_datetime("2011-11-03", "%Y-%m-%d", "%Y/%m/%d") на виході буде 2011/11/03`

Ця функція перетворює вхідну дату у **timestamp**.

\#{current\_date} #{current\_time} - перетворює у "06.01.2025 11:45" — оскільки немає інформації про секунди або мікросекунди, отриманий timestamp має нулі після десяткової крапки.

Наприклад: 1736144700.000000

Якщо ви вкажете мілісекунди після десяткової крапки,

`convert_datetime("06.01.2025 19:26:35.123456", "%d.%m.%Y %H:%M:%S.%f", "%s.%f")`

результат буде таким: `1736166395.123456`

**get\_datetime(format)** - функція для отримання поточного часу в певному форматі.
\
Функція приймає один параметр — рядок, який вказує потрібний формат виведення.

{% hint style="info" %} <mark style="color:$primary;">Важливо!</mark> Відповіддю функції буде (Monday, Tuesday тощо).\
\
Приклад: <mark style="color:orange;">get\_datetime("%A") на виході буде Wednesday</mark>
{% endhint %}

Опис параметрів рядка формату, які вказуються у функції як рядки в лапках:

<table data-header-hidden><thead><tr><th width="177.33333333333331">Директива</th><th>Значення</th><th>Приклад</th></tr></thead><tbody><tr><td><code>%a</code></td><td>Коротка назва дня тижня</td><td>Sun, Mon ...</td></tr><tr><td><code>%A</code></td><td>Повна назва дня тижня</td><td>Monday, Tuesday, …, Sunday </td></tr><tr><td><code>%w</code></td><td>День тижня як десяткове число, де 0 — неділя, а 6 — субота</td><td>0, 1, …, 6</td></tr><tr><td><code>%d</code></td><td>День місяця як десяткове число з доповненням нулями зліва</td><td>01, 02, …, 31</td></tr><tr><td><code>%b</code></td><td>Коротка назва місяця</td><td>Jan, Feb, …, Dec</td></tr><tr><td><code>%B</code></td><td>Повна назва місяця</td><td>January, February, March тощо.</td></tr><tr><td><code>%m</code></td><td>Місяць як десяткове число з доповненням нулями зліва</td><td>01, 02, …, 12</td></tr><tr><td><code>%y</code></td><td>Рік як двозначне число</td><td>00, 01, …, 99</td></tr><tr><td><code>%Y</code></td><td>Рік як чотиризначне число</td><td>0001, 0002, …, 2013, 2014, …, 9998, 9999</td></tr><tr><td><code>%H</code></td><td>Година (24-годинний формат) як двозначне число з доповненням нулями зліва</td><td>00, 01, …, 23</td></tr><tr><td><code>%I</code></td><td>Година (12-годинний формат) як двозначне число з доповненням нулями зліва</td><td>01, 02, …, 12</td></tr><tr><td><code>%p</code></td><td>Позначення AM або PM</td><td>AM, PM (en_US);am, pm (de_DE)</td></tr><tr><td><code>%M</code></td><td>Хвилини як двозначне число з доповненням нулями зліва</td><td>00, 01, …, 59</td></tr><tr><td><code>%S</code></td><td>Секунди як двозначне число з доповненням нулями зліва</td><td>00, 01, …, 59</td></tr><tr><td><code>%f</code></td><td>Мікросекунди як шестизначне число з доповненням нулями зліва</td><td>000000, 000001, …, 999999</td></tr><tr><td><code>%z</code></td><td>Зсув UTC у форматі <code>±HHMM[SS[.ffffff]]</code> (порожній рядок, якщо об’єкт naive).</td><td>(порожньо), +0000, -0400, +1030, +063415, -030712.345216</td></tr><tr><td><code>%Z</code></td><td>Назва часового поясу (порожній рядок, якщо об’єкт naive).</td><td>(порожньо), UTC, GMT</td></tr><tr><td><code>%j</code></td><td>День року як трицифрове число з доповненням нулями зліва</td><td>001, 002, …, 366</td></tr><tr><td><code>%U</code></td><td>Номер тижня року (де неділя є першим днем тижня) як десяткове число з доповненням нулями зліва. Усі дні нового року до першої неділі вважаються нульовим тижнем.</td><td>00, 01, …, 53</td></tr><tr><td><code>%W</code></td><td>Номер тижня року (де понеділок є першим днем тижня) як десяткове число. Усі дні нового року до першого понеділка вважаються нульовим тижнем.</td><td>00, 01, …, 53</td></tr><tr><td><code>%%</code></td><td>Символ <code>'%'</code></td><td>%</td></tr><tr><td><code>%s</code></td><td>timestamp</td><td>1607926200</td></tr></tbody></table>

Усі інші символи відображаються як є.

{% hint style="info" %}
Ви можете отримати поточний timestamp за допомогою: **convert\_datetime("#{current\_date} #{current\_time}", "%d.%m.%Y %H:%M", "%s")**
{% endhint %}

</details>

### Показати поточну дату у форматі "дд назва місяця"

<details>

<summary>Приклад</summary>

Щоб відобразити дату у форматі "дд назва місяця", використовуйте функцію ***current\_date\_eng()***.&#x20;

*Якщо вам потрібно додати до цієї дати певну кількість днів, слід вказати потрібну кількість днів як параметр у функції.*

Наприклад, якщо сьогодні 3 квітня, тоді функція поверне:

current\_date\_eng() - 3 квітня

current\_date\_eng(2) - 5 квітня

current\_date\_eng(-2) - 1 квітня

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/doc/uk/chatbot/functions/kalkulyator/date.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.