Кампании

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

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

Загрузите contacts CSV — в нем должен быть столбец phone_number; все дополнительные столбцы станут initial_context для каждого звонка
Создайте campaign — привяжите ее к workflow, задайте concurrency, time slots и retry behaviour
Запустите ее — Агентика начнет обзванивать контакты в пределах вашего concurrency limit
Следите за прогрессом — отслеживайте processed, completed, failed и pending в реальном времени
Ставьте на паузу и возобновляйте — можно остановить и перезапустить кампанию в любой момент без потери прогресса

Contacts 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 в каждый звонок и становятся доступны как template variables в prompt агента. Так каждый звонок может быть персонализированным даже в масштабе.

Расписание и concurrency

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

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

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

Retry behaviour

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

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

max_retries принимает значения 0–10, retry_delay_seconds — 30–3600.

Circuit breaker

Circuit breaker автоматически ставит кампанию на паузу, когда доля неудачных звонков становится слишком высокой. Это защищает от лишних расходов и проблем с telephony reputation из-за неправильно настроенного агента или плохого списка контактов. Когда он включен, Агентика отслеживает failure rate в скользящем временном окне. Если показатель превышает threshold, кампания автоматически ставится на паузу; возобновить ее нужно вручную после расследования проблемы.

Setting	Default	Description
Failure Threshold (%)	`50`	Поставить на паузу, когда failure rate в окне превышает этот процент
Window (seconds)	`120`	Скользящее временное окно, по которому считается failure rate
Min Calls in Window	`5`	Минимальное число звонков до срабатывания circuit breaker; защищает от false positives на малых выборках

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

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

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

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

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

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

Поле	Что это
`concurrent_call_limit`	Потолок, который организация не может превысить. Форма кампании сверяет с ним ваш concurrency.
`from_numbers_count`	Сколько активных номеров у telephony configuration по умолчанию — concurrency сверх запаса caller ID бессмысленен.
`default_retry_config`	Retry-настройки, с которых стартует первая кампания: retry включён, `max_retries: 1`, `retry_delay_seconds: 120`, повтор при «занято» и «не ответил», но не при voicemail.
`last_campaign_settings`	Retry config, concurrency, расписание и circuit breaker из вашей последней кампании.

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

Этот endpoint работает только на чтение. 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 outreach (Redial)",
        "retry_on_voicemail": true,
        "retry_on_no_answer": true,
        "retry_on_busy": true
      }'

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

Результаты

Звонок каждого контакта создает run record с полным transcript, recording и gathered context, как при ручном запуске. Чтобы получить их все, используйте endpoint Get Campaign Runs.

Выгрузка результатов в 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

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

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

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

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

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

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

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

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

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

Телефония

Интеграции

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

Contacts CSV

Расписание и concurrency

Retry behaviour

Circuit breaker

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

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

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

Результаты

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

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

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

​Contacts CSV

​Расписание и concurrency

​Retry behaviour

​Circuit breaker

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

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

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

​Результаты

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

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

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

Contacts CSV

Расписание и concurrency

Retry behaviour

Circuit breaker

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

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

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

Результаты

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

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