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

# Web API

> Как ваша система сама запускает обзвоны: с чего начать и где что описано.

# Web API: как ваша система сама запускает обзвоны

Этот раздел объясняет, что умеет Web API, как получить ключ доступа, как через него запустить обзвон и как читать ответы.

Раздел состоит из двух частей, и они для разных людей:

* **«Как это работает»** не требует знания программирования: что происходит, кто за что отвечает и что нужно решить до первого запроса.
* **«Технический справочник»** — для разработчика: адреса запросов, поля, форматы ответов, коды ошибок и примеры.

<Note>
  **Как читать контракт.** Всё, что названо в таблице, стабильно, если в таблице не сказано иное. Две вещи в контракт **не входят**: `error.message` (английское диагностическое пояснение) и поле `message` внутри элементов `blockers` / `warnings` в успешных ответах по кампаниям. Новые поля и новые коды со временем добавляются — незнакомое поле считайте непрозрачным, а незнакомый код разбирайте по `error.type` + `error.status`.
</Note>

## Что это такое и зачем

Обычно кампанию обзвона заводит человек: заходит в кабинет, создаёт кампанию, загружает файл с номерами, нажимает **Запустить**. Это удобно, пока обзвоны эпизодические.

Web API нужен, когда обзвон должен запускаться **сам** — из вашей системы, в тот момент, когда там произошло событие. Появилась просрочка по договору, закрылась заявка, наступила дата напоминания — ваша система отправляет платформе один запрос, и обзвон начинается. Человек в этот момент не участвует.

<Note>
  **Главное свойство: под капотом это тот же продукт.** Кампания, созданная запросом, ничем не отличается от созданной в кабинете. Те же проверки перед запуском, тот же разбор номеров, тот же реестр «не звонить», тот же планировщик, те же ограничения частоты звонков на номер, те же записи разговоров и отчёты. Она видна в кабинете в общем списке, её можно поставить на паузу мышкой. Это не «второй продукт для разработчиков» — это вторая дверь в один и тот же.
</Note>

## Две модели работы — выберите одну

|                               | **Отдельные звонки**                    | **Кампании**                                    |
| ----------------------------- | --------------------------------------- | ----------------------------------------------- |
| Что вы отправляете            | один номер за раз                       | список номеров (и потом ещё партии, если нужно) |
| Запрос                        | `POST /v1/calls/phone`                  | `POST /v1/campaigns`                            |
| Кто держит темп               | вы                                      | платформа                                       |
| Кто повторяет недозвоны       | вы                                      | платформа, **если вы разрешили повторы**        |
| Кто следит за рабочими часами | вы                                      | платформа                                       |
| Кто сверяет с «не звонить»    | платформа                               | платформа                                       |
| Когда это удобно              | ваша система уже умеет быть дозвонщиком | вы хотите отдать список и получить результат    |

Смешивать их в одной задаче не нужно: если вы отдаёте список кампанией, платформа сама решает, кому и когда звонить, и вмешательство «сверху» отдельными звонками ломает её расчёт темпа.

Дальше раздел в основном про **кампании** — это то, ради чего Web API обычно и подключают; отдельные звонки описаны в [Отдельных звонках](/ru/v4/web-api/calls).

## Как это работает

<CardGroup cols={2}>
  <Card title="Ключ доступа и подготовка" icon="key" href="/ru/v4/web-api/start">
    Как выпустить ключ, что должно быть готово до первого запроса и чек-лист перед запуском.
  </Card>

  <Card title="Как проходит обзвон" icon="play" href="/ru/v4/web-api/how-it-works">
    Что происходит после запроса, как читать ответ и зачем обязателен ключ повтора.
  </Card>

  <Card title="Согласие и ответственность" icon="scale-balanced" href="/ru/v4/web-api/rules">
    Подтверждение согласия, реестр «не звонить» и что платформа делает сама.
  </Card>

  <Card title="Когда что-то пошло не так" icon="triangle-exclamation" href="/ru/v4/web-api/troubleshooting">
    Частые отказы, что они означают и что с ними делать.
  </Card>
</CardGroup>

## Технический справочник

<CardGroup cols={2}>
  <Card title="Обращение к API" icon="plug" href="/ru/v4/web-api/reference">
    Базовый адрес, аутентификация, форматы и карта всех запросов.
  </Card>

  <Card title="Создание кампании" icon="rocket" href="/ru/v4/web-api/campaign-create">
    `POST /v1/campaigns`: заголовки, тело запроса, порядок отказов.
  </Card>

  <Card title="Объект кампании" icon="box" href="/ru/v4/web-api/campaign-object">
    Что приходит в ответе и как читать блокеры и предупреждения запуска.
  </Card>

  <Card title="Поля кампании" icon="sliders" href="/ru/v4/web-api/campaign-fields">
    Повторы, номера, привязка набора, согласие, сверка с реестром, идемпотентность.
  </Card>

  <Card title="Управление кампанией" icon="gauge" href="/ru/v4/web-api/campaign-manage">
    Запуск, пауза, отмена, прогресс, статистика и добавление партий номеров.
  </Card>

  <Card title="Отчёт по загрузке номеров" icon="file-lines" href="/ru/v4/web-api/imports">
    Что вернулось по каждой строке файла и построчные коды замечаний.
  </Card>

  <Card title="Отдельные звонки" icon="phone" href="/ru/v4/web-api/calls">
    `POST /v1/calls/phone`, объект звонка, чтение, завершение и список.
  </Card>

  <Card title="Исходы звонка" icon="list-check" href="/ru/v4/web-api/call-status">
    Ось исходов: `call_status`, `status_reason` и как они складываются в вердикт.
  </Card>

  <Card title="Вебхуки" icon="webhook" href="/ru/v4/web-api/webhooks">
    События `call_ended` и `call_analyzed`, подпись, повторы и порядок доставки.
  </Card>

  <Card title="Коды ошибок и пример" icon="code" href="/ru/v4/web-api/errors">
    Полный перечень кодов и рабочий сценарий одним куском.
  </Card>
</CardGroup>