# About Using autobroadcast__create Action in Scenarios

Action `autobroadcast__create` allows creating scheduled message broadcasts in bot scenarios. This allows sending messages to users with delay or on schedule, for example, after a client performs a certain action or for regular broadcasts.

---

## Context and Problem

In many scenarios, you need to send messages to users not immediately, but after a certain time or on schedule. For example:
- Reminder to user to continue dialog after a few days
- Regular news or update broadcasts
- Deferred messages after performing certain actions

Action `autobroadcast__create` solves this task by allowing creating scheduled broadcasts directly in the bot scenario.

---

## Key Concepts

### What is autobroadcast

Autobroadcast is a scheduled message broadcast to a user, which can be:
- **One-time** — sent once at the specified time
- **Recurring** — sent regularly on schedule (daily, weekly, etc.)

### Configuration Parameters

Action `autobroadcast__create` accepts the following parameters:

- `template_id` or `alias` — one of them is required: broadcast template ID or alias name for transition
- `one_time` — whether the broadcast is one-time (supports placeholders)
- `send_after` — time in natural language format ("2 days", "1 week", etc.)
- `weekday`, `monthday`, `daytime` — parameters for recurring broadcasts (used if `send_after` is not specified)

### Natural Language Parsing

The `send_after` parameter supports natural language parsing, allowing specifying time in a convenient format:
- `"2 days"` — in 2 days
- `"3d"` — in 3 days
- `"after 1 week"` — in 1 week
- `"1 month"` — in 1 month
- `"5 hours"` — in 5 hours
- `"7"` — in 7 days (number is interpreted as number of days)

---

## Approach Options

### One-Time Broadcast vs Recurring

**One-time broadcast (`one_time: true`):**
- ✅ Pros: Simple setup, suitable for reminders and one-time messages
- ❌ Cons: Need to create new broadcast for each case

**Recurring broadcast (`one_time: false` or without parameter):**
- ✅ Pros: Automatic repetition, suitable for regular broadcasts
- ❌ Cons: Need to configure schedule, can accumulate many active broadcasts

### Using template_id vs alias

**Template ID:**
- Used for sending ready broadcast template
- Suitable when you need to send a standard message

**Alias:**
- Used for transitioning user to a specific alias in the scenario
- Suitable when you need to launch part of the scenario from a specific point

---

## Adopted Solutions

### Required Choice Between template_id and alias

The system requires specifying either `template_id` or `alias`, but not both simultaneously. This ensures configuration clarity and avoids conflicts.

### Placeholder Support

Parameters `one_time`, `weekday`, `monthday`, `daytime` support placeholders, allowing dynamically setting broadcast time based on user data or context.

### Canceling Broadcasts

To cancel a scheduled broadcast, action `autobroadcast__remove` is used, which accepts `template_id` or `alias` to identify the broadcast.

---

## Implications for Users and Implementation

### For Integrators

When using `autobroadcast__create` in scenarios, it's important to:

1. **Determine broadcast type** — one-time or recurring
2. **Choose between template_id and alias** — depending on scenario needs
3. **Configure send time** — use natural language for convenience
4. **Handle case of no free operators** — add `limit` event to handle situations when broadcast cannot be executed

### Common Errors

**Error:** Both parameters `template_id` and `alias` are specified simultaneously  
**Problem:** System does not know what exactly to send  
**Solution:** Use only one of the parameters

**Error:** No parameter specified (`template_id` or `alias`)  
**Problem:** System does not know what to send  
**Solution:** Must specify one of the parameters

**Error:** Using recurring broadcast without schedule configuration  
**Problem:** Broadcast may not work correctly  
**Solution:** Specify `weekday`/`monthday`/`daytime` or `send_after` with `one_time: false`

### Limitations

- One user can have a limited number of active autobroadcasts (depends on system settings)
- Autobroadcast executes only for active users (who have not deleted the bot)
- Send time is calculated based on server time

---

## Usage Examples

### Subscription to Regular Broadcast

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

This will create a broadcast that sends daily at 09:00.

### User Reminder

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

Reminder to user to continue dialog in 2 days.

### Using Broadcast Template

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

Will send broadcast template with ID 42 in one week, one-time.

---

## Related Documents

- **How-to:** [Configure Automatic Broadcast](/en/broadcast/how-to/configure-autobroadcast.md) — configuration through Broadcast module UI
- **How-to:** [Create Broadcast Template](/en/broadcast/how-to/create-broadcast-template.md) — creating templates for use with `template_id`