Телефония¶
Для интеграции Мегапалана c телефонией, мы предусмотрели различные методы и способы, о которых сейчас расскажем :)
HTTP API¶
Для телефонии реализовано HTTP API в 3 версии.
Существуют методы создания сущности звонка и изменения её, переводя по статусам calling, talking, finished.
При создании звонка и прохождения его по статусам, в Мегаплане на стороне клиента эти события отлавливает встроенный виджет телефонии,
показывая клиента, найденного по номеру, и связывает звонок с делом - коммуникацией на карточке клиента, по завершении которой
отображается проигрыватель ссылки на запись разговора, если была такая ссылка в callInfo.
Более подробно про виджет телефонии.
Также есть CallRoute, с помощью которого можно получить ответственного менеджера по номеру клиента.
CallUserConfig используется для создания конфига пользователя в Мегаплане, которому доступна телефония и его
авторизационные данные необходимые для АТС, также присутствует внутренний номер для быстрого поиска и отдачи его в CallRoute.
systemSetting используется для сохранения общей информации для всех пользователей, такой как сервер АТС,
авторизационный ключ, возможно, путь для скачивания записей разговоров
Более подробная информация по HTTP методам и структуре сущностей находится в Документации APIv3.
Кроме того, внутри каждого аккаунта присутствует документация для текущей версии аккаунта, URL-путь: /dev/api и /dev/api3
Виджет телефонии¶
Виджет телефонии находится в нижнем левом углу (трубка на нижней панели). Трубка своим цветом указывает на состояние телефонии.
Режим простоя - это недавние звонки, при ненадобности виджет можно свернуть вниз. Снизу управляющие кнопки, показ которых зависит от возможностей интеграции с телефонией.
Внешний вид в режиме ожидания - «недавние звонки»:
Переключение режимов и внешний вид зависят от возможностей интеграции.
Различные режимы представлены на картинках ниже:
Входящий звонок, исходящий звонок и режим разговора:
Отключение микрофона, режим «не беспокоить» и перевод звонка:
Режим дополнительные настройки:
Особенности:
Виджет изначально рассчитан на работу с телефонией по WebSocket. Поэтому в нём реализована работа через localStorage со всеми вкладками одного хоста.
Необходимость подключения по webSocket есть только в одной master вкладке, наша SDK для телефонии предусматривает это.
Внутри SDK запрос на подключение и, соответственно, все запросы связанные с сервером АТС будут происходить только в master вкладке, все остальные события передаются через localStorage второстепенным (slave) вкладкам и обратно
Slave вкладки могут подписаться на событие updateCallInfo, это событие происходит при любом изменении CallInfo во всех вкладках.
P.S. Master вкладка необязательно та вкладка, в которой фокус окна. Вкладка выбирается автоматически и если она не перезагружается, то и соединение не разрывается.
Виджет отображает название клиента, с которым идет разговор, или список найденных клиентов с возможностью выбора или смены на другого.
Также, виджет сам выбирает первого из найденных клиентов, если нет других действий менеджера.
После выбора клиента запускается механизм работы с коммуникациями. При наличии коммуникации и связи со звонком,
интерфейс предлагает менеджеру указать результат коммуникации и завершить её с записью в журнал клиента.
При наличии recordUrl в callInfo, в журнале отображается проигрыватель записи по внешней ссылке.
P.S. Через пол часа после звонка, Мегаплан попробует скачать запись по указанной ссылке, и если ссылка доступна для скачивания,
то запись разговора прикладывается в виде файла в коммуникацию, и в дальнейшем проигрывание идёт напрямую из Мегаплана.
Доступ к записи имеют те сотрудники, которые обладают правами чтения на клиента, с которым была коммуникация.
Механизм коммуникаций с типом «звонок» в Мегаплане¶
При интеграции с телефонией в Мегаплане идёт работа с коммуникациями типа звонок.
Для интеграции существуют системные настройки телефонии: типы звонков, используемые при тех или иных событиях, и настройки набора номера.
Эти настройки глобальны для аккаунта Мегаплана, то есть при подключении другой интеграции, будут использоваться те же настройки.
При звонке, система осуществляет поиск клиента или сотрудника по номеру телефона, если это не задано изначально через callInfo или при исходящем с карточки клиента.
Если клиент не найден, то виджет телефонии предлагает создать нового клиента.
После установки клиента, система смотрит на текущие коммуникации по клиенту с типом «звонок». При наличии подходящих коммуникаций выбирается самая ранняя по времени.
Подходящая коммуникация - это дело с типом «звонок» без времени или на сегодняшний день с конкретным клиентом.
В интерфейсе это отмечается переключением коммуникации в режим завершения и предлагается пользователю ввести результат звонка.
В случае, если подходящих коммуникаций нет, система создает новую с названием «входящий звонок» или «исходящий звонок». Созданная коммуникация уже жестко связана с текущим звонком.
Если пользователь указывает результат и завершает коммуникацию в процессе звонка или в течение двух минут после завершения звонка, то коммуникация считается связанной со звонком.
Если пользователь не завершает коммуникацию, то через 2-3 минуты после завершения разговора, система завершит коммуникацию, если звонок был связан с ней.
Если нет, то создаст новую с названием типа звонка и завершит с результатом «автоматически завершенная коммуникация» с привязкой записи разговора.
Через, примерно, полчаса Мегаплан попробует скачать запись разговора по ссылке и приложить файл к коммуникации.
javascript SDK для работы с телефонией¶
mpCallJsSDK представляет собой объект с набором функций и событий для работы с подсистемой телефонии в Мегаплане.
Работа с SDK доступна из javascript кода в виджетах приложений. Получить объект SDK можно следующим образом:
a9n.callSDK().then(function(mpCallJsSdk){ //mpCallJsSdk - SDK для взаимодействия с Мегапланом в разрезе телефонии });В SDK есть обязательный метод (setCapabilities), который должна вызывать любая интеграция с простановкой возможностей интеграции, в зависимости от выставленных параметров (true - наличие соответствующей возможности, false - отсутствие), в виджете будет доступен тот или иной функционал:
mpCallJsSdk.setCapabilities({ /* WEBRTC, если true - позволяет указать Мегаплану, что разговор будет идти в браузере. */ 'WEBTALK': false, /* если true - в виджете будет кнопка ответить при входящем звонке, а интеграция должна будет подписываться на событие answer и выполнять необходимые действия с АТС */ 'ANSWER': false, /* если true - в виджете будет кнопка сбросить входящий и завершить текущий звонок */ 'END_TALK': false, /* если true - в виджете будет стрелка перевода звонка (только безусловный перевод) */ 'TRANSFER': false, /* если true - в виджете будет кнопка перехода в режим не беспокоить */ 'AWAY_MODE': false, /* если true - в виджете будет кнопка отключения микрофона */ 'MUTE': false, /* если true - в виджете будет кнопка сброса состояния (когда нет возможности завершить вызов, но нужно предоставить возможность скрыть виджет телефонии и сбросить его состояние */ 'CLEAR_STATE': false, });В SDK используется объект CallInfo, как и в HTTP API, Основные поля:
Параметр
Тип
Описание
id
string
Идентификатор звонка в Мегаплане
providerId
any
Идентификатор звонка на стороне провайдера
type
string
Тип звонка, возможные варианты: unknown, in, out, miss, fail
state
string
Статус звонка, возможные варианты: unknown, calling, talking, finished, failed
fromPhone
string
Номер телефона абонента А (кто звонит)
toPhone
string
Номер телефона абонента Б (кому звонят)
timeFrom
DateTime
Время начала звонка
timeTo
DateTime
Время завершения звонка
recordLinks
string[]
Массив ссылок на запись разговора (разговоров, в случае нескольких сессий записи)
type = miss - пропущенный входящий, а type = fail - не отвеченный исходящий, state у таких звонков должен быть finished.
state = failed - используется при звонках, когда, например, нет денег у абонента и он не смог осуществить звонок, или не было связи с АТС.
type и state в режиме unknown - это начальное состояние виджета, когда ничего не происходит.
События SDK, подключение обработчика происходит через метод on (mpCallJsSdk.on(eventName, callback):
connect - Событие для главной вкладки, сообщает о необходимости подключиться к АТС или определить наличие доступа к работе с АТС текущего пользователя. После обработки события, необходимо вызвать mpCallJsSdk.connected() или mpCallJsSdk.disconnected() в зависимости от того, может ли пользователь работать с телефонией. Виджет телефонии перейдёт в рабочее или отключённое состояние соответственно.
disconnect - событие отключения телефонии, происходит при отключении от телефонии пользователя в настройках виджета телефонии или администратором в настройках пользователей телефонии, а также при закрытии главной вкладки.
changeDndMode - событие нажатия на кнопку «не беспокоить» в виджете телефонии.
transfer - событие перевода звонка, на вход передается объект CallInfo, в котором toPhone - это номер телефона, на который пользователь переводит звонок.
mute - событие нажатия на кнопку выключения микрофона.
unMute - событие нажатия на кнопку включения микрофона.
answer - событие нажатия на кнопку ответа.
call - событие нажатия на номер телефона (инициация звонка), на вход передается объект CallInfo, в котором toPhone - это номер телефона, кому пользователь звонит.
dtmf - донабор номера через номеронабиратель, на вход передается набранный номер.
endCall - событие нажатия на кнопку завершения разговора или сброса входящего.
updateCallInfo - событие изменения текущей CallInfo - отрабатывает во всех вкладках, на вход передается объект CallInfo.
- !Внимание
Событие connected вызывается в master вкладке при открытии slave вкладки, для проверки того, что соединение в данный момент существует и в ответ необходимо вызывать connected.
Методы SDK:
setCapabilities - установка возможностей интеграции, вызывать надо после инициализации виджета и подписки на события.
getServerConfig - отдает серверные настройки, которые устанавливаются по HTTP APIv3 systemSetting (scope для телефонии callServerConfig, id - любое название настройки). и/или в настройках API телефонии.
getUserConfig - отдает настройки текущего пользователя, которые устанавливаются по HTTP APIv3 callUserConfig и/или в настройках пользователей телефонии (вкладка «пользователи» в настройках API телефонии).
getUserInternalNumberConfig - отдает внутренний номер пользователя, указанный в настройках пользователей телефонии (internalNumber в сущности CallUserConfig).
connected - устанавливает виджет в режим работы (зелёная трубка и активный виджет).
disconnected - устанавливает виджет в отключенное состояние.
calling - отдает виджету состояние ожидания соединения при наборе номера или входящем звонке, на вход передается объект CallInfo.
talking - отдает виджету состояние установленной связи, на вход передается объект CallInfo.
badCall - отдает виджету состояние неуспешного звонка, на вход передается CallInfo (или используется текущий объект), например, не дозвонились, нет связи с АТС или недостаточно средств.
finished - отдает виджету состояние завершенного звонка, на вход передается объект CallInfo (или используется текущий объект)
getCurrentCallInfo - отдает текущий объект CallInfo.
showMicAccess - при работе через webRTC , можно встроенными средствами Мегаплана показать промо - уведомление с картинкой о необходимости включить микрофон в браузере.
hideMicAccess - закрытие промо - уведомления при получении доступа к микрофону.
Показать / скрыть базовый пример работы с mpCallJsSdk
a9n.callSDK().then(function(mpCallJsSdk){ console.log('CallSDK ready to work'); // получим внутренний номер, или идентификатор, который указан для сотрудника в настройках телефонии var userPhone = mpCallJsSdk.getUserInternalNumberConfig(); // конфиг добавляемый через HTTP API для каждого пользователя var userConfig = mpCallJsSdk.getUserConfig(); // конфиг серверный, создается через HTTP API и для всех пользователей одинаковый var serverConfig = mpCallJsSdk.getServerConfig(); mpCallJsSdk.on('connect', function () { // Событие необходимости подключения к серверу телефонии (одно на все вкладки Мегаплана) // При закрытии вкладки - это событие произойдет в другой одной вкладке // Тут реализовываем подключение(websocket), если это необходимо // когда подключение установлено, нужно сказать об этом Мегаплану: mpCallJsSdk.connected(); //При неуспешном подключении mpCallJsSdk.disconnected(); }); mpCallJsSdk.on('disconnect', function () { // Событие отключения от телефонии, например, при отключении пользователя в настройках // После отключения или при разрыве соединения, нужно сказать об этом Мегаплану: mpCallJsSdk.disconnected(); }); // Обработка события нажатия на кнопку звонка в интерфейсе Мегапалана mpCallJsSdk.on('call', function(callInfo){ //Совершаем звонок и если успех, то: mpCallSdk.talking(); //Если ошибка звонка, то: mpCallSdk.badCall(); }); //Кнопка завершить звонок из виджета mpCallJsSdk.on('endCall', function(){ //После успешного завершения звонка на АТС: mpCallJsSdk.finished(); }); /* При изменении состояния звонка, а следовательно, и виджета (например, через hhtp запрос) в неглавной вкладке, можно получать изменения callInfo: */ mpCallJsSdk.on('updateCallInfo', function(callInfo){ console.log(callInfo); }); // Обработка события смены статуса "Не беспокоить" в виджете телефонии mpCallJsSdk.on('changeDndMode', function(isModeOn){ // если значение isModeOn === true, режим "Не беспокоить" включен }); // При событиях звонка используется структура var callInfo = { fromPhone: '100', // с какого номера звонок toPhone: '101', // на какой номер звонок type: 'in', // in | out providerId: '', // Id системы телефонии для звонка, если есть recordLinks: [''] // Массив ссылок на запись разговора }; //Для сообщения виджету о текущем состоянии линии пользователя, например, при работе через WebSocket: // Входящий или исходящий звонок, определяется по callInfo.type mpCallJsSdk.calling(callInfo); //Разговор mpCallJsSdk.talking(callInfo); //Завершенный звонок mpCallJsSdk.finished(callInfo); //После подписки на все события, проставляем возможности текущего приложения в CallSDK, после чего происходит инициализация событий mpCallJsSdk.setCapabilities({ 'WEBTALK': false, //Разговор из браузера 'ANSWER': false, // Ответ на звонок 'END_TALK': false, // Завершение вызова 'TRANSFER': false, // Перевод звонка 'AWAY_MODE': false, // Режим недоступен 'MUTE': false, // При наличии WEBTALK отключение микрофона 'CLEAR_STATE': true, // Сброс состояния (когда нет возможности завершить вызов, но нужно предоставить возможность скрыть виджет телефонии и сбросить его состояние }); });
API провайдер телефонии¶
В Мегаплане, включение интеграции с телефонией происходит при включении API провайдера телефонии
/settings/integration/call/apiProvider/
Код выхода в город и международный код используется для систем, где необходим преднабор кода для выхода в ТфОП или на международную линию. Номер телефона в интеграцию будет приходить уже преобразованный.
Замена кода страны. Мегаплан, по умолчанию, если понимает какой номер ввели, преобразует его и сохраняет в международном формате. Если для локальной АТС необходимо набирать номер не с 7ки а с 8ки, то эта настройка будет заменять номера +7… на номера 8…
Максимальная длинна внутреннего номера нужна для того, чтобы Мегаплан мог понимать идёт разговор внутри компании между сотрудниками или же это внешний звонок.
Типы коммуникаций для различных видов звонков можно настраивать для удобства работы с коммуникациями и отчетами.
Галочка «учитывать внутренние звонки» - при включённом состоянии, будут создаваться коммуникации при звонках между сотрудниками.
После включения, создается приложение от специального пользователя «Call Api User» - это пользователь с правами только для методов телефонии.
При авторизации по HTTP API права ограничены, и открыты для использования только методы для телефонии.
Если вы разрабатываете интеграцию, которой необходимы полные права, то после включения провайдера «API телефония», создайте вручную новое приложение и делайте всю работу в нём.
При установке приложения из расширений Мегаплана, автором будет текущий пользователь с полными правами вместо пользователя телефонии.
Внимание! Ключи приложения подходят для авторизации через APIv1 и APIv3. Все запросы с этими ключами будут выполняться от пользователя, который установил или создал приложение в Мегапалане.
Созданное приложение с ключами доступа по API:
Это приложение можно настраивать и реализовывать виджеты для интеграции с телефонией.
При создании виджета, для телефонии предусмотрено несколько плейсхолдеров, common_telephony_widget:
Плейсхолдер settings_api_telephony:
Плейсхолдеры
common_phone_number - рядом с любым номером телефона в системе,
common_telephony_widget_config (режим настроек виджета - переход по кнопке «три точки» внизу виджета) и
common_telephony_widget_header (всегда сверху виджета телефонии):
Более подробно возможности приложений и виджетов описаны в разделе Приложения.