Создание кампании

Один запрос делает три вещи: создаёт кампанию, принимает запланированные звонки и — если все проверки запуска прошли — начинает набор. Отдельного шага «старт» в счастливом пути нет.

Заголовки

Заголовок	Обязателен	Примечания
`Authorization: Bearer YOUR_API_KEY`	да
`Content-Type: application/json`	да
`Idempotency-Key: <уникальная строка>`	да	В отличие от `POST /v1/calls/*`, здесь не опционален: повтор после сетевого таймаута создал бы вторую кампанию и обзвонил весь список дважды. Отсутствует или пуст → `422 idempotency_key_required`. Протокол — в конце этого раздела, «Идемпотентность запросов по кампаниям».

Тело запроса

Неизвестные поля верхнего уровня игнорируются.

Поле	Тип	Обяз.	По умолч.	Описание
`name`	string	да	—	Название кампании, видное в кабинете; 1–80 символов после обрезки пробелов (иначе `422 campaign_spec_invalid`).
`agent_id`	string	да	—	Имя агента, разрешается внутри вашей организации. Неизвестное имя → `422 campaign_agent_unknown`. Существующий, но неопубликованный агент принимается: кампания создаётся черновиком с блокером `agent_not_published`.
`calls_per_minute`	integer	да	—	Скорость — это ступень, а не произвольное число: одно из `1, 2, 5, 10, 20, 30, 60, 100, 200` (иное → `422 campaign_spec_invalid`). Значение применяется как есть: потолка развёртывания, который урезал бы его, нет.
`planned_calls`	array	нет	`[]`	Номера для набора, см. ниже. Пусто — кампания создана без чего набирать (блокер `no_pending_contacts`, если только не задан `accepts_call_additions`).
`starts_at` / `ends_at`	number \| null	нет	`null`	Окно кампании. `null` в начале означает «сейчас». `ends_at` должен быть позже `starts_at` (иначе `422 campaign_window_invalid`). Дата начала в прошлом (по календарной дате в зоне кампании) блокирует запуск (`starts_date_past`); прошедший `ends_at` — тоже (`ends_at_past`).
`timezone`	string	нет	`""`	Название зоны IANA (`Asia/Almaty`), в которой трактуются окно и рабочие часы. Не указана → зона организации. Неизвестная → `422 campaign_timezone_unknown`; фиксированные смещения не принимаются.
`working_hours`	array	нет	`[]`	Строки расписания `{"days": [0..6], "start": "ЧЧ:ММ", "end": "ЧЧ:ММ"}` (`days`: 0 — понедельник, непустой; `start` строго раньше `end`; строка никогда не переходит через полночь — ночная смена это две строки). Неверная форма → `422 campaign_spec_invalid`. Кампания может только сужать базовое окно вашей организации: под пакетом рынка США — законное окно юрисдикций контактов, иначе — окно обзвона организации; более широкая строка → `422 working_hours_wider_than_law`. Пусто означает, что действует само базовое окно — кампания ничего не сужает, а набор ограничен законным окном (предупреждение `working_hours_law_only`) либо окном обзвона организации (`working_hours_org_window_only`). Круглосуточного набора не бывает.
`call_strategy`	`"standard"` \| `"expert"`	нет	`"standard"`	`standard` повторяет по фиксированной лестнице; `expert` решает по каждому исходу из правил `retry_config.rules`.
`retry_config`	object	нет	`{"attempts": 1, "interval_s": 900}`	См. «Настройку повторов» ниже в этом разделе. По умолчанию — одна попытка, без перезвонов.
`duplicate_action`	`"reject"` \| `"keep_first"` \| `"keep_last"`	нет	`"reject"`	Что делать, если один и тот же телефон встречается в `planned_calls` дважды (и внутри партии `calls`).
`classification`	`"marketing"` \| `"servicing"` \| `"debt_collection"`	нет	`"marketing"`	Чем звонит кампания. Определяет тип согласия, под которым ставится подпись (`marketing` → `pewc`, `servicing` и `debt_collection` → `pec`), поэтому не угадывается: не указали — берётся самый строгий. Иное → `422 campaign_classification_invalid`.
`use_contact_timezone`	boolean	нет	`false`	Набирать каждый контакт в его собственной зоне (из колонки `timezone`), а не в зоне кампании.
`trunk_id`, `route_id`, `from_number`	string	нет	разрешается	Привязка набора, см. ниже.
`attestation`	object	нет	—	`{"confirmed": true}` — подтверждение согласия, необходимое до набора. При создании необязательно: без него кампания создаётся черновиком с блокером `attestation_required`.
`accepts_call_additions`	boolean	нет	`false`	Держать кампанию открытой к добавлению партий номеров (Управление кампанией): опустевшая очередь её не завершает, только `ends_at` или отмена. Требует `ends_at` (`422 campaign_open_ends_at_required`) не дальше горизонта оператора, по умолчанию 30 суток (`422 campaign_open_ends_at_too_far`). Задаётся только при создании.
`dnc`	`"block"` \| `"skip"`	нет	`"block"`	Что делать с номерами из реестра «не звонить». Иное значение → `422 dnc_decision_invalid`.

