Возможность подключить WebPhone прямо в своей инфраструктуре

Веб-телефоны становятся все более популярным инструментом исходящих звонков для поддержки отделов продаж и работы с клиентами. Сегодня такое решение предлагает и компания New-Tel. Рассказываем, как интегрировать WebPhone непосредственно в инфраструктуру бизнес-телефонии.

Что такое WebPhone

WebPhone— это клиентское программное обеспечение VoIP, основанное на стандартах SIP. Этот инструмент может быть встроен в любую веб-страницу в качестве программного браузера или использован как библиотека JavaScript VoIP для создания собственного веб-решения VoIP. Будь то простая кнопка вызова или интегрированное комплексное решение с вашей существующей бизнес-логикой, WebPhone обеспечивает эффективное взаимодействие со сторонними системами.

WebPhone разработан для компаний, которые работают с клиентами через собственные приложения, самописную CRM или личный кабинет. По сути, это дополнительная опция виртуальной АТС от компании New-Tel — интеграция телефонии и бизнес-решения организации.

Допустим, в компании есть 100 сотрудников, которые пользуются CRM. В обычной ситуации, чтобы обеспечить им доступ к телефонии, каждому нужно установить софтфон. Однако это долго и сложно.

С помощью интеграции с WebPhone компания может одновременно телефонизировать всех сотрудников. Какие преимущества создает такое решение:

• Создается единая унифицированная телефонная среда.
• Телефония настраивается быстро, один раз и для всех.
• При необходимости для всех сотрудников можно внести изменения в работу системы.

Какие функции предусматривает интеграция с WebPhone:

• Возможность звонить из CRM в один клик.
• Получение уведомления о звонках с подробной информацией об абоненте и ссылкой на клиентскую карточку.
• Ведение статистики звонков.
• Автоматическая генерация лида при звонке.
• Переадресация звонков по сценариям.
• Напоминания о пропущенных вызовах.
• Создание списков входящих звонков, например избранные или нежелательные.
• Интеграция с личным кабинетом New-Tel.

WebPhone в разы упрощает коммуникацию с клиентом через единую систему веб-телефонии

Как интегрировать WebPhone от «Нью-Тел» в свою систему

Для работы с WebPhone необходимо сформировать два постоянных ключа в личном кабинете системы в разделе API:

• для доступа к API-серверу;
• для подписи запросов.

Эти ключи будут использоваться для авторизации запросов, приходящих из вашей информационной системы. Если у зарегистрированного абонента используется несколько информационных систем, интегрированных с API «Нью-Тел», то для всех систем используется один комплект ключей.

ВАЖНО! Не размещайте виджет в открытом доступе в сети, иначе через ваш аккаунт сможет позвонить любой желающий.

Авторизация запросов

Для авторизации запросов используется схема на основе токена Bearer. Достаточно в каждый запрос добавить токен Bearer в формате:

Authorization: Bearer token

Bearer-токен формируется для каждого запроса динамически и представляет собой строку длиной 112 символа:

• Постоянного «Ключа доступа к API-серверу».
• Динамической метки времени.
• Динамической подписи запроса в виде хэша по алгоритму SHA-256 от нескольких переменных.

Например, так формируется токен на PHP:

$token = $keyNewtel.$time.hash ("sha256", $methodName."\n".$time."\n".$keyNewtel."\n".$params."\n".$writeKey)

где:

• \n — команда переноса строки, является разделителем переменных.
• $methodName — относительный путь для вызова метода, например: company/get-state.
• $time — метка времени запроса, формируется динамически клиентом при создании запроса и передается в виде Unix timestamp. Представляет собой строку, состоящую из 10 десятичных цифр. Для прохождения аутентификации и авторизации все запросы должны иметь метку времени в пределах ±10 минут от текущего мирового времени.
• $keyNewtel — постоянный «Ключ доступа к API-серверу», который представляет собой строку из 48 шестнадцатеричных цифр в нижнем регистре (десятичных цифр и латинских букв «a», «b», «c», «d», «e» и «f»). Ключ доступа имеет неограниченный срок жизни и формируется клиентом самостоятельно в личном кабинете «Нью-Тел».
• $params — тело запроса (BODY) со всеми значениями в application/json или в формате application/x-www-form-urlencoded .
• $writeKey — постоянный «Ключ для подписи запросов», который представляет собой строку из 48 шестнадцатеричных цифр в нижнем регистре (десятичных цифр и латинских букв «a», «b», «c», «d», «e» и «f»). Ключ доступа имеет неограниченный срок жизни и формируется клиентом самостоятельно в личном кабинете «Нью-Тел».

