Версия от 10:16, 22 июля 2025

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

В рамках данной статьи будет рассмотрены способы интеграции управления звонками из внешней системы (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 (объект тот же, что и при работе с REST API Long Polling)

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

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

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

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

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

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

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

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

@@ Строка 39: / Строка 39: @@
 * Платформа Эра отправляет подписавшейся системе события звонков
 * Внешняя система получает события, обрабатывает их, отображает результат пользователю (опционально)
-* При необходимости управления звонком, внешняя система отправляет WebSocket-сообщение через REST API к объекту /uc/calls
+* При необходимости управления звонком, внешняя система отправляет WebSocket-сообщение через REST API к объекту /uc/calls (объект тот же, что и при работе с REST API Long Polling)
 [[Файл:Интеграция звонков через WebSocket.png|центр|безрамки|816x816пкс]]