Версия от 11:19, 28 июля 2025

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

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

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

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

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

Основной подход к интеграции внешних систем - комбинирование WebSocket и REST API.

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

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

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

Получение событий с помощью 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.

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

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

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

Примеры авторизации и выполнения REST API запросов можно посмотреть в данной статье.

Объект uc/calls поддерживает следующий набор операций:

HTTP verb	Endpoint	Описание
`GET`	`/rest/v1/uc/calls`	Получение списка звонков (GET)
`POST`	`/rest/v1/uc/calls`	Инициация нового звонка (POST)
`INVITE`	`/rest/v1/uc/calls`	Инициация нового звонка (INVITE)
`INVITEBYIVR`	`/rest/v1/uc/calls`	Инициация нового звонка с обслуживанием в IVR (INVITEBYIVR)
`LOOKUP`	`/rest/v1/uc/calls`	Поиск идентификатора звонка (LOOKUP)
`TRANSCRIBE`	`/rest/v1/uc/calls`	Поиск идентификатора звонка (LOOKUP)
`GET`	`/rest/v1/uc/calls/<id>`	Получение информации о звонке (GET)
`REFER`	`/rest/v1/uc/calls/<id>`	Перевод звонка на номер (REFER)
`REFERREPLACES`	`/rest/v1/uc/calls/<id>`	Перевод звонка с подменой (REFERREPLACES)
`SWITCHCONF`	`/rest/v1/uc/calls/<id>`	Преобразование звонка в конференцию (SWITCHCONF)
`REFERCONF`	`/rest/v1/uc/calls/<id>`	Перевод звонка в конференцию (REFERCONF)
`NOTIFY`	`/rest/v1/uc/calls/<id>`	Отправка события управления устройством (NOTIFY)
`SEND_DTMF`	`/rest/v1/uc/calls/<id>`	Отправка DTMF сигнала в плечо (SEND_DTMF)
`SETUP_ASR`	`/rest/v1/uc/calls/<id>`	Запуск/остановка стенографирования речи одной из сторон (SETUP_ASR)
`SETUP_RECORD`	`/rest/v1/uc/calls/<id>`	Включение/выключение (добавление/удаление) канала записи диалога, а также управление паузой основной записи (SETUP_RECORD)
`SETUP_BINDINGS`	`/rest/v1/uc/calls/<id>`	Управление метками диалога (SETUP_BINDINGS)
`STOP_HOLD_MELODY`	`/rest/v1/uc/calls/<id>`	Остановка мелодии ожидания (STOP_HOLD_MELODY)
`DELETE`	`/rest/v1/uc/calls/<id>`	Завершение звонка (DELETE)

Получение данных о звонках

Для получения информации о звонках используется метод GET.

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

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

Пример JSON звонка:

{
  "acallid": "3113017065@192.168.0.149",
  "callids": [
    "rB2-002-484FD3-01-3113017065@192.168.0.149",
    "3113017065@192.168.0.149"
  ],
  "dialogid": "rDlg-002-484FD3",
  "esgdlg": "",
  "esgcallid": "",
  "inviteid": "357924f1-0623-b685-c105-b80000000002",
  "legs": [
    {
      "callid": "3113017065@192.168.0.149",
      "expirets": "undefined",
      "localuri": "<sip:sip3@test.rootdomain.ru>",
      "remoteuri": "<sip:sip2@test.rootdomain.ru>",
      "side": "a"
    },
    {
      "callid": "rB2-002-484FD3-01-3113017065@192.168.0.149",
      "expirets": 30000,
      "localuri": "<sip:12@test.rootdomain.ru>",
      "remoteuri": "<sip:sip3@test.rootdomain.ru>",
      "side": "b"
    }
  ],
  "localuri": "<sip:sip3@test.rootdomain.ru>",
  "opts": {
    "referred-by": "<sip:sip1@test.rootdomain.ru>"
  },
  "remoteuri": "<sip:sip2@test.rootdomain.ru>",
  "site": "SITE1",
  "startts": 1571747612067,
  "status": "forking",
  "uris": [
    "<sip:12@test.rootdomain.ru>",
    "<sip:sip3@test.rootdomain.ru>",
    "<sip:sip3@test.rootdomain.ru>",
    "<sip:sip2@test.rootdomain.ru>"
  ]
}

Описание всех свойств JSON можно посмотреть в описании методов на ресурсе Vendor.

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

Объект /rest/v1/uc/calls предоставляет широкий набор методов для управления вызовом.

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

Далее, приведем сокращенную версию таблицы выше, с комментариями по основным кейсам управления звонком:

