Версия от 12:00, 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 - События телефонии

ccsevents - События контакт центра (Calls-Connections-Seances)

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

Внешняя система подписывается на события callevents и/или ccsevents
Платформа Эра отправляет подписавшейся системе события звонков
Внешняя система получает события, обрабатывает их, отображает результат пользователю (опционально)
При необходимости управления звонком, внешняя система осуществляет вызовы 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-панели и т.д.

Получение записей разговоров

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

Данный класс событий является более верхнеуровневым и предоставляет информацию об обработке звонков в рамках контакт-центра.

При завершении записи разговора и её микширования, платформой будет отправлено событие connection_set_record_info.

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

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

Для получения временной внешней ссылки можно использоваться одним из следующих методов:

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

Работа со звонками через REST API

Для работы со звонками через REST используется объект /rest/v1/uc/calls.

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

Кроме прямых HTTP-вызовов API, можно также пользоваться возможностью отправки REST-запросов через WebSocket.

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

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

Объект /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
}

@@ Строка 85: / Строка 85: @@
 Логика интеграции должна строиться таким образом, что внешняя система хранит только ключ получения записи, и при необходимости каждый раз запрашивает временную ссылку на запись разговора.
-=== Управление звонком ===
-Для отправки запросов на управление звонком, внешняя система использует вызовы REST API /rest/v1/uc/calls, так же как в примере с Long Polling. Все данные и идентификаторы для запросов передаются в состваве сообщений WebSocket.
 = Работа со звонками через REST API =
@@ Строка 94: / Строка 91: @@
 Примеры авторизации и выполнения REST API запросов можно посмотреть в [[Примеры API запросов|данной статье]].
-Объект uc/calls поддерживает [https://vendor.era-platform.ru/docs/era/latest/api/rest/v1/uc/calls.html следующий набор операций]:
+Кроме прямых HTTP-вызовов API, можно также пользоваться возможностью [https://vendor.era-platform.ru/docs/era/latest/api/websocket/user/rest.html отправки REST-запросов через WebSocket].
-{| class="wikitable"
-!HTTP verb
-!Endpoint
-!Описание
-|-
-|<code>GET</code>
-|<code>/rest/v1/uc/calls</code>
-|Получение списка звонков (GET)
-|-
-|<code>POST</code>
-|<code>/rest/v1/uc/calls</code>
-|Инициация нового звонка (POST)
-|-
-|<code>INVITE</code>
-|<code>/rest/v1/uc/calls</code>
-|Инициация нового звонка (INVITE)
-|-
-|<code>INVITEBYIVR</code>
-|<code>/rest/v1/uc/calls</code>
-|Инициация нового звонка с обслуживанием в IVR (INVITEBYIVR)
-|-
-|<code>LOOKUP</code>
-|<code>/rest/v1/uc/calls</code>
-|Поиск идентификатора звонка (LOOKUP)
-|-
-|<code>TRANSCRIBE</code>
-|<code>/rest/v1/uc/calls</code>
-|Поиск идентификатора звонка (LOOKUP)
-|-
-|<code>GET</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Получение информации о звонке (GET)
-|-
-|<code>REFER</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Перевод звонка на номер (REFER)
-|-
-|<code>REFERREPLACES</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Перевод звонка с подменой (REFERREPLACES)
-|-
-|<code>SWITCHCONF</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Преобразование звонка в конференцию (SWITCHCONF)
-|-
-|<code>REFERCONF</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Перевод звонка в конференцию (REFERCONF)
-|-
-|<code>NOTIFY</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Отправка события управления устройством (NOTIFY)
-|-
-|<code>SEND_DTMF</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Отправка DTMF сигнала в плечо (SEND_DTMF)
-|-
-|<code>SETUP_ASR</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Запуск/остановка стенографирования речи одной из сторон (SETUP_ASR)
-|-
-|<code>SETUP_RECORD</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Включение/выключение (добавление/удаление) канала записи диалога, а также управление паузой основной записи (SETUP_RECORD)
-|-
-|<code>SETUP_BINDINGS</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Управление метками диалога (SETUP_BINDINGS)
-|-
-|<code>STOP_HOLD_MELODY</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Остановка мелодии ожидания (STOP_HOLD_MELODY)
-|-
-|<code>DELETE</code>
-|<code>/rest/v1/uc/calls/<id></code>
-|Завершение звонка (DELETE)
-|}
+Объект uc/calls поддерживает [https://vendor.era-platform.ru/docs/era/latest/api/rest/v1/uc/calls.html следующий набор операций].
 === Управление звонком ===
 [[Файл:Пример кастомного типа запросов в Postman.png|мини|Пример кастомного типа запросов в Postman]]