API планировщика звонков

Типичный паттерн использования API включает в себя следующие шаги:

  1. Загрузить номера в стоп-лист
  2. Создать кампанию
  3. Выставить настройки для кампании
  4. Загрузить номера на прозвон в кампанию
  5. Поменять статус кампании на activated
  6. Ожидать окончания кампании
  7. Выгрузить результаты прозвона по кампании

О кампании

  • Кампания - это один прозвон на одну тему. Например, уведомление клиентов о поступлении нового товара.
  • У кампании есть временные рамки. Момент начала (startTime) и момент окончания (finishTime). Планировщик не будет начинать звонки вне этих временных рамок. Допускается, что планировщик начнет некоторое количество звонков незадолго до момента окончания и эти звонки могут начаться и закончится после.
  • У кампании есть количество попыток на дозвон до человека (maxAttempts). Планировщик будет звонить человеку несколько раз в рамках одной кампании, до тех пор, пока не случится удачный дозвон. Удачным он считается, если человек поднял трубку. Между дозвонами одному и тому же человеку планировщик будет ожидать minDelayBetweenAttempts секунд, чтобы сразу же не спалить все попытки.
  • У кампании есть локальные временные рамки. Они указываются, используя clientStart и clientEnd. Это время в локальном часовом поясе клиента. Эта опция существует, чтобы планировщик не начал звонок, пока у клиента глубокая ночь.
  • Чтобы локальные временные рамки клиента работали, планировщик должен знать в каком часовом поясе находится клиент. Для этого, при загрузке номеров, у номера должен быть указан либо часовой пояс от UTC, либо город проживания. Если часовой пояс указан, планировщик использует его, если нет, планировщик использует информацию о городе. Если и город не указан, планировщик использует часовой пояс телефонного номера человека. Если о телефоне человека нет информации в базе планировщика, он использует defaultTimezone.
  • Порядок вызовов номеров ничем не гарантируется, планировщик может дозваниваться номерам в любом порядке, вне зависимости от их расположения в таблице. Он пытается сделать это наиболее эффективно, чтобы прозвонить как можно большее количество номеров в заданные рамки.
  • В случае, если у одного робота существует несколько активных в данный момент кампаний, планировщик обращает внимание на поле priority у кампании, чтобы определить их важность и отсортировать номера для прозвона. Новосозданной кампании автоматически выставляется наивысший приоритет. Приоритет можно изменить, используя PATCH /{botId}/companies/{id}
  • Зачастую необходимо ограничисть количество звонков в промежуток времени, например, чтобы отдел продаж мог обработать заявки. Для этого существует поле maxTasksPerHour.
  • Для получения статистики "в реальном времени" рекомендуется вызывать GET /{botId}/companies/{id} раз в минуту. Ответ содержит поле stats, которое содержит информацию о количестве событий, произошедших с кампанией.

О статусе кампании

Текущее состояние кампании отслеживается в поле status информации о кампании.

Статусы бывают следующих видов:

  • draft - Черновик
  • activated - Активирована
  • calling - Звонит прямо сейчас
  • paused - Приостановлена
  • cancelled - Отменена
  • completed - Завершена
  • blocked - Заблокирована

При создании кампании ей присваивается статус черновика. Черновые кампании не звонят и никаким образом не влияют на робота. Вывести кампанию из статуса черновика можно вручную методом PATCH /{botId}/companies/{id}/status. При этом происходит проверка на наличие всей необходимой информации внутри кампании. Если не все поля проставлены, метод вернет ошибку.

Пользователь может перевести кампанию в статус activated для старта обзвона. В этот момент планировщик начинает учитывать кампанию при построении очереди обзвона. Присвоение этого статуса не означает что звонки начнутся сразу же.

Если планировщик начал звонок в рамках кампании и он сейчас находится в процессе, кампании присваивается статус calling. По большому счету его можно считать косметическим и эквивалентным activated.

Пользователь может перевести кампанию в статус paused для приостановки инициации новых звонков. Текущие звонки завершатся как обычно, но новые не будут появляться до перевода обратно в activated.

Пользователь может перевести кампанию в статус cancelled для полной отмены кампании. Текущие звонки завершатся как обычно. После этого кампания не может быть продолжена, так как рабочее состояние кампании стирается из базы данных.

Планировщик может перевести кампанию в статус completed. Это происходит в нескольких случаях:

  • Кампания достигла своего дедлайна (finishTime).
  • В кампании кончились номера для обзвона. К примеру, до части номеров удалось дозвониться успешно, а у части номеров кончились попытки дозвона (maxAttempts).

