Кампании

Кампания — это способ автоматически запускать воркфлоу для множества контактов. Вместо того чтобы запускать звонки по одному через API, вы загружаете список номеров, а Агентика обзванивает их с учетом окон расписания, лимитов параллелизма и правил повтора.

Как работает кампания

Загрузите CSV с контактами — в нем должен быть столбец phone_number; все дополнительные столбцы станут initial_context для каждого звонка
Создайте кампанию — привяжите ее к воркфлоу, задайте параллелизм, окна расписания и поведение повторов
Запустите ее — Агентика начнет обзванивать контакты в пределах вашего лимита параллелизма
Следите за прогрессом — отслеживайте число обработанных, завершенных, неудачных и ожидающих контактов в реальном времени
Ставьте на паузу и возобновляйте — можно остановить и перезапустить кампанию в любой момент без потери прогресса

CSV с контактами

CSV управляет кампанией. Каждая строка — один контакт.

phone_number,customer_name,account_id,plan
+14155550100,Jane Smith,acc_001,premium
+14155550101,Bob Jones,acc_002,basic

Столбцы кроме phone_number автоматически передаются как initial_context в каждый звонок и становятся доступны как переменные шаблона в промпте агента. Так каждый звонок может быть персонализированным даже в масштабе.

Расписание и параллелизм

Параллелизм управляет числом одновременных звонков. Он ограничен вашим тарифом телефонии. Начинайте с консервативного значения. Окна расписания ограничивают, когда Агентика может звонить. Это полезно для соблюдения рабочих часов или регуляторных требований:

{
  "timezone": "America/New_York",
  "time_slots": [
    { "day": "monday", "start": "09:00", "end": "17:00" },
    { "day": "tuesday", "start": "09:00", "end": "17:00" }
  ]
}

Если окна расписания не заданы, Агентика звонит непрерывно после запуска кампании.

Поведение повторов

Агентика может автоматически повторять попытки для контактов, которые не ответили или были заняты. Вы задаёте число повторов, паузу между ними и то, какие исходы вообще стоит повторять:

{
  "retry_config": {
    "enabled": true,
    "max_retries": 2,
    "retry_delay_seconds": 120,
    "retry_on_busy": true,
    "retry_on_no_answer": true
  }
}

max_retries принимает значения 0–10, retry_delay_seconds — 30–3600. Флаг retry_on_voicemail пока ни на что не влияет: повторяются только исходы «занято» и «без ответа» — распознавание автоответчика ещё не передаёт свой исход в телефонные статусы.

Защита от сбоев (circuit breaker)

Защита от сбоев автоматически ставит кампанию на паузу, когда доля неудачных звонков становится слишком высокой. Это защищает от лишних расходов и проблем с репутацией телефонии из-за неправильно настроенного агента или плохого списка контактов. Когда она включена, Агентика отслеживает долю неудач в скользящем временном окне. Если показатель превышает порог, кампания автоматически ставится на паузу; возобновить ее нужно вручную после расследования проблемы.

Настройка	По умолчанию	Описание
Порог сбоев (%)	`50`	Поставить на паузу, когда доля неудач в окне превышает этот процент
Окно (секунды)	`120`	Скользящее временное окно, по которому считается доля неудач
Мин. звонков в окне	`5`	Минимальное число звонков до срабатывания защиты; предохраняет от ложных срабатываний на малых выборках

Кампания, остановленная защитой от сбоев, ведет себя как вручную поставленная на паузу: текущие звонки нормально завершаются, а после устранения причины кампанию можно возобновить.

Жизненный цикл кампании

Статус	Значение
`created`	Создана, но не запущена
`syncing`	Контакты ставятся в очередь
`running`	Активно обзванивает контакты
`paused`	Остановлена; продолжит с того места, где остановилась
`completed`	Все контакты обработаны
`failed`	Произошла фатальная ошибка

Кампанию можно ставить на паузу и возобновлять в любой момент. Текущие звонки нормально завершаются до того, как пауза вступит в силу.

Значения по умолчанию для организации

Лимиты кампаний и стартовые значения задаются на уровне организации, и форма создания кампании читает их из GET /api/v1/organizations/campaign-defaults:

Поле	Что это
`concurrent_call_limit`	Потолок, который организация не может превысить. Форма кампании сверяет с ним ваш параллелизм.
`from_numbers_count`	Сколько активных номеров у конфигурации телефонии по умолчанию — параллелизм сверх запаса caller ID бессмысленен.
`default_retry_config`	Настройки повторов, с которых стартует первая кампания: повторы включены, `max_retries: 1`, `retry_delay_seconds: 120`, повтор при «занято» и «не ответил», но не при автоответчике.
`last_campaign_settings`	Конфигурация повторов, параллелизм, расписание и защита от сбоев из вашей последней кампании.

