​

Как проходит обзвон

​

Как проходит обзвон, запущенный запросом

Шаг 1. Ваша система отправляет один запрос. В нём: название кампании, имя агента, скорость обзвона, рабочие часы, цель обзвона, подтверждение согласия и сам список номеров с данными для разговора. Шаг 2. Платформа разбирает список. Тот же разбор, что у файла в кабинете: нормализация номеров, поиск дублей, проверка обязательных колонок, сверка с реестром «не звонить», проверка географии для США. Ничего из этого на пути через API не пропускается и не упрощается. Шаг 3. Платформа проверяет, можно ли запускать. Опубликован ли агент, есть ли линия, не в прошлом ли окно, подписано ли подтверждение, не все ли номера оказались в реестре «не звонить». Шаг 4. Если всё в порядке — обзвон начинается. Тем же планировщиком, что и у кампаний из кабинета: с вашей скоростью, в ваши рабочие часы, с повторами недозвонов по вашим правилам и с учётом ограничений частоты звонков на один номер, действующих в вашей организации. Шаг 5. Вы читаете ответ. В нём — что получилось: поехал ли обзвон, сколько строк принято, что не так с непринятыми. Отдельного «нажатия кнопки» в этой схеме нет: один запрос делает все три вещи сразу — создаёт, принимает номера и запускает.

​

Как читать ответ

Ответ приходит всегда, даже когда обзвон не начался. Читается он по одному полю и двум спискам. status — единственный ответ на вопрос «поехало ли»: blockers — почему не начался. Это не «ошибки запроса», а состояние дел: агент снят с публикации, номера попали в реестр «не звонить», окно в прошлом, нет подписи под подтверждением согласия. Каждая причина названа отдельным кодом — тем же, что виден в кабинете на экране запуска. warnings — предупреждения. Они ничего не блокируют и есть почти у каждой кампании: например, «начало не задано — набор начнётся сразу» и «действует частотная политика» с цифрами, сколько раз в сутки и за неделю можно звонить на один номер. import — что стало со списком номеров. Сколько строк увидели, сколько приняли, сколько с предупреждениями, сколько отклонили, сколько дублей, и по каким причинам (сгруппировано по коду причины с номерами первых строк). dnc_screen отдельно называет: сколько читаемых строк проверено, сколько не проверено, сколько строк совпало с реестром и сколько это уникальных номеров; каждое совпадение несёт строку, исходный телефон, имя, причину и запись реестра.

​

Одно правило, которое избавляет от догадок

Действие, которое ничего не изменило, — всегда ошибка. Успешный ответ означает, что состояние в теле ответа и есть новое состояние. Поэтому:

• запрос на создание отвечает успехом, даже если обзвон не начался: кампания и отчёт действительно созданы, и status честно говорит draft;
• отдельный запрос «запусти», который ничего не запустил, отвечает ошибкой — и называет причину в самой ошибке, чтобы не пришлось спрашивать второй раз;
• повторная команда «поставь на паузу» уже остановленной кампании — не ошибка: состояние и так такое, как вы просили.

​

Повторная отправка: почему обязателен «ключ повтора»

Сеть иногда обрывает ответ уже после того, как платформа всё сделала. Ваша система в этот момент не знает, дошёл запрос или нет, и обычно повторяет его. Для одного звонка это неприятно; для списка из десяти тысяч номеров это означает обзвонить всех дважды. Поэтому на создании кампании и на добавлении номеров в неё обязателен заголовок Idempotency-Key — произвольная строка, которую ваша система придумывает для каждой новой кампании или партии (например, идентификатор задачи в вашей системе). Дальше платформа разбирается сама:

• тот же ключ, то же тело — вернётся тот же ответ, что и в первый раз; вторая кампания не появится;
• тот же ключ, пока первый запрос ещё выполняется — отказ 409 idempotency_key_in_flight: подождите ответ, не повторяйте снова;
• тот же ключ, но ДРУГОЕ тело — отказ 422 idempotency_key_reuse. Это защита от самой неприятной ошибки: без неё вы получили бы ответ на чужой запрос и решили бы, что платформа проигнорировала ваши настройки;
• запрос отклонён до создания кампании — ключ освобождается сразу, и исправленный запрос с тем же ключом пройдёт нормально. Если отказ случился уже после создания (например, не удалось сохранить список), ключ остаётся занятым, а созданную кампанию можно найти в списке кампаний.

Ключи помнятся сутки. Практический вывод: новая кампания — новый ключ, новая партия — новый ключ. Повторять с прежним ключом стоит только буквально тот же запрос.