Web API: как ваша система сама запускает обзвоны
Этот раздел объясняет, что умеет Web API, как получить ключ доступа, как через него запустить обзвон и как читать ответы. Раздел состоит из двух частей, и они для разных людей:- «Как это работает» не требует знания программирования: что происходит, кто за что отвечает и что нужно решить до первого запроса.
- «Технический справочник» — для разработчика: адреса запросов, поля, форматы ответов, коды ошибок и примеры.
Как читать контракт. Всё, что названо в таблице, стабильно, если в таблице не сказано иное. Две вещи в контракт не входят:
error.message (английское диагностическое пояснение) и поле message внутри элементов blockers / warnings в успешных ответах по кампаниям. Новые поля и новые коды со временем добавляются — незнакомое поле считайте непрозрачным, а незнакомый код разбирайте по error.type + error.status.Что это такое и зачем
Обычно кампанию обзвона заводит человек: заходит в кабинет, создаёт кампанию, загружает файл с номерами, нажимает Запустить. Это удобно, пока обзвоны эпизодические. Web API нужен, когда обзвон должен запускаться сам — из вашей системы, в тот момент, когда там произошло событие. Появилась просрочка по договору, закрылась заявка, наступила дата напоминания — ваша система отправляет платформе один запрос, и обзвон начинается. Человек в этот момент не участвует.Главное свойство: под капотом это тот же продукт. Кампания, созданная запросом, ничем не отличается от созданной в кабинете. Те же проверки перед запуском, тот же разбор номеров, тот же реестр «не звонить», тот же планировщик, те же ограничения частоты звонков на номер, те же записи разговоров и отчёты. Она видна в кабинете в общем списке, её можно поставить на паузу мышкой. Это не «второй продукт для разработчиков» — это вторая дверь в один и тот же.
Две модели работы — выберите одну
Смешивать их в одной задаче не нужно: если вы отдаёте список кампанией, платформа сама решает, кому и когда звонить, и вмешательство «сверху» отдельными звонками ломает её расчёт темпа.
Дальше раздел в основном про кампании — это то, ради чего Web API обычно и подключают; отдельные звонки описаны в Отдельных звонках.
Как это работает
Ключ доступа и подготовка
Как выпустить ключ, что должно быть готово до первого запроса и чек-лист перед запуском.
Как проходит обзвон
Что происходит после запроса, как читать ответ и зачем обязателен ключ повтора.
Согласие и ответственность
Подтверждение согласия, реестр «не звонить» и что платформа делает сама.
Когда что-то пошло не так
Частые отказы, что они означают и что с ними делать.
Технический справочник
Обращение к API
Базовый адрес, аутентификация, форматы и карта всех запросов.
Создание кампании
POST /v1/campaigns: заголовки, тело запроса, порядок отказов.Объект кампании
Что приходит в ответе и как читать блокеры и предупреждения запуска.
Поля кампании
Повторы, номера, привязка набора, согласие, сверка с реестром, идемпотентность.
Управление кампанией
Запуск, пауза, отмена, прогресс, статистика и добавление партий номеров.
Отчёт по загрузке номеров
Что вернулось по каждой строке файла и построчные коды замечаний.
Отдельные звонки
POST /v1/calls/phone, объект звонка, чтение, завершение и список.Исходы звонка
Ось исходов:
call_status, status_reason и как они складываются в вердикт.Вебхуки
События
call_ended и call_analyzed, подпись, повторы и порядок доставки.Коды ошибок и пример
Полный перечень кодов и рабочий сценарий одним куском.