HTTP verb	Endpoint	Описание
`POST`	`/rest/v1/uc/calls`	Инициация нового звонка (POST). Используется для инициирования нового звонка между оператором и абонентом
`INVITEBYIVR`	`/rest/v1/uc/calls`	Инициация нового звонка с обслуживанием в IVR (INVITEBYIVR). Используется для инициирования нового звонка между IVR и абонентом
`REFER`	`/rest/v1/uc/calls/<id>`	Перевод звонка на номер (REFER). Осуществляет "слепой" перевод на указанный номер.
`SWITCHCONF`	`/rest/v1/uc/calls/<id>`	Преобразование звонка в конференцию (SWITCHCONF). Создает новую конференцию из диалога
`REFERCONF`	`/rest/v1/uc/calls/<id>`	Перевод звонка в конференцию (REFERCONF). Переводит абонента в указанную конференцию
`NOTIFY`	`/rest/v1/uc/calls/<id>`	Отправка события управления устройством (NOTIFY). Используется для выполнения операций над звонком, выполняемых с SIP-устройства - поднятие трубки, удержание и т.д. Поддерживаемый функционал напрямую зависит от производителя и модели конечного устройства.
`SEND_DTMF`	`/rest/v1/uc/calls/<id>`	Отправка DTMF сигнала в плечо (SEND_DTMF). Позволяет отправлять цифры числового набора
`SETUP_RECORD`	`/rest/v1/uc/calls/<id>`	Включение/выключение (добавление/удаление) канала записи диалога, а также управление паузой основной записи (SETUP_RECORD)
`SETUP_BINDINGS`	`/rest/v1/uc/calls/<id>`	Управление метками диалога (SETUP_BINDINGS)
`STOP_HOLD_MELODY`	`/rest/v1/uc/calls/<id>`	Остановка мелодии ожидания (STOP_HOLD_MELODY)
`DELETE`	`/rest/v1/uc/calls/<id>`	Завершение звонка (DELETE)

Более полную информацию по доступным методам управления, можно изучить на ресурсе Vendor.

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

POST /rest/v1/uc/calls HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "from": "14",
  "to": "16",

  "mode": "number",
  "callerid": "100",
  "callername": "callmanager",
  "calltimeout": 30,
  "use_intercom": true,
  "binding": "sample_binding",
  "response_mode": 5
}

Доступ к записям разговоров

Прослушивание записей средствами платформы (через API или из приложений платформы) возможно только в том случае, если запись производилась в локальном режиме.

Доступ к записям определяется ролевой политикой.

Для доступа к файлу всегда формируется временная ссылка со сложным уникальным именем, доступная публично в течение 5 минут.

https://vendor.era-platform.ru/docs/era/latest/api/api/admin/callrecords.html

@@ Строка 15: / Строка 15: @@
 Кроме этих основных функций, также крайне полезно иметь возможность прослушивания и скачивания записи разговора из внешней системы.
