Отложенные действия (ОД)
ОД — Отложенное действие, которое можно запустить после выполнения пользователем любого действия, связанного с ботом.
Назначение
Отложенные действия позволяют выполнить набор реакций через некоторое время после наступления события. Используется для:
- Напоминаний и уведомлений
- Отложенной отправки сообщений
- Автоматических действий через заданный интервал
- Длительных операций (обработка данных, интеграции)
Настройки
| Функция | Описание |
|---|---|
| Название | Техническое название, которое видят только администраторы |
| Режим работы | Отложенные действия могут работать в нескольких режимах |
| Отсрочка | Настройка времени срабатывания ОД |
| Динамическая отсрочка | Время срабатывания строкой, с поддержкой переменных и макросов |
| Данные | Пути к переменным через запятую: их значения сохраняются из контекста перед запуском ОД |
| Сохранять завершенные | Сохранение результатов выполненных работ |
| Удалить | Удаление отложенного действия |
Формат динамической отсрочки
Динамическая отсрочка имеет приоритет над обычной. Её же формат используют until_date у блокировки и ограничения участника и expire_date у пригласительной ссылки.
| Формат | Пример | Результат |
|---|---|---|
| Относительный срок | 1h, 30m, 7d |
Через указанное время |
| Комбинированный | 1d2h30m15s |
Через день, 2 часа, 30 минут и 15 секунд |
| Полная дата и время | 12.05.2025 15:30 |
В указанный момент |
| Дата без года | 12.05 15:30 |
Ближайшее 12 мая |
| Только время | 15:30 |
Сегодня в 15:30, а если время уже прошло — завтра |
| Особые значения | завтра 08:00, выходной 10:00, будний 09:00 |
В указанный момент |
| День недели | понедельник 09:30, пн 09:30 |
Ближайший такой день |
| Unix-время | 1748880000 |
Конкретный момент, в секундах |
Единицы относительного срока: s — секунды, m — минуты, h — часы, d — дни. Можно и кириллицей: с, м, ч, д — например 1ч30м.
⚠️ Важно: Время срабатывания должно быть в будущем. Отсрочка, указывающая в прошлое, не запустится — отложенное действие завершится ошибкой, которая видна в логах бота.
Передача данных в отложенное действие
При запуске отложенного действия через реакцию StartTask вы можете передать данные в параметре «Данные». Эти данные будут доступны внутри отложенного действия через переменную ${task.data}.
Формат данных
Параметр «Данные» принимает не сами данные, а пути к переменным — через запятую. Значение по каждому пути копируется в отложенное действие и становится доступно под последним именем из пути.
var.local.user_id, var.local.message, chat.id
| Путь | Как обратиться внутри ОД |
|---|---|
var.local.user_id |
${task.data.user_id} |
var.local.message |
${task.data.message} |
chat.id |
${task.data.id} |
⚠️ Важно: Имя берётся из последнего сегмента пути, поэтому два пути с одинаковым окончанием (
var.local.idиchat.id) перезапишут друг друга. Давайте таким переменным разные имена.
💡 Совет: Пути поддерживают подстановку переменных и макросов — см. Путь из переменной. Если путь после подстановки окажется неправильным, реакция завершится ошибкой. Путь, по которому просто нет данных, ошибкой не считается — он молча пропускается.
Пример передачи данных
Реакция StartTask:
| Параметр | Значение |
|---|---|
| Отложенное действие | send_reminder |
| Данные | var.local.user_id, var.local.message |
Внутри отложенного действия send_reminder:
| Переменная | Значение |
|---|---|
${task.data.user_id} |
ID пользователя |
${task.data.message} |
Текст напоминания |
Пример реакции внутри ОД:
SendMessage →
chat_id: ${task.data.user_id}
Текст: ${task.data.message}
Использование переменных в данных
Подставлять переменные и макросы можно внутри самих путей — так путь собирается во время выполнения:
var.local.items[${loop.i}], var.local.profile.${var.local.field}
💡 Совет: Если нужно передать не готовое значение из контекста, а собранный текст или объект, сложите его заранее реакцией
SetVarLocal, а в «Данные» укажите путь к этой локальной переменной.
Режим работы
| Режим | Описание |
|---|---|
| Режим по умолчанию | запускает ОД, при попытке повторного запуска ОД ничего не произойдет |
| Режим замены | запускает ОД, при повторном запуске перезапускает работающее ОД |
| Режим добавления | запускает ОД, при повторном запуске создает еще одно ОД, не отменяя ранее запущенные |
Триггер
Главный раздел, здесь необходимо указывать все реакции, которые должно выполнить ОД.
Подробнее о реакциях можно узнать в разделе Реакции.
⚠️ Частые ошибки и их решение
Ошибка 1: Данные не передаются
Причина: В параметре «Данные» указаны не пути к переменным, а сами значения или JSON.
Решение: Перечислите пути через запятую. Если нужен собранный объект, сначала положите его в локальную переменную реакцией SetVarLocal, а сюда впишите путь к ней.
❌ Неправильно:
{"user_id": ${user.id}, "message": "текст"}
✅ Правильно:
user.id, var.local.message
Вторая причина: по указанному пути на момент запуска нет данных — тогда значение просто не передаётся, без ошибки. Проверьте, что переменная установлена до реакции StartTask.
Ошибка 2: Отложенное действие не срабатывает
Причина: Неверно указано время отсрочки.
Решение: Проверьте формат времени в настройках ОД. Используйте макрос !{time} для динамической отсрочки.
Ошибка 3: ОД срабатывает несколько раз
Причина: Неправильно выбран режим работы.
Решение:
- Для однократного выполнения используйте «Режим по умолчанию»
- Для обновления времени используйте «Режим замены»
Ошибка 4: Данные потеряны при перезапуске ОД
Причина: В режиме замены данные обновляются при каждом запуске.
Решение: Убедитесь, что в режиме замены данные передаются корректно при каждом вызове StartTask.
🔗 Связанные разделы
- StartTask — запуск отложенного действия
- StopTask — остановка отложенного действия
- Макрос time — для динамической отсрочки