Планировщик может перевести кампанию в статус blocked в случае удаления телефонной интеграции в Томору. В таком случае совершать новые звонки невозможно. Возобновить функционирование всех кампаний в роботе можно путем реактивации в интерфейсе кампаний в Томору.

О стоп-листе

  • Стоп-лист - это список номеров, используемый для фильтрации нежелательных звонков. Например, государственные номера, или номера клиентов, которые отказались от получения звонков.
  • На всего робота один стоп-лист.
  • Планировщик использует стоп-лист для фильтрации номеров на этапе загрузки номеров в кампанию. Если в стоп лист добавить номера уже после того, как номера были загружены в кампанию, то ничего не произойдет.

Загрузка номеров

Все методы загрузки или удаления телефонных номеров используют табличный формат. На данный момент поддерживаются GoogleSheets, Excel (+ OpenOffice) и CSV. Excel использовать нежелательно, так как по сравнению с остальными сильно более ресурсозатратен и занимает больше времени. Кроме того, для удобства использования по API есть возможность загружать номера телефонов в JSON. Планировщик использует значение заголовка Content-Type для определения формата данных. Все поддерживаемые форматы перечислены ниже:

  • application/vnd.ms-excel
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
  • application/vnd.ms-excel.sheet.macroEnabled.12
  • application/vnd.ms-excel.addin.macroEnabled.12
  • application/vnd.ms-excel.sheet.binary.macroEnabled.12
  • application/vnd.oasis.opendocument.spreadsheet
  • application/x-vnd.oasis.opendocument.spreadsheet
  • text/csv
  • application/json

Корневой URL

https://europe-west1-hypercalls.cloudfunctions.net/api-callPlanner

Аутентификация

Для использования API планировщика необходимо получить токен доступа. Сделать это можно в разделе "Токены API" в кабинете робота.

Полученный токен доступа необходимо передавать в заголовке Authorization в следующем формате:

Authorization: Bearer {token}

Методы

Данный раздел представляет собой ознакомительный шорт-лист методов.

С полной спецификацией в формате OpenAPI можно ознакомиться, перейдя по ссылке: OpenAPI спецификация.

Кампании

GET /{botId}/companies

Получает список кампаний, которые сейчас присутствуют в роботе.

Этот метод поддерживает функционал поиска, пагинации и фильтрации.

POST /{botId}/companies

Создает новую кампанию.

GET /{botId}/companies/{id}

Получает информацию о кампании.

В теле ответа так же присутствует сжатая статистика по этапам прозвона.

DELETE /{botId}/companies/{id}

Удалить конкретную кампанию.

Удаление кампании в процессе работы может привести к неожиданным результатам. Текущие звонки (и звонки в очереди на прозвон) не будут остановлены. Рекомендуется поменять статус кампании на cancelled для корректного завершения работы.

PATCH /{botId}/companies/{id}

Изменяет конкретную кампанию.

Все настройки кампании должны быть переданы разом. Частичное изменение не поддерживается.

GET /{botId}/companies/{id}/statistics

Выгрузить статистику по кампании.

Метод может выполняться довольно долго и он довольно тяжел, поэтому лучше вызывать его один раз по окончанию прозвона. Возвращает полную статистику с разбиением по номерам. В статистике присутствуют дополнительные поля, которые были переданы при загрузке номеров в кампанию.

PATCH /{botId}/companies/{id}/status

Изменить статус кампании.

POST /{botId}/companies/{id}/add-phone-numbers

Добавить номера телефонов к кампании.

В таблице должна присутствовать именованная колонка "Телефон". Необязательно могут присутствовать колонки "Город" и "Часовой пояс" - см. заметки по кампаниям. Кроме того, допускается наличие других колонок, планировщик запоминает их и использует в выгрузке.

POST /{botId}/companies/{id}/remove-phone-numbers

Удалить номера телефонов из кампании.

В таблице должна присутствовать колонка "Телефон".

Стоп-лист

POST /{botId}/stop-list/add-phone-numbers

Добавляет номера телефонов в стоп-лист робота. В таблице должна присутствовать именованная колонка "Телефон".

POST /{botId}/stop-list/remove-phone-numbers

Удаляет номера телефонов из стоп-листа робота В таблице должна присутствовать именованная колонка "Телефон".

GET /{botId}/stop-list

Выдает количество номеров в стоп-листе.

DELETE /{botId}/stop-list/phone-numbers

Очищает стоп-лист полностью.