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. Получение информации об обзвоне.

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

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

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

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

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

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

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

Ограничения

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

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

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

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