> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ukrgsm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Кампанії

> Запуск голосового агента на список контактів масово

Кампанія — це спосіб запустити сценарій на багатьох контактах автоматично. Замість запуску дзвінків по одному через API, ви завантажуєте список номерів телефону, а платформа набирає їх сама — з урахуванням розкладу, обмежень паралельності й правил повторних спроб.

## Як працює кампанія

```mermaid theme={null}
flowchart LR
    CSV[CSV контактів] --> Upload[Завантаження на платформу]
    Upload --> Campaign[Створення кампанії]
    Campaign --> Schedule[Розклад і паралельність]
    Schedule --> Calls[Вихідні дзвінки]
    Calls --> Runs[Записи виконання]
    Runs --> Results[Прогрес і звіти]
```

1. **Завантажте CSV з контактами** — обовʼязкова колонка `phone_number`; будь-які додаткові колонки стають `initial_context` для кожного дзвінка
2. **Створіть кампанію** — привʼяжіть до сценарію, задайте паралельність, часові вікна й поведінку повторних спроб
3. **Запустіть** — платформа починає набирати контакти в межах ліміту паралельності
4. **Слідкуйте за прогресом** — кількість оброблених, завершених, невдалих і очікуючих у реальному часі
5. **Призупиняйте й відновлюйте** — зупинити й продовжити в будь-який момент без втрати прогресу

## CSV з контактами

CSV керує кампанією. Кожен рядок — один контакт.

```csv theme={null}
phone_number,customer_name,account_id,plan
380501234567,Олена Іваненко,acc_001,преміум
380671234567,Ігор Петренко,acc_002,базовий
```

Номер телефону приймається як з `+`, так і без нього — головне, щоб залишалось рівно 12 цифр (код країни + номер). Колонки, окрім `phone_number`, автоматично передаються як `initial_context` для кожного дзвінка, стаючи доступними як змінні шаблону в промпті агента — тож кожен дзвінок звучить персоналізовано навіть при масовому запуску.

## Розклад і паралельність

**Паралельність** визначає, скільки дзвінків виконується одночасно. Обмежена вашим тарифом телефонії. На старті варто задавати консервативне значення.

**Часові вікна** обмежують, коли платформі дозволено дзвонити — корисно для дотримання робочих годин чи вимог законодавства:

```json theme={null}
{
  "timezone": "Europe/Kyiv",
  "time_slots": [
    { "day": "monday", "start": "09:00", "end": "17:00" },
    { "day": "tuesday", "start": "09:00", "end": "17:00" }
  ]
}
```

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

## Поведінка повторних спроб

Платформа може автоматично повторно набирати контакти, які не відповіли, були зайняті або потрапили на автовідповідач:

```json theme={null}
{
  "retry_config": {
    "max_attempts": 3,
    "retry_interval_minutes": 60
  }
}
```

## Автоматичне зупинення (circuit breaker)

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

Коли увімкнено, платформа відстежує відсоток невдалих дзвінків у ковзному часовому вікні. Якщо він перевищує поріг, кампанія автоматично призупиняється і потребує ручного відновлення після зʼясування причини.

| Налаштування          | За замовчуванням | Опис                                                                                                                       |
| --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Поріг невдач (%)      | `50`             | Призупинити, коли відсоток невдач у вікні перевищує це значення                                                            |
| Вікно (секунди)       | `120`            | Ковзне часове вікно для розрахунку відсотка невдач                                                                         |
| Мін. дзвінків у вікні | `5`              | Мінімальна кількість дзвінків перед тим, як спрацює автоматичне зупинення — запобігає хибним спрацюванням на малій вибірці |

Кампанія, призупинена через автоматичне зупинення, поводиться так само, як і призупинена вручну — дзвінки в процесі завершуються нормально, і кампанію можна відновити після вирішення проблеми.

## Життєвий цикл кампанії

| Статус      | Значення                                |
| ----------- | --------------------------------------- |
| `draft`     | Створена, але не запущена               |
| `running`   | Активно набирає контакти                |
| `paused`    | Зупинена; відновлюється з місця зупинки |
| `completed` | Усі контакти оброблено                  |
| `failed`    | Сталася критична помилка                |

Кампанію можна призупиняти й відновлювати в будь-який момент. Дзвінки в процесі завершуються нормально до того, як зупинення набуде чинності.