Формат запроса

Для всех запросов используется только метод POST по спецификации HTTP/1.1. Параметры запроса передаются в теле сообщения в формате application/json или application/x-www-form-urlencoded.

Строка параметров запроса должна быть сформирована в кодировке UTF-8 без дополнительных пробелов и переносов строк. Например, в PHP это можно сделать методами: json_encode($params) или http_build_query($params), где: $params – ассоциативный массив параметров или объект.

Формат данных запроса должен быть указан в заголовке: Content-Type.

Пример запроса для получения информации о состоянии компании-абонента:

URI

https://api.new-tel.net/company/get-state

HEAD

Authorization: Bearer df9b7fg89n79...

Content-Type: application/json

BODY

{}

Формат ответа

Ответные данные возвращаются всегда в кодировке UTF-8. Формат данных может быть указан в заголовке запроса Accept, где допускаются следующие значения:

• application/json – для ответа в формате JSON;
• application/xml – для ответа в формате XML.

В случае отсутствия в запросе заголовка Accept данные возвращаются в формате JSON.

Ответы для всех запросов содержат следующие нестандартные HTTP-заголовки:

• X-Rate-Limit-Limit – 1;
• X-Rate-Limit-Remaining – 0;
• X-Rate-Limit-Reset – 1;
• Signature — подпись ответа.

Если в ответе отсутствуют указанные заголовки, установите параметр CURLOPT_HEADER => 1 в запросе.

Тело ответа может содержать следующие атрибуты:

• Status — возвращается независимо от результатов обработки запроса сервером. Информирует о результате обработки запроса API-сервером. Может принимать одно из значений:

• success – обработка запроса прошла успешно (аутентификация и авторизация произведены, запрашиваемый метод существует, все необходимые параметры присутствуют и валидны);
• error — при обработке запроса произошла ошибка.

• Message — возвращается для запросов, при обработке которых произошла ошибка (status = error). Содержит текстовое описание ошибки.
• Data — возвращается для успешно обработанных запросов (status = success). Содержит дополнительные атрибуты, информирующие о результатах выполнения запроса:
• Result — возвращается всегда, информирует о результатах работы запрашиваемого метода. Может принимать одно из значений:
• success — запрашиваемый метод успешно выполнен;
• error — при выполнении метода возникла ошибка.
• Result — возвращается для запросов при выполнении которых произошла ошибка (status = error). Содержит текстовое описание ошибки. Возможные ситуации возникновения ошибки и соответствующие сообщения перечислены в описании методов.
• Data — возвращается, если запрашиваемый метод подразумевает возврат данных и запрос успешно выполнен (result = success). Содержит указанное в описании метода свойство, массив или объект, где будут находиться ответные данные.

Подпись ответа

Клиентская сторона может проверять достоверность получаемых данных, сверяя подпись ответа. Подпись ответа вычисляется по алгоритму, аналогичному для вычисления подписи запроса, где вместо строки параметров запроса используется текстовый контент ответного HTTP-сообщения. Результат вычисления отправляется в текстовом виде с HTTP-заголовком: Signature.

Пример проверки подписи ответа сервера на языке PHP — формирование запроса для осуществления соединения между номерами +7 (904) 111-22-33 и +7 (999) 111-22-33 с отображением номера +7 (495) 111-22-33 при вызовах:

<?php

$data = json_encode([

'callerId' => ‘74951112233’,

'dstNumber' => '79041112233',

'srcNumber' => '79991112233',

'timeout' => 30,

]);

var_dump($data);

$time = time();

$resId = curl_init();

$key = getKey('call/start_simple_call',

$time,'616a2cbbc392c798c06161dae2bd0c2093af4f399e95f48d',

$data,'84c29e3807ccb092f50ea7e66537ba9b519628efdd741046');

curl_setopt_array($resId, [

CURLINFO_HEADER_OUT => true,

CURLOPT_HEADER => 0,

CURLOPT_HTTPHEADER => [

'Authorization: Bearer '.$key ,

'Content-Type: application/json' ,

],

CURLOPT_POST => true,

CURLOPT_RETURNTRANSFER => true,

CURLOPT_SSL_VERIFYPEER => false,

CURLOPT_URL => 'https://api.new-tel.net/call/start_simple_call',

CURLOPT_POSTFIELDS => $data,

]);

$response = curl_exec($resId);

$curlInfo = curl_getinfo($resId);

echo $response;

function getKey ($methodName , $time , $keyNewtel , $params , $writeKey )

{

return $keyNewtel.$time.hash( 'sha256' ,

$methodName."\n".$time."\n".$keyNewtel."\n".

$params."\n".$writeKey);

}

