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

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

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

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

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

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

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

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

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

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

Интеграция с помощью 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.

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

Пример кастомного типа запросов в Postman

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

Интеграция с помощью 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.

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

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

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

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

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