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

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

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

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

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

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

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

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

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

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

Получение событий с помощью WebSocket

На ресурсе Vendor доступно полное описание WebSocket API, которое включает форматы данных, описание настройки прав и доступные виды запросов.

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

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

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

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

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

• Внешняя система подписывается на события 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-панели и т.д.

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

События интеграции звонка

Событие	Свойства события	Комментарий
invite	invitets / invitedt - timestamp или дата-время начала вызова cid - идентификатор вызова connectionid - идентификатор вызова в формате продуктового слоя fromusername - usrname стороны А (From) fromouter - является ли сторона А внешним абонентом isreferred - является ли звонок переведенным callednum - Набранный номер (To)	Событие поступления вызова (дозвона). Внешняя система создает звонок с идентификатором=cid, и временем начала звонка=tinvitets. Направление звонка определяется параметром fromouter. Пользователю должен быть отображен интерфейс дозвона (входящего или исходящего), а также кнопки управления в зависимости от направления звонка.
dlg_start	eventts - время начала разговора cid - идентификатор вызова anumber - номер стороны А bnumber - номер стороны Б aouter - является ли сторона А внешним абонентом bouter - является ли сторона Б внешним абонентом	Начало диалога, после ответа стороны Б. Внешняя система обновляет данные звонка по его cid. Начинается диалог с абонентом, соответственно можно запустить таймер диалога, а также обновить доступный набор кнопок управления.
dlg_stop	eventts - время завершения разговора cid - идентификатор вызова stoptype - тип завершения звонка stopreason - причина завершения звонка stopside - сторона, завершившая звонок	Завершение диалога одной из сторон. Внешняя система обновляет данные звонка по его cid, а также завершает звонок в интерфейсе пользователя. Таймер звонка останавливается и пропадает, кнопки управления звонком должны быть недоступны и скрыты.
dlg_binding	cid - идентификатор звонка dlgbinding - значение привязки (метки)	К звонку была привязана метка для связи с другой сущностью. Или любое другое действие по изменению состава меток. Внешняя система может ориентироваться на привязку меток к диалогу для построения связей между несколькими звонками в одной цепочке (например, цепочка переводов одного абонента между разными операторами). Если у значения метки есть префикс seance_, то значения этого префикса у одной цепочки вызовов будут соблюдать. Данное событие полезно для улучшения связности звонков во внешней системе и построения статистики.
hold	cid - идентификатор звонка xcallid - идентификатор стороны, установившей hold	Пользователь поставил вызов на удержание. Внешняя система должна скрыть кнопку постановки на удержание и отобразить кнопку возврата вызова с удержания
unhold	cid - идентификатор звонка xcallid - идентификатор стороны, установившей hold	Пользователь снял вызов с удержания. Внешняя система должна скрыть кнопку снятия с удержания и отобразить кнопку постановки на удержание
referring_invite	cid - идентификатор звонка referredside - сторона, инициировавшая перевод new_cid - cid нового звонка new_connid - connectionid нового звонка	Был совершен перевод. Внешняя система может скрыть кнопку завершения перевода, или другие кнопки управления звонком. Для повышения связанности данных, можно сохранить идентификатор следующего звонка в цепочке.
records_moved	cid - идентификатор звонка aisrec - Признак записи средствами медиашлюза в домене стороны А. bisrec - Признак записи средствами медиашлюза в домене стороны Б. areclink - Ключ/ссылка для скачивания записи разговора из хранилища в домене стороны А. breclink - Ключ/ссылка для скачивания записи разговора из хранилища в домене стороны Б.	Запись разговора обработана, перенесена и доступна для загрузки. Процесс работы с записями разговоров описан в следующем пункте статьи.

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

Процесс загрузки записи разговора внешней системой (или пользователем внешней системы) происходит следующим образом:

1. При получении события records_moved внешняя система сохраняет reclink - внутреннюю ссылку на запись разговора
2. При необходимости прослушивания или скачивания записи - внешняя система вызывает один из доступных методов генерации внешней ссылки
3. Платформа Эра генерирует временную публичную ссылку на запись разговора и передает её внешней системе
4. Внешняя система скачивает запись / передает ссылку пользователю для загрузки / активирует плеер для прослушивания

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

• REST API /api/admin/v1/callrecords
• WebSocket callrecord message

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

REST Sandbox

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

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

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

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

Также, полезным инструментом в тестировании REST API будет REST Sandbox, который можно найти в приложении Builder.

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

Пример кастомного типа запросов в 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
}