Система из коробки включает в себя интеграции с различными провайдерами IP-телефонии. Если нужной именно вам интеграции не нашлось, вы можете воспользоваться данным API для создания собственной интеграции. Для этого вам нужно создать пользовательский модуль и реализовать несколько функций в сценариях модуля на языке TypeScript.

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

• инициация исходящего звонка из системы по нажатию на поле типа Телефон;
• всплывающая карточка, сигнализирующая о входящем звонке и отображающая краткую информацию, например, телефон, имя контакта и имя ответственного за этого клиента пользователя;
• открытие карточки элемента, содержащего номер телефона, с которого поступает звонок;
• автоматическое создание и сохранение элемента приложения, если звонок был пропущен, а номера нет в базе;
• регистрация пропущенных звонков;
• сохранение в ленте объекта оповещения о входящем или исходящем звонке. Если разговор состоялся, то к оповещению прикладывается ссылка на запись звонка; запись можно воспроизвести в интерфейсе системы, а также оставить комментарий, содержащий, к примеру, краткое резюме звонка;
• сопоставление учетных записей пользователей IP-телефонии и пользователей системы для маршрутизации и корректного отражения информации об операторе, принявшем или осуществившем звонок.

Ограничения

Прежде чем реализовывать модуль интеграции, обратите внимание на следующие ограничения API:

1. На стороне системы не осуществляется маршрутизация звонка во избежание конфликтов с настройками маршрутизации на стороне телефонии и на стороне системы. Такую возможность предоставляет практически каждый провайдер: после того, как звонок маршрутизирован на сотрудника или группу, входящий вызов отображается в системе для указанных пользователей.
2. На текущий момент обработка событий телефонии производится путем доставки сообщений на определенную HTTP-ссылку (Webhook). Если провайдер телефонии не предоставляет возможность указать ссылку для доставки сообщений, то необходимо создать промежуточный сервис, который преобразует данные провайдера телефонии в запрос на сервер системы.
3. Для записей звонков сохраняется только ссылка на файл. Обычно провайдеры телефонии сохраняют записи звонков за вас, и ссылка на запись звонка уже существует, но вам следует обратить внимание на политику хранения файлов на серверах провайдера телефонии: возможно, провайдер сохраняет записи звонков в течение ограниченного времени.

Реализация

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

// Проверить соединение с телефонией. Вызывается при нажатии на кнопку Проверить соединение на странице модуля
// Возвращает статус проверки соединения, который отобразится для пользователя на странице модуля
async function VoipTestConnection(): Promise<VoipTestConnectionResult> { }

// Обработать запрос от провайдера IP-телефонии. Вызывается когда происходит запрос на вебхук модуля
// В параметре “request” содержится информация об HTTP-запросе, в том числе HTTP-заголовки и содержимое тела запроса
// Функция возвращает результат обработки запроса, на основании которого система будет показывать уведомления
// о входящем звонке, сохранять запись звонка и т. д.
async function VoipParseWebhookRequest(request: FetchRequest): Promise<VoipWebhookParseResult> { }

// Получить список пользователей со стороны провайдера IP-телефонии
// Вызывается при сопоставлении пользователей телефонии с пользователями системы после нажатия кнопки Настроить на странице модуля
// Возвращает список пользователей провайдера IP-телефонии
async function VoipGetMembers(): Promise<VoipMember[]> { }

// Сгенерировать исходящий звонок. Данная функция вызывается, когда пользователь системы нажимает на кнопку звонка
// в поле типа Телефон элемента приложения. В параметрах “srcPhone” указывается номер звонящего пользователя,
// в “dstPhone” — номер, на который нужно позвонить
async function VoipGenerateCall(srcPhone: string, dstPhone: string): Promise<void> { }

// Получить ссылку на запись звонка. Функция вызывается, когда пользователь системы проигрывает запись звонка из
// ленты элемента приложения. В параметре “callData” содержатся данные, которые были указаны при сохранении
// информации о записи звонка из функции “VoipParseWebhookRequest”. Функция должна возвращать ссылку на файл
async function VoipGetCallLink(callData: any): Promise<string> { }

// Вызывается автоматически при изменении ссылки на вебхук (например, при обновлении токена)
// В параметре webhookUrl указывается абсолютная ссылка на вебхук модуля интеграции. Функция не обязательна к реализации
async function VoipOnWebhookUpdated(webhookUrl: string): Promise<void> { }

После реализации этих функций и сохранения сценария на странице модуля вы найдете новый раздел под названием Настройки телефонии. В этом разделе будет указана ссылка на вебхук — при отправке данных на эту ссылку будет вызываться функция VoipParseWebhookRequest из сценария. В этой функции вы должны обработать запрос и вернуть из неё экземпляр VoipWebhookParseResult, на основании которого система отобразит уведомления о входящем звонке или сохранит информацию о записи звонка. Саму ссылку на вебхук вам необходимо указать в настройках вашего провайдера телефонии. Ссылка обрабатывает HTTP-запросы типа GET и POST. Также в ссылке должен присутствовать обязательный параметр token.

Рекомендуем вам ознакомиться со статьей справки «Интеграция с IP-телефонией через пользовательский модуль». Внутри статьи вы найдете заготовку модуля и пример реального использования API на основе интеграции с IP-телефонией Гравител.