Про використання action autobroadcast__create у сценаріях

Action autobroadcast__create дозволяє створювати заплановані розсилки повідомлень у сценаріях ботів. Це дозволяє надсилати повідомлення користувачам з затримкою або за розкладом, наприклад, після того як клієнт виконав певну дію або для регулярних розсилок.

Контекст і проблема

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

• Нагадування користувачу продовжити діалог через кілька днів
• Регулярні розсилки новин або оновлень
• Відкладені повідомлення після виконання певних дій

Action autobroadcast__create вирішує цю задачу, дозволяючи створювати заплановані розсилки безпосередньо в сценарії бота.

Основні концепції

Що таке autobroadcast

Autobroadcast — це запланована розсилка повідомлення користувачу, яка може бути:

• Одноразовою — надсилається один раз у вказаний час
• Повторюваною — надсилається регулярно за розкладом (щодня, щотижня тощо)

Параметри конфігурації

Action autobroadcast__create приймає наступні параметри:

• template_id або alias — обов'язково один з них: ID шаблону розсилки або назва alias для переходу
• one_time — чи є розсилка одноразовою (підтримує плейсхолдери)
• send_after — час у natural language форматі ("2 days", "1 week" тощо)
• weekday, monthday, daytime — параметри для регулярних розсилок (використовуються, якщо send_after не заданий)

Natural language parsing

Параметр send_after підтримує natural language parsing, що дозволяє вказувати час у зручному форматі:

• "2 days" — через 2 дні
• "3d" — через 3 дні
• "after 1 week" — через 1 тиждень
• "1 month" — через 1 місяць
• "5 hours" — через 5 годин
• "7" — через 7 днів (число інтерпретується як кількість днів)

Варіанти підходів

Одноразова розсилка vs регулярна

Одноразова розсилка (one_time: true):

• ✅ Плюси: Простота налаштування, підходить для нагадувань та одноразових повідомлень
• ❌ Мінуси: Потрібно створювати нову розсилку для кожного випадку

Регулярна розсилка (one_time: false або без параметра):

• ✅ Плюси: Автоматичне повторення, підходить для регулярних розсилок
• ❌ Мінуси: Потрібно налаштувати розклад, може накопичуватися багато активних розсилок

Використання template_id vs alias

Template ID:

• Використовується для надсилання готового шаблону розсилки
• Підходить, коли потрібно надіслати стандартне повідомлення

Alias:

• Використовується для переходу користувача на певний alias у сценарії
• Підходить, коли потрібно запустити частину сценарію з певної точки

Прийняті рішення

Обов'язковий вибір між template_id та alias

Система вимагає вказати або template_id, або alias, але не обидва одночасно. Це забезпечує чіткість конфігурації та уникнення конфліктів.

Підтримка плейсхолдерів

Параметри one_time, weekday, monthday, daytime підтримують плейсхолдери, що дозволяє динамічно встановлювати час розсилки на основі даних користувача або контексту.

Відміна розсилок

Для відміни запланованої розсилки використовується action autobroadcast__remove, який приймає template_id або alias для ідентифікації розсилки.

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

Для інтеграторів

При використанні autobroadcast__create в сценаріях важливо:

1. Визначити тип розсилки — одноразова чи регулярна
2. Вибрати між template_id та alias — залежно від потреб сценарію
3. Налаштувати час відправлення — використовувати natural language для зручності
4. Обробити випадок відсутності вільних операторів — додати подію limit для обробки ситуацій, коли розсилка не може бути виконана

Типові помилки

Помилка: Вказано обидва параметри template_id та alias одночасно
Проблема: Система не знає, що саме потрібно надіслати
Рішення: Використовувати тільки один з параметрів

Помилка: Не вказано жодного параметра (template_id або alias)
Проблема: Система не знає, що надсилати
Рішення: Обов'язково вказати один з параметрів

Помилка: Використання регулярної розсилки без налаштування розкладу
Проблема: Розсилка може не працювати коректно
Рішення: Вказати weekday/monthday/daytime або send_after з one_time: false

Обмеження

• Один користувач може мати обмежену кількість активних autobroadcast (залежить від налаштувань системи)
• Autobroadcast виконується тільки для активних користувачів (які не видалили бота)
• Час відправлення обчислюється на основі серверного часу

Приклади використання

Підписка на регулярну розсилку

{
  "alias": "daily_news",
  "weekday": "1",
  "daytime": "09:00",
  "one_time": false
}

Це створить розсилку, яка буде відправлятися щодня о 09:00.

Нагадування користувачу

{
  "alias": "reminder_continue",
  "send_after": "2 days",
  "one_time": true
}

Нагадування користувачу продовжити діалог через 2 дні.

Використання шаблону розсилки

{
  "template_id": 42,
  "send_after": "1 week",
  "one_time": true
}

Відправить шаблон розсилки з ID 42 через тиждень одноразово.

Пов'язані документи

• How-to: Налаштування автоматичної розсилки — налаштування через UI модуля Broadcast
• How-to: Створити шаблон розсилки — створення шаблонів для використання з template_id