-В рамках платформы Эра существует три основных подхода к интеграции, позволяющие реализовать описанный функционал:
+Основной подход к интеграции внешних систем - комбинирование WebSocket и REST API.
-* Интеграция по WebSocket - внешняя система и платформа обмениваются сообщениями в реальном времени
+Платформа эра отправляет внешней системе события с помощью WebSocket. Внешняя же система обрабатывает события, и направляет запросы через WebSocket или напрямую в REST API.
-* Интеграция методом REST API Long Polling - внешняя система периодически запрашивает данные платформы и отправляет команды в одностороннем порядке
-* Интеграция с помощью механизма Webhook - каждая из систем вызывает сервисы другой
-<blockquote>При этом внешняя система может использовать комбинированный подход, например получая события из WebSocket, и отправляя команды с помощью REST API.
-Последний вариант с Webhook не является штатным решением, однако может быть реализован при помощи инструментов платформы. Наиболее удобным вариантом является разработка собственных сервисов, обрабатывающих события платформы и перенаправляющих их во внешние системы. Разработке на платформе посвещен [[:Категория:Курс Разработка приложений|отдельный курс]].</blockquote>В рамках данной статьи будут рассмотрены интеграционные возможности WebSocket и Long Polling.
+Также, возможна интеграция с помощью механизма Webhook - каждая из систем может вызывать сервисы другой, однако такой вариант интеграции является проектным решением и должен реализовываться вручную.
+В рамках данной статьи будут рассмотрены базовые инструменты интеграции, для реализации проектных решений рекомендуется обратиться к материалам [[:Категория:Курс Разработка приложений|курса по разработке приложений]], в частности к [[Разработка сервисов|разработке сервисов]].
+= Получение событий с помощью WebSocket =
+ Детальное описание WebSocket API можно найти на [https://vendor.era-platform.ru/docs/era/latest/api/websocket/websocket_api_concepts.html ресурсе Vendor].
+Интеграция данным способом подразумевает обмен сообщениями между двумя системами.
+В рамках платформы существует два подхода к использования WebSocket API:
+* Token-API - для интеграции server-server. В рамках обмена сообщениями передаются события по всем пользователям
+* User-API - для интеграции client-server. В рамках обмена сообщениями передаются события конкретного пользователя
+Набор доступных API также отличается, однако методы и события работы со звонками доступны везде.
+Общий подход интеграции выглядит таким образом:
+* Внешняя система подписывается на события callevents
+* Платформа Эра отправляет подписавшейся системе события звонков
+* Внешняя система получает события, обрабатывает их, отображает результат пользователю (опционально)
+* При необходимости управления звонком, внешняя система осуществляет вызовы REST API /rest/v1/uc/calls
+[[Файл:Интеграция звонков через WebSocket.png|центр|безрамки|816x816пкс]]
+[[Файл:CallEvents schema.svg|мини|Схема событий звонка]]
+=== Получение данных и событий звонков ===
+Получение данных осуществляется при помощи подписки ([https://vendor.era-platform.ru/docs/era/latest/api/websocket/user/subscr.html subscr]) на события '''callevents:'''<syntaxhighlight lang="json">
+[
+  "subscribe",
+  {
+    "qid": 0.105938272,
+    "id": "bcdebcde-bcde-bcde-bcde-bcdebcdebcde",
+    "events": ["callevents.*"],
+    "objects": ["11"],
+    "expires": 300
+  }
+]
+</syntaxhighlight>Набор объектов (абонентов), по которым будут поступать события зависит от фильтра objects, типа используемого WebSocket API и набора прав учетной записи.
+После подписки, платформа автоматически начнет присылать события, связанные с изменениями звонков - начало и окончание диалога, изменение состояния звонка, информацию о записи разговора и т.д.
+Описание всех событий звонков, их структуры и свойств можно найти на [https://vendor.era-platform.ru/docs/era/latest/events/event_classes/callevents/index.html ресурсе Vendor].
+Внешняя система должна получать и обрабатывать эти события. В зависимости от бизнес-целей интеграции, данные о звонках и их состояниях могут быть сохранены во внешней системе, выведены пользователю в CTI-панели и т.д.
+=== Управление звонком ===
+Для отправки запросов на управление звонком, внешняя система использует вызовы REST API /rest/v1/uc/calls, так же как в примере с Long Polling. Все данные и идентификаторы для запросов передаются в состваве сообщений WebSocket.
 = Интеграция с помощью Long Polling =
@@ Строка 237: / Строка 279: @@
 }
 </syntaxhighlight>
-= Интеграция с помощью WebSocket =
- Детальное описание WebSocket API можно найти на [https://vendor.era-platform.ru/docs/era/latest/api/websocket/websocket_api_concepts.html ресурсе Vendor].
-Интеграция данным способом подразумевает обмен сообщениями между двумя системами.
-В рамках платформы существует два подхода к использования WebSocket API:
-* Token-API - для интеграции server-server. В рамках обмена сообщениями передаются события по всем пользователям
-* User-API - для интеграции client-server. В рамках обмена сообщениями передаются события конкретного пользователя
-Набор доступных API также отличается, однако методы и события работы со звонками доступны везде.
-Общий подход интеграции выглядит таким образом:
-* Внешняя система подписывается на события callevents
-* Платформа Эра отправляет подписавшейся системе события звонков
-* Внешняя система получает события, обрабатывает их, отображает результат пользователю (опционально)
-* При необходимости управления звонком, внешняя система осуществляет вызовы REST API /rest/v1/uc/calls
-[[Файл:Интеграция звонков через WebSocket.png|центр|безрамки|816x816пкс]]
-[[Файл:CallEvents schema.svg|мини|Схема событий звонка]]
-=== Получение данных и событий звонков ===
-Получение данных осуществляется при помощи подписки ([https://vendor.era-platform.ru/docs/era/latest/api/websocket/user/subscr.html subscr]) на события '''callevents:'''<syntaxhighlight lang="json">
-[
-  "subscribe",
-  {
-    "qid": 0.105938272,
-    "id": "bcdebcde-bcde-bcde-bcde-bcdebcdebcde",
-    "events": ["callevents.*"],
-    "objects": ["11"],
-    "expires": 300
-  }
-]
-</syntaxhighlight>Набор объектов (абонентов), по которым будут поступать события зависит от фильтра objects, типа используемого WebSocket API и набора прав учетной записи.
-После подписки, платформа автоматически начнет присылать события, связанные с изменениями звонков - начало и окончание диалога, изменение состояния звонка, информацию о записи разговора и т.д.
-Описание всех событий звонков, их структуры и свойств можно найти на [https://vendor.era-platform.ru/docs/era/latest/events/event_classes/callevents/index.html ресурсе Vendor].
-Внешняя система должна получать и обрабатывать эти события. В зависимости от бизнес-целей интеграции, данные о звонках и их состояниях могут быть сохранены во внешней системе, выведены пользователю в CTI-панели и т.д.
-=== Управление звонком ===
-Для отправки запросов на управление звонком, внешняя система использует вызовы REST API /rest/v1/uc/calls, так же как в примере с Long Polling. Все данные и идентификаторы для запросов передаются в состваве сообщений WebSocket.
 = Доступ к записям разговоров =