Система из коробки включает в себя интеграции с различными провайдерами IP-телефонии. Если нужной именно вам
интеграции не нашлось, вы можете воспользоваться данным API для создания собственной интеграции. Для этого вам нужно
создать пользовательский модуль и реализовать несколько функций в сценариях модуля на языке TypeScript.
Встроенные и пользовательские модули интеграции с IP-телефонией по функционалу принципиально ничем не отличаются.
Вашему модулю будут доступны следующие возможности:
инициация исходящего звонка из системы по нажатию на поле типа Телефон;
всплывающая карточка, сигнализирующая о входящем звонке и отображающая краткую информацию, например, телефон,
имя контакта и имя ответственного за этого клиента пользователя;
открытие карточки элемента, содержащего номер телефона, с которого поступает звонок;
автоматическое создание и сохранение элемента приложения, если звонок был пропущен, а номера нет в базе;
регистрация пропущенных звонков;
сохранение в ленте объекта оповещения о входящем или исходящем звонке. Если разговор состоялся, то к оповещению
прикладывается ссылка на запись звонка; запись можно воспроизвести в интерфейсе системы, а также оставить
комментарий, содержащий, к примеру, краткое резюме звонка;
сопоставление учетных записей пользователей IP-телефонии и пользователей системы для маршрутизации и
корректного отражения информации об операторе, принявшем или осуществившем звонок.
Прежде чем реализовывать модуль интеграции, обратите внимание на следующие ограничения API:
На стороне системы не осуществляется маршрутизация звонка во избежание конфликтов с настройками маршрутизации
на стороне телефонии и на стороне системы. Такую возможность предоставляет практически каждый провайдер: после
того, как звонок маршрутизирован на сотрудника или группу, входящий вызов отображается в системе для указанных
пользователей.
На текущий момент обработка событий телефонии производится путем доставки сообщений на определенную HTTP-ссылку
(Webhook). Если провайдер телефонии не предоставляет возможность указать ссылку для доставки сообщений, то необходимо
создать промежуточный сервис, который преобразует данные провайдера телефонии в запрос на сервер системы.
Для записей звонков сохраняется только ссылка на файл. Обычно провайдеры телефонии сохраняют записи звонков за
вас, и ссылка на запись звонка уже существует, но вам следует обратить внимание на политику хранения файлов на
серверах провайдера телефонии: возможно, провайдер сохраняет записи звонков в течение ограниченного времени.
Для создания модуля интеграции вам необходимо в сценариях пользовательского модуля реализовать следующие функции:
// Проверить соединение с телефонией. Вызывается при нажатии на кнопку «Проверить соединение» на странице модуля// Возвращает статус проверки соединения, который отобразится для пользователя на странице модуляasyncfunctionVoipTestConnection(): Promise<VoipTestConnectionResult> { }
// Обработать запрос от провайдера IP-телефонии. Вызывается когда происходит запрос на вебхук модуля// В параметре “request” содержится информация об HTTP-запросе, в том числе HTTP-заголовки и содержимое тела запроса// Функция возвращает результат обработки запроса, на основании которого система будет показывать уведомления// о входящем звонке, сохранять запись звонка и т. д.asyncfunctionVoipParseWebhookRequest(request: FetchRequest): Promise<VoipWebhookParseResult> { }
// Получить список пользователей со стороны провайдера IP-телефонии// Вызывается при сопоставлении пользователей телефонии с пользователями системы после нажатия кнопки «Настроить» на странице модуля// Возвращает список пользователей провайдера IP-телефонииasyncfunctionVoipGetMembers(): Promise<VoipMember[]> { }
// Сгенерировать исходящий звонок. Данная функция вызывается, когда пользователь системы нажимает на кнопку звонка// в поле типа Телефон элемента приложения. В параметрах “srcPhone” указывается номер звонящего пользователя,// в “dstPhone” — номер, на который нужно позвонитьasyncfunctionVoipGenerateCall(srcPhone: string, dstPhone: string): Promise<void> { }
// Получить ссылку на запись звонка. Функция вызывается, когда пользователь системы проигрывает запись звонка из// ленты элемента приложения. В параметре “callData” содержатся данные, которые были указаны при сохранении// информации о записи звонка из функции “VoipParseWebhookRequest”. Функция должна возвращать ссылку на файлasyncfunctionVoipGetCallLink(callData: any): Promise<string> { }
// Вызывается автоматически при изменении ссылки на вебхук (например, при обновлении токена)// В параметре “webhookUrl” указывается абсолютная ссылка на вебхук модуля интеграции. Функция не обязательна к реализацииasyncfunctionVoipOnWebhookUpdated(webhookUrl: string): Promise<void> { }
После реализации этих функций и сохранения сценария на странице модуля вы найдете новый раздел под названием
«Настройки телефонии». В этом разделе будет указана ссылка на вебхук — при отправке данных на эту ссылку будет
вызываться функция VoipParseWebhookRequest из сценария. В этой функции вы должны обработать запрос и вернуть из
неё экземпляр VoipWebhookParseResult, на основании которого система отобразит уведомления о входящем звонке или
сохранит информацию о записи звонка. Саму ссылку на вебхук вам необходимо указать в настройках вашего провайдера
телефонии. Ссылка обрабатывает HTTP-запросы типа GET и POST. Также в ссылке должен присутствовать обязательный
параметр token.
Рекомендуем вам ознакомиться со статьей справки
«Интеграция с IP-телефонией через пользовательский модуль».
Внутри статьи вы найдете заготовку модуля и пример реального использования API на основе интеграции с IP-телефонией
«Гравител».
Интеграция с IP-телефонией
Система из коробки включает в себя интеграции с различными провайдерами IP-телефонии. Если нужной именно вам интеграции не нашлось, вы можете воспользоваться данным API для создания собственной интеграции. Для этого вам нужно создать пользовательский модуль и реализовать несколько функций в сценариях модуля на языке TypeScript.
Встроенные и пользовательские модули интеграции с IP-телефонией по функционалу принципиально ничем не отличаются. Вашему модулю будут доступны следующие возможности:
Ограничения
Прежде чем реализовывать модуль интеграции, обратите внимание на следующие ограничения API:
Реализация
Для создания модуля интеграции вам необходимо в сценариях пользовательского модуля реализовать следующие функции:
// Проверить соединение с телефонией. Вызывается при нажатии на кнопку «Проверить соединение» на странице модуля // Возвращает статус проверки соединения, который отобразится для пользователя на странице модуля 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-телефонией «Гравител».