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
   • GET /api/crmCalls/campaign/{token}/test/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. Получение информации об обзвоне.

   • GET /api/calls/campaign/{token}
   • GET /api/calls/campaign/{token}/status

5. Приостановление, возобновление и остановка обзвона.

   • 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": "79123456789"
    }
]'

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

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

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

• Если запросы были выполнены без ключа идемпотентности:

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

• Если с запросами был передан одинаковый ключ идемпотентности:

  Второй запрос выполнится успешно, но задание на обзвон не будет создано. Второй запрос вернет ID того же задания, которое ранее создал первый запрос.

предупреждение

Используйте разные ключи для обзвонов с одинаковыми номерами. Так вы сможете добавлять одинаковые номера в разные обзвоны и избежать дублирования звонков в одном обзвоне.

Ограничения

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

Ключ идемпотентности распространяется на все проекты и обзвоны аккаунта. Для добавления одинаковых номеров телефона в разные обзвоны необходимо использовать разные ключи.

предупреждение

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