Внедрение WebPhone на вашу страницу

Для успешного интегрирования виджета WebPhone в вашу систему вам необходимо выполнить настройку в личном кабинете «Нью-Тел», а также добавить соответствующий JavaScript-код на страницу вашего проекта.

Настройка личного кабинета New-Tel:

• Для получения настроек пользователя через API необходимо, чтобы у данного пользователя был привязан внутренний номер в системе.
• Для проверки наличия внутреннего номера у пользователя в разделе «Профиль компании» выберите закладку «Сотрудники», затем найдите нужного пользователя и проверьте наличие внутреннего номера у данного сотрудника.
• Если внутренний номер отсутствует, необходимо добавить его в настройках профиля данного пользователя. После добавления внутреннего номера можно будет получить настройки пользователя через API.

Настройка WebPhone со стороны клиента:

Добавьте следующий код в <head> секцию HTML-кода вашей страницы:

<link href="https://public.new-tel.net/webrtc/widget.css" rel="stylesheet">

Данный код подключает стили по умолчанию для виджета. Если вы хотите кастомизировать виджет, вы можете создать свои стили на основе данных стилей.

В <body> секции HTML-кода вашей страницы добавьте следующий код:

<script>

window.newtelWebrtcWidgetConfig = <?= json_encode($widgetConfig, JSON_UNESCAPED_SLASHES) ?>

</script>

<script

async src="https://public.new-tel.net/webrtc/widget.js">

</script>

Данный код создает и использует глобальный объект window.newtelWebrtcWidgetConfig, который содержит все параметры для виджета. Эти параметры можно получить через API-метод:

webrtc/get-widget-config

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

Пример кода:

<style>

.widget-container {

background-color: #fff;

border: 1px solid #ccc;

border-radius: 5px;

box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);

position: fixed;

bottom: 20px;

right: 20px;

z-index: 9999;

}

</style>

<!-- Подключение стилей по умолчанию -->

<link href="https://public.new-tel.net/webrtc/widget.css" rel="stylesheet">

<?php

// API-ключи и данные для запроса

$api_key_new_tel = YOUR_API_KEY;

$writeKey_new_tel = YOUR_SIGNING_KEY;

$data =json_encode([

'internalNumber' => 100,

]);

// Вычисление ключа авторизации

$time = time();

$key = getKey_new_tel('webrtc/get-widget-config', $time, $api_key_new_tel, $data, $writeKey_new_tel);

// Опции для запроса

$resId = curl_init();

$options = [

CURLINFO_HEADER_OUT => true,

CURLOPT_HEADER => 0,

CURLOPT_HTTPHEADER => [

'Authorization: Bearer ' . $key ,

'Content-Type: application/json',

],

CURLOPT_POST => true,

CURLOPT_RETURNTRANSFER => true,

CURLOPT_SSL_VERIFYPEER => false,

CURLOPT_URL => 'https://api.new-tel.net/webrtc/get-widget-config',

CURLOPT_POSTFIELDS => $data,

];

curl_setopt_array($resId, $options);

// Выполнение запроса и обработка ответа

$response = curl_exec($resId);

$curlInfo = curl_getinfo($resId);

$ajax = array();

$ajax = json_decode($response, true);

if (isset($ajax['status']) AND $ajax['status'] == 'success') {

?>

<!-- Создание и использование объекта конфигурации виджета -->

<script>window.newtelWebrtcWidgetConfig = <?php echo json_encode($ajax['data']['widgetConfig'],JSON_UNESCAPED_SLASHES); ?>;</script>

<!-- Подключение скрипта виджета -->

<script async src="https://public.new-tel.net/webrtc/widget.js"></script>

<!-- Контейнер виджета -->

<div class="widget-container">

<div class="widget-header">

<span>WebRTC виджет</span>

</div>

<div class="widget-body">

<p>Здесь будет содержимое виджета.</p>

</div>

</div>

<?php

}

function getKey_new_tel($methodName, $time, $keyNewtel, $params, $writeKey) {

return $keyNewtel . $time . hash('sha256', $methodName . "\n" . $time . "\n" . $keyNewtel . "\n" . $params . "\n" . $writeKey);

}

?>

Для управления WebPhone-виджетом существует ряд доступных методов. Если вам необходимы дополнительные методы для управления виджетом, вы можете обратиться в техническую поддержку ООО «Нью-Тел» по адресу: support@new-tel.net с запросом на разработку дополнительных методов. Наши специалисты будут рады помочь вам и предоставить дополнительную информацию о возможностях взаимодействия с WebPhone-виджетом.