Управление звонками через API

Общая информация

В рамках данной статьи будет рассмотрены способы интеграции управления звонками из внешней системы (CRM, SD и т.д.).

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

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

Кроме этих основных функций, также крайне полезно иметь возможность прослушивания и скачивания записи разговора из внешней системы.

В рамках платформы Эра существует три основных подхода к интеграции, позволяющие реализовать описанный функционал:

• Интеграция по WebSocket - внешняя система и платформа обмениваются сообщениями в реальном времени
• Интеграция методом REST API Long Polling - внешняя система периодически запрашивает данные платформы и отправляет команды в одностороннем порядке
• Интеграция с помощью механизма Webhook - каждая из систем вызывает сервисы другой

При этом внешняя система может использовать комбинированный подход, например получая события из WebSocket, и отправляя команды с помощью REST API. Последний вариант с Webhook не является штатным решением, однако может быть реализован при помощи инструментов платформы. Наиболее удобным вариантом является разработка собственных сервисов, обрабатывающих события платформы и перенаправляющих их во внешние системы. Разработке на платформе посвещен отдельный курс.

В рамках данной статьи будут рассмотрены интеграционные возможности WebSocket и Long Polling.

Интеграция с помощью WebSocket

Детальное описание WebSocket API можно найти на ресурсе Vendor.

Интеграция данным способом подразумевает обмен сообщениями между двумя системами.

В рамках платформы существует два подхода к использования WebSocket API:

• Token-API - для интеграции server-server. В рамках обмена сообщениями передаются события по всем пользователям
• User-API - для интеграции client-server. В рамках обмена сообщениями передаются события конкретного пользователя

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

Общий подход интеграции выглядит таким образом:

• Внешняя система подписывается на события callevents
• Платформа Эра отправляет подписавшейся системе события звонков
• Внешняя система получает события, обрабатывает их, отображает результат пользователю (опционально)
• При необходимости управления звонком, внешняя система отправляет WebSocket-сообщение через REST API к объекту /uc/calls

Схема событий звонка

Получение данных и событий звонков

Получение данных осуществляется при помощи подписки (subscr) на события callevents:

[
  "subscribe",
  {
    "qid": 0.105938272,
    "id": "bcdebcde-bcde-bcde-bcde-bcdebcdebcde",
    "events": ["callevents.*"],
    "objects": ["11"],
    "expires": 300
  }
]

Набор объектов (абонентов), по которым будут поступать события зависит от фильтра objects, типа используемого WebSocket API и набора прав учетной записи.

Описание всех событий звонков, их структуры и свойств можно найти на ресурсе Vendor.

Управление звонком

При работе с WebSocket есть два подхода к отправке запросов на управление звонком:

Вызов сервисов