# Про використання 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 виконується тільки для активних користувачів (які не видалили бота)
- Час відправлення обчислюється на основі серверного часу

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

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

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

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

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

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

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

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

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

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

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

- **How-to:** [Налаштування автоматичної розсилки](/uk/broadcast/how-to/configure-autobroadcast.md) — налаштування через UI модуля Broadcast
- **How-to:** [Створити шаблон розсилки](/uk/broadcast/how-to/create-broadcast-template.md) — створення шаблонів для використання з `template_id`