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

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

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

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

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

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

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

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

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

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

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

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

Для реализации этого подхода, используется объект /rest/v1/uc/calls и доступ к нему через REST API.

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

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

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

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

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

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

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

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

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

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

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

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

После подписки, платформа автоматически начнет присылать события, связанные с изменениями звонков - начало и окончание диалога, изменение состояния звонка, информацию о записи разговора и т.д.

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

Внешняя система должна получать и обрабатывать эти события. В зависимости от бизнес-целей интеграции, данные о звонках и их состояниях могут быть сохранены во внешней системе, выведены пользователю в CTI-панели и т.д.

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

Для отправки запросов на управление звонком, внешняя система использует вызовы REST API /rest/v1/uc/calls, так же как в примере с Long Polling. Все данные и идентификаторы для запросов передаются в состваве сообщений WebSocket.

@@ Строка 23: / Строка 23: @@
 Последний вариант с Webhook не является штатным решением, однако может быть реализован при помощи инструментов платформы. Наиболее удобным вариантом является разработка собственных сервисов, обрабатывающих события платформы и перенаправляющих их во внешние системы. Разработке на платформе посвещен [[:Категория:Курс Разработка приложений|отдельный курс]].</blockquote>В рамках данной статьи будут рассмотрены интеграционные возможности WebSocket и Long Polling.
+= Интеграция с помощью Long Polling =
+Данный способ интеграции является односторонним, т.е. внешняя система сама запрашивает текущее состояние звонков с некоторой периодоичностью. Внешняя система обрабатывает овтеты платформы и сохраняет данные.
+Для реализации этого подхода, используется объект '''/rest/v1/uc/calls''' и доступ к нему через REST API.
 = Интеграция с помощью WebSocket =
@@ Строка 39: / Строка 44: @@
 * Платформа Эра отправляет подписавшейся системе события звонков
 * Внешняя система получает события, обрабатывает их, отображает результат пользователю (опционально)
-* При необходимости управления звонком, внешняя система отправляет WebSocket-сообщение через REST API к объекту /uc/calls (объект тот же, что и при работе с REST API Long Polling)
+* При необходимости управления звонком, внешняя система осуществляет вызовы REST API /rest/v1/uc/calls
 [[Файл:Интеграция звонков через WebSocket.png|центр|безрамки|816x816пкс]]
@@ Строка 45: / Строка 50: @@
 === Получение данных и событий звонков ===
-Получение данных осуществляется при помощи подписки (subscr) на события '''callevents:'''<syntaxhighlight lang="json">
+Получение данных осуществляется при помощи подписки ([https://vendor.era-platform.ru/docs/era/latest/api/websocket/user/subscr.html subscr]) на события '''callevents:'''<syntaxhighlight lang="json">
 [
    "subscribe",
@@ Строка 57: / Строка 62: @@
 ]
 </syntaxhighlight>Набор объектов (абонентов), по которым будут поступать события зависит от фильтра objects, типа используемого WebSocket API и набора прав учетной записи.
+После подписки, платформа автоматически начнет присылать события, связанные с изменениями звонков - начало и окончание диалога, изменение состояния звонка, информацию о записи разговора и т.д.
 Описание всех событий звонков, их структуры и свойств можно найти на [https://vendor.era-platform.ru/docs/era/latest/events/event_classes/callevents/index.html ресурсе Vendor].
+Внешняя система должна получать и обрабатывать эти события. В зависимости от бизнес-целей интеграции, данные о звонках и их состояниях могут быть сохранены во внешней системе, выведены пользователю в CTI-панели и т.д.
 === Управление звонком ===
-При работе с WebSocket есть два подхода к отправке запросов на управление звонком:
+Для отправки запросов на управление звонком, внешняя система использует вызовы REST API /rest/v1/uc/calls, так же как в примере с Long Polling. Все данные и идентификаторы для запросов передаются в состваве сообщений WebSocket.
-Вызов сервисов
 [[Категория:Интеграция с внешними системами]]