​

Управление кампанией

{
  "error": {
    "type": "conflict_error",
    "code": "launch_blocked",
    "status": 409,
    "message": "The campaign did not start: error.blockers names every check that did not pass",
    "blockers": [
      {"code": "agent_not_published", "field": "agent_id"},
      {"code": "dnc_matches", "field": "contacts", "dnc_screen": {"status": "matches", "…": "…"}}
    ]
  }
}

​

Добавление номеров в существующую кампанию

POST /v1/campaigns/{id}/calls
Idempotency-Key: <уникальная строка>        (обязателен)

{
  "calls": [
    {"phone": "+77001234567", "timezone": "Asia/Almaty", "variables": {"debt": "15000"}},
    {"phone": "+77007654321", "name": "Daniyar"}
  ],
  "attestation": {"confirmed": true}
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "calls_rejected",
    "status": 422,
    "message": "…",
    "import": {
      "import_id": "imp-b87d984fe7",
      "status": "refused",
      "refusal_code": "calls_rejected",
      "rows_seen": 2,
      "accepted": 0,
      "warned": 0,
      "rejected": 1,
      "dnc_matched": 0,
      "issues_total": 1,
      "issues": [{"row_number": 2, "code": "phone_unreadable", "severity": "error"}]
    }
  }
}

{
  "campaign": {
    "campaign_id": "cam-…", "status": "running", "name": "june collections",
    "agent_id": "collections-agent", "created_via": "api", "launched_via": "api",
    "starts_at": null, "ends_at": null, "timezone": "Asia/Almaty",
    "timezone_source": "request", "accepts_call_additions": true
  },
  "import": { "import_id": "imp-…", "status": "accepted", "rows_seen": 2, "accepted": 2, "warned": 0, "rejected": 0, "duplicates_found": 0, "dnc_matched": 0, "refusal_code": "", "issues": {}, "dnc_screen": {"status": "clean", "as_of_launch": false, "…": "…"}, "dnc_matches": [] },
  "blockers": [{"code": "campaign_paused", "field": "status"}],
  "warnings": [{"code": "starts_immediately", "field": ""}, {"code": "frequency_policy_active", "field": ""}]
}

• Предел — до 1000 строк за запрос по умолчанию (настройка развёртывания): больше — 422 calls_batch_too_large, пустая партия — 422 calls_required. Один запрос считается один раз в лимите ключа.
• Подпись — attestation должна быть ровно {"confirmed": true}: без других ключей и без import_id (иначе 422 attestation_invalid). Каждая принятая партия подписывается отдельно и привязана к своей загрузке; подпись запуска не переиспользуется для строк, которых на момент запуска не существовало.
• Часовой пояс — в кампании с use_contact_timezone: true под казахстанским рыночным профилем строка без timezone — это ошибка данных (timezone_required), и она отклоняет партию: платформа не подставит зону кампании строке, на которую никто не смотрел. У загрузки файла и у planned_calls при создании подстановка сохраняется.
• Дубли — внутри партии duplicate_action работает так же, как для файла. Номер, у которого в кампании уже есть контакт — даже уже набранный, — принимается как новый контакт и набирается снова: для адаптера, который сам управляет перезвонами, повтор и есть перезвон. Если перезвонами управляет ваша система, оставьте retry_config.attempts = 1; при большем бюджете перезвоны станут двухуровневыми.
• Партия никогда не становится запусковой загрузкой кампании — зафиксированный снимок реестра, подпись запуска и dnc_screen в GET /v1/campaigns/{id} продолжают указывать на загрузку, с которой кампанию запускали. Своя сверка партии — в теле 201 и в GET /v1/imports/{import_id}.
• Идемпотентность — ключ ограничен рамками кампании, поэтому один и тот же ключ с одним и тем же телом, отправленный в две кампании, — это две партии. Отклонённая партия освобождает ключ: исправьте строки и пришлите заново с тем же ключом (создастся вторая отклонённая запись загрузки — диагностически полезно, звонков это не касается). Повтор принятой партии переигрывает ответ; тот же ключ с другим телом — 422 idempotency_key_reuse.