Поля, которые у кампании есть, но через /v1 не задаются (frequency_override, кабинетные пресеты), молча игнорируются.

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

До того как кампания создана (слот идемпотентности освобождается, исправленный повтор с тем же ключом пройдёт):

422 invalid_request — тело не проходит схему (нет name, agent_id или calls_per_minute, неверные типы).
422 idempotency_key_required, 422 dnc_decision_invalid.
422 idempotency_key_reuse / 409 idempotency_key_in_flight / переигровка прежнего ответа.
422 campaign_window_invalid, затем 422 campaign_open_ends_at_required / campaign_open_ends_at_too_far.
422 campaign_agent_unknown, 422 campaign_timezone_unknown.
Привязка набора: 422 dialing_route_unresolved / dialing_route_ambiguous / dialing_binding_incomplete.
422 working_hours_wider_than_law.
Валидация хранилища: 422 campaign_spec_invalid (ступень, настройка повторов, форма рабочих часов, действие по дублям, длина названия), 422 campaign_classification_invalid.

После того как кампания создана (слот остаётся занятым — повтор с тем же ключом отвечает 409 idempotency_key_in_flight; кампанию ищите через GET /v1/campaigns):

Запланированные звонки: 409 market_package_not_installed, 502 contact_file_storage_unavailable, 422 contact_rows_rejected (строки не удалось сохранить вовсе — это не то же самое, что строки, отклонённые разборщиком: те приходят внутри import вместе с 201).
Запуск: 409 campaign_transition_invalid (неожиданная гонка состояний).

Успешный ответ — `201 Created`

Ответ всегда 201, если кампания создана, независимо от того, начался ли набор. Единственный источник истины об этом — status.

{
  "campaign_id": "cam-b9b536a86e",
  "status": "running",
  "created_via": "api",
  "launched_via": "api",
  "name": "june collections",
  "agent_id": "collections-agent",
  "timezone": "Asia/Almaty",
  "timezone_source": "request",
  "starts_at": null,
  "ends_at": null,
  "accepts_call_additions": false,
  "calls_per_minute": 10,
  "call_strategy": "standard",
  "classification": "marketing",
  "consent_tier": "pewc",
  "retry_config": { "attempts": 1, "interval_s": 900 },
  "duplicate_action": "reject",
  "use_contact_timezone": false,
  "working_hours": [{ "days": [0, 1, 2, 3, 4], "start": "09:00", "end": "19:00" }],
  "binding": { "trunk_id": "trk-31d4dc745a", "route_id": "rt-out-a", "from_number": "77000000001" },
  "import": {
    "import_id": "imp-353d158dd2",
    "status": "accepted",
    "rows_seen": 2,
    "accepted": 2,
    "warned": 0,
    "rejected": 0,
    "duplicates_found": 0,
    "dnc_matched": 0,
    "refusal_code": "",
    "issues": {},
    "dnc_screen": { "status": "clean", "checked_rows": 2, "unscreened_rows": 0, "matched_rows": 0, "suppressed_contacts": 0, "fingerprint": "20e2…", "items": [], "has_more": false, "hidden_rows": 0, "all_dialable_suppressed": false, "as_of_launch": true, "screened_at": 1788941847.27, "audit_id": 2, "decision": "clean", "import_id": "imp-353d158dd2" },
    "dnc_matches": []
  },
  "dnc_screen": { "status": "clean", "as_of_launch": true, "…": "тот же объект, что import.dnc_screen" },
  "blockers": [],
  "warnings": [
    { "code": "starts_immediately", "message": "…" },
    { "code": "frequency_policy_active", "rolling_7d_cap": 7, "daily_cap": 2, "source": "platform_default", "message": "…" }
  ]
}

​Создание кампании

​Заголовки

​Тело запроса

​Порядок отказов на создании

​Успешный ответ — 201 Created

Создание кампании

Заголовки

Тело запроса

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

Успешный ответ — `201 Created`