JAICP

Calls API


Платформа JAICP предоставляет Calls API для работы с исходящей телефонией.

Перед началом работы с Calls API необходимо:

  1. Настроить телефонию.
  2. Подключить телефонный канал.
  3. Создать обзвон.

Методы API

API предоставляет методы для следующих операций:

  1. Добавление телефонных номеров с параметрами в обзвон.

    • POST /api/calls/campaign/{token}/addPhones
    • GET /api/crmCalls/campaign/{token}/addPhone
    • POST /api/crmCalls/campaign/{token}/addPhone
  2. Отмена созданных заданий на обзвон.

    • POST /api/calls/campaign/{token}/callJob/cancel
  3. Получение отчетов по ID задания на обзвон или по номеру телефона.

    • POST /api/calls/campaign/{token}/callJob/getReport
    • POST /api/calls/campaign/{token}/callAttempt/getReport
  4. Приостановление, возобновление и остановка обзвона.

    • POST /api/calls/campaign/{token}/control/pause
    • POST /api/calls/campaign/{token}/control/resume
    • POST /api/calls/campaign/{token}/control/stop

Подробное описание Calls API: методы, параметры запроса, форматы ответа, примеры, возвращаемые ошибки


Параметры запросов

Обязательные параметры

В строки запросов к Calls API подставляются следующие обязательные параметры:

  • host_name — имя хоста, на котором запущен обзвон.
  • token — уникальный токен для управления обзвоном.

Получить токен можно на вкладке Обзвоны, нажав на иконку    рядом с названием обзвона либо на    > Скопировать API-токен.

Например, для https://app.jaicp.com/ строка запроса на добавление телефонных номеров может выглядеть следующим образом:

https://app.jaicp.com/api/calls/campaign/8231.7056.1b131df1/addPhones

Ключ идемпотентности

Чтобы контролировать согласованность создаваемых ресурсов, клиентские приложения могут генерировать и передавать в Calls API ключ идемпотентности.

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

Если же для таких запросов ключ идемпотентности не передан или отличается между запросами, запросы считаются разными, и одинаковый результат их выполнения не гарантируется.


Передача ключа идемпотентности

Метод GET

Для метода GET /addPhone ключ идемпотентности передается в параметре запроса Idempotence-Key:

curl 'https://app.jaicp.com/api/calls/campaign/8231.7056.1b131df1/addPhone?phone=79110000000&Idempotence-Key=d5f41bd4'

Методы POST

Все методы POST требуют передачи ключа идемпотентности в заголовке Idempotence-Key:

curl --request POST 'https://app.jaicp.com/api/calls/campaign/8231.7056.1b131df1/addPhones' \
--header 'Content-Type: application/json' \
--header 'Idempotence-Key: d5f41bd4' \
--data-raw '[
    {
        "phone": 79110000000
    }
]'

Пример использования

Предположим, что в результате системного сбоя запрос на добавление номера в обзвон был выполнен дважды. Номер и данные, переданные в payload, в обоих запросах одинаковы.

  • Если запросы были выполнены без ключа идемпотентности, то в очередь обзвона добавится задание на обзвон с уникальным ID, а затем новое задание на обзвон с другим ID.
  • Если с запросами был передан ключ идемпотентности, то дубликат задания на обзвон не будет создан. Второй запрос вернет ID того же задания, которое ранее создал первый запрос.

Ограничения

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

Срок действия ключа идемпотентности — 1 сутки со времени первого использования. По прошествии суток запросы с прежним ключом вновь могут создавать дубликаты.