Перейти к основному содержимому

API для звонков

Aimylogic предоставляет API для звонков — Calls API, чтобы вы могли интегрировать телефонию Aimylogic с любыми внешними системами.

С помощью Calls API вы сможете:

  • запускать обзвоны;
  • добавлять номера в базу;
  • получать отчеты по номерам телефона или задачам в обзвоне.

Начало работы с Calls API​

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

  1. Настроить телефонию.
  2. Создать сценарий обзвона.
  3. Настроить и запустить обзвон.

Методы API​

API предоставляет следующие методы.

  1. Добавление номеров в обзвон.

    • POST https://app.aimylogic.com/api/calls/campaign/{token}/addPhones

  2. Добавление номеров из CRM в обзвон.

    • GET https://app.aimylogic.com/api/crmCalls/campaign/{token}/addPhone
    • POST https://app.aimylogic.com/api/crmCalls/campaign/{token}/addPhone
    • GET https://app.aimylogic.com/api/crmCalls/campaign/{token}/test/addPhone

  3. Отмена созданных заданий на обзвон.

    • POST https://app.aimylogic.com/api/calls/campaign/{token}/callJob/cancel

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

    • POST https://app.aimylogic.com/api/calls/campaign/{token}/control/pause
    • POST https://app.aimylogic.com/api/calls/campaign/{token}/control/resume
    • POST https://app.aimylogic.com/api/calls/campaign/{token}/control/stop

  5. Получение информации об обзвоне.

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

  6. Получение отчетов по ID задания на обзвон или по номеру телефона.

    • POST https://app.aimylogic.com/api/calls/campaign/{token}/callJob/getReport
    • POST https://app.aimylogic.com/api/calls/campaign/{token}/callAttempt/getReport
подсказка
Подробное описание Calls API: методы, параметры запроса, форматы ответа, примеры, возвращаемые ошибки

Токен Calls API​

Запросы методов Calls API должны содержать {token} — уникальный идентификатор (токен), который позволяет получить доступ к API. Для каждого нового обзвона из CRM создается уникальный токен.

Вы можете скопировать его на странице обзвона:

  1. Перейдите на страницу Обзвоны.
  2. Нажмите Создать в секции Обзвон из CRM. Вы попадете на страницу настроек обзвона.
  3. В секции Интеграция нажмите Получить токен → Скопировать токен:

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

Клиентские приложения могут генерировать и передавать в Calls API ключ идемпотентности.

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

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

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

Метод GET

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

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

Методы POST

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

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

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

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

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

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

Ограничения​

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

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