Если кампании уже были, форма подставляет значения из last_campaign_settings, иначе — из default_retry_config. Так вторая кампания начинается там, где закончилась первая, а не с нуля.

Этот эндпоинт работает только на чтение. concurrent_call_limit — настройка организации на стороне оператора (значение по умолчанию для развёртывания — 10); поднять её через API самостоятельно нельзя.

Перезвон по завершённой кампании

Когда кампания завершается, часть контактов просто не взяла трубку. Не нужно собирать по ним CSV вручную: нажмите Перезвонить на странице кампании — кнопка появляется только у кампании в состоянии completed — или вызовите POST /api/v1/campaign/{campaign_id}/redial. Агентика создаст новую кампанию, список контактов которой — ровно те абоненты родительской кампании, чей последний звонок закончился одной из отмеченных вами причин:

Причина	Когда включается
Voicemail	Последний звонок принял автоответчик
Не ответил	Последний звонок остался без ответа
Занято	Линия была занята

curl -X POST https://your-agentika-instance/api/v1/campaign/17/redial \
  -H "Authorization: Bearer $AGENTIKA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Обзвон Q3 (Перезвон)",
        "retry_on_voicemail": true,
        "retry_on_no_answer": true,
        "retry_on_busy": true
      }'

Все три причины по умолчанию true; хотя бы одна должна остаться включённой.
Новая кампания создаётся в состоянии created, контакты уже поставлены в очередь из исходных контекстов родительской кампании — проверьте её и запустите как обычную.
Она наследует настройки повторов родителя, если вы не передали новый retry_config; имя по умолчанию — <имя родителя> (Redial).
Перезвон по кампании можно сделать только один раз. После этого родительская кампания ссылается на кампанию-перезвон, а кнопка исчезает.
Если под выбранные причины никто не подошёл, запрос отклоняется: перезванивать некому.

Результаты

Звонок каждого контакта создает запись запуска с полным транскриптом, записью разговора и собранным контекстом, как при ручном запуске. Чтобы получить их все, используйте эндпоинт получения запусков кампании.

Выгрузка результатов в CSV

GET /api/v1/campaign/{campaign_id}/report отдаёт потоком CSV по завершённым запускам кампании с именем campaign_<id>_report.csv. На странице кампании это кнопка Скачать отчёт с необязательным диапазоном дат; параметры start_date и end_date (ISO 8601) фильтруют по времени создания запуска. В файле одна строка на запуск:

Run ID,Campaign ID,Agent ID,Agent Definition ID,Created At,Phone Number,Call Disposition,Call Duration (s),<extracted variables…>,Call Tags,Transcript URL,Recording URL

Каждая переменная, извлечённая агентом за время кампании, получает свой столбец — так что выгрузка сразу заменяет ручной сбор данных из транскриптов.

Выгрузка загруженного списка контактов

GET /api/v1/campaign/{campaign_id}/source-download-url возвращает подписанную ссылку (presigned URL) на исходный CSV с контактами, действующую один час:

{ "download_url": "https://…", "expires_in": 3600 }

Страница кампании использует её в действии Скачать CSV. Ссылка работает только для кампаний, созданных из загруженного CSV, и файл должен принадлежать вашей организации. Чтобы начать, см. справочник API кампаний.

Начало работы

Основные понятия

Конфигурации

Конструктор голосовых агентов

Телефония

Интеграции

Как работает кампания

CSV с контактами

Расписание и параллелизм

Поведение повторов

Защита от сбоев (circuit breaker)

Жизненный цикл кампании

Значения по умолчанию для организации

Перезвон по завершённой кампании

Результаты

Выгрузка результатов в CSV

Выгрузка загруженного списка контактов

​Как работает кампания

​CSV с контактами

​Расписание и параллелизм

​Поведение повторов

​Защита от сбоев (circuit breaker)

​Жизненный цикл кампании

​Значения по умолчанию для организации

​Перезвон по завершённой кампании

​Результаты

​Выгрузка результатов в CSV

​Выгрузка загруженного списка контактов

Как работает кампания

CSV с контактами

Расписание и параллелизм

Поведение повторов

Защита от сбоев (circuit breaker)

Жизненный цикл кампании

Значения по умолчанию для организации

Перезвон по завершённой кампании

Результаты

Выгрузка результатов в CSV

Выгрузка загруженного списка контактов