​

Кампании, открытые к добавлению номеров

• требует ends_at (422 campaign_open_ends_at_required) не дальше горизонта оператора — по умолчанию 30 суток (422 campaign_open_ends_at_too_far);
• может быть создана вообще без planned_calls и стартует пустой (блокера no_pending_contacts нет);
• закрывается только наступлением ends_at или отменой, но не опустевшей очередью.

​

Прогресс и состояния контактов

{
  "status": "running",
  "total": 120,
  "by_state": {"pending": 80, "in_progress": 3, "done": 30, "exhausted": 5, "suppressed": 2},
  "ready": 78,
  "holds": 2,
  "held_reasons": {"quiet_hours": 2},
  "suppressed_reasons": {"dnc_suppressed": 2},
  "dnc_suppressed_at_launch": 1,
  "dnc_suppressed_mid_campaign": 1,
  "backpressure": 0,
  "infra_retries": 0,
  "next_attempt_at": 1788942000.0,
  "frequency": {"held": 0, "blocked": 0, "by_governing_cap": {}},
  "rate": {"target_per_minute": 10, "actual_per_minute": 4}
}

​

Снятие контакта с обзвона

curl -s -X POST "$BASE_URL/v1/contacts/withdraw" \
  -H "Authorization: Bearer $CFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["+7 701 123 45 67", "77015550011"]}'

{
  "operation_id": "wd-3f9c2a71b0",
  "withdrawn":         [{"contact_id": "cc-…", "campaign_id": "cam-…", "phone": "7011234567"}],
  "already_withdrawn": [],
  "not_withdrawable":  [{"contact_id": "cc-…", "campaign_id": "cam-…", "phone": "7015550011", "reason": "in_call"}],
  "not_found": [],
  "invalid":   []
}

• Что снимается. Контакт, ожидающий набора (pending, включая запланированный перезвон) или ожидающий вердикта аналитики (awaiting). Он переходит в suppressed с причиной withdrawn_by_client и в этой кампании больше не набирается. У контакта в awaiting звонок уже состоялся — снятие отменяет перезвон, который мог бы назначить вердикт.
• Что не снимается. not_withdrawable называет причину: in_call — звонок идёт или контакт только что взят в набор (снятие трубку не кладёт: используйте POST /v1/calls/{call_id}/end, а после звонка снимите контакт ещё раз, если перезвон не нужен), done, exhausted или already_suppressed — исключён раньше самой платформой (реестр «не звонить», частотный лимит, география); прежняя причина сохраняется.
• Повторять безопасно. Idempotency-Key не нужен: уже снятый контакт вернётся в already_withdrawn.
• Как адресовать. Номер сопоставляется по последним десяти цифрам, поэтому написание значения не имеет, а само значение можно слать строкой или числом. Один номер достаёт все контакты, которые его несут, — в кампании с дублями все сразу. Идентификатор контакта — это metadata.contact_id из вебхуков звонка; контакт, который ещё ни разу не набирали, адресуется номером.
• Ручка по организации достаёт и кабинетные кампании: все живые кампании организации, как бы они ни были созданы. Черновики и закрытые кампании не трогаются.
• Частичная обработка. Один плохой адрес не роняет запрос: в invalid вернётся то, что не удалось прочитать (не номер, нет цифр, пустой идентификатор), в not_found — то, под что не нашлось контакта, и то и другое ровно в том виде, в каком вы прислали. По умолчанию не больше 1000 адресов на запрос.
• Последствия. Если снять последние ожидающие контакты идущей кампании, она завершится на следующем проходе диалера — кроме кампании, открытой к добавлению номеров. Снятый номер вернётся в набор только с новой партией звонков.