Прежде чем перейти к статье, хочу вам представить, экономическую онлайн игру Brave Knights, в которой вы можете играть и зарабатывать. Регистируйтесь, играйте и зарабатывайте!
![](https://habrastorage.org/webt/9p/4z/il/9p4zilg_eledccytuo6hslf19f0.png)
Современный бизнес воспринимает городские телефоны как устаревшую технологию: сотовая связь обеспечивает мобильность и постоянную доступность сотрудников, соцсети и мессенджеры являются более легким и быстрым каналом общения. Чтобы не отставать от своих конкурентов, офисные АТС все больше становятся похожи на них: они переходят в облака, управляются через web-интерфейс и интегрируются с другими системами через API. В этом посте мы расскажем, какие есть функции у API виртуальной АТС «Ростелекома» и как через него работать с основными функциями виртуальной АТС.
Основная задача API виртуальной АТС «Ростелекома» — взаимодействие с CRM или сайтами компаний. Например, на API реализованы виджеты «обратный звонок» и «звонок с сайта» для основных систем управления: WordPress, Bitrix, OpenCart. API позволяет:
- Получать информацию, уведомлять о статусе и совершать вызовы по запросу из внешней системы;
- Получить временную ссылку на запись разговора;
- Управлять и получать параметры ограничений у пользователей;
- Получить информацию о пользователе вирутальной АТС;
- Запросить истории списаний и начислений по вызовам;
- Выгрузить журнал звонков.
Как работает API
Интеграционный API и внешняя система взаимодействуют между собой при помощи HTTP-запросов. В личном кабинете администратор задает адреса, куда должны приходить запросы к API и куда должны отправляться запросы от API. У внешней системы должен быть публичный адрес, доступный из интернета, с установленным SSL-сертификатом.
![](https://habrastorage.org/getpro/habr/post_images/aef/32c/8c5/aef32c8c5b54534a5b002a87166cb724.png)
Также в личном кабинете администратор домена может ограничить по IP источники запросов при обращении к API.
Получаем информацию о пользователях виртуальной АТС
Чтобы получить список пользователей или групп, нужно отправить в виртуальной АТС запрос методом /users_info.
{
"domain":"example.ru"
}
В ответ придет список, который можно сохранить.
{
"result":0,
"resultMessage":"",
"users":[
{
"display_name":"test_user_1",
"name":"admin",
"pin":^_^quotʚquot^_^,
"is_supervisor":true,
"is_operator":false,
"email":"<a href="mailto:test_user_1@mail.gov">test_user_1@mail.gov</a>","recording":1
},
{
"display_name":"test_user_2",
"name":"test",
"pin":^_^quotʿquot^_^,
"is_supervisor":true,
"is_operator":false,
"email":"",
"recording":1
}
],
"groups":
[
{
"name":"testAPI",
"pin":^_^quotǴquot^_^,
"email":"Ivanov@mail.gov",
"distribution":1,
"users_list":[^_^quotʚquot^_^,^_^quotʿquot^_^]
}
]
В данном методе передается два массива. Один с пользователями домена, один с группами домена. У группу также есть возможность указать электронную почту, которая будет передаваться в запросе.
Обрабатываем информацию о входящем вызове
Подключение корпоративной телефонии к различным системам CRM экономит время сотрудников, которые взаимодействуют с клиентами, и ускоряет обработку входящих звонков. Например, по звонку от текущего клиента CRM может открыть его карточку, а из CRM можно отправить вызов клиенту и соединить его с сотрудником.
Чтобы получить информацию о вызовах через API, нужно использовать метод /get_number_info, который формирует список вызовов с информацией о группе, в которую вызов распределяется. Предположим, что на номер виртуальной АТС поступил входящий вызов с номера 1234567890. Тогда от АТС отправится запрос:
{
"session_id":"SDsnZugDFmTW7Sec",
"timestamp":"2019-12-27 15:34:44.461",
"type":"incoming",
"state":"new",
"from_number":"sip:</i^_^gtlt&i;gt^_^@192.168.0.1",
"from_pin":"",
"request_number":"sip:</i^_^gtlt&i;gt^_^@1192.168.0.1",
"request_pin":^_^quotɟquot^_^,
"disconnect_reason":"",
"is_record":""
}
Далее нужно подключить обработчик /get_number_info. Запрос должен выполняться при поступлении входящего вызова на входящую линию до маршрутизации вызовов. Если ответ на запрос не получен за установленное время, то вызов маршрутизируется по установленным в домене правилам.
Пример обработчика на стороне CRM.
if ($account) {
$data = [
'result' => 0,
'resultMessage' => 'Абонент найден',
'displayName' => $account->name,
//'PIN' => $crm_users,
];
}
else
{
$data = [
'result' => 0,
'resultMessage' => 'Абонент не найден',
'displayName' => 'Неизвестный абонент '.$contact,
//'PIN' => crm_users,
];
}
return $data;
Ответ от обработчика.
{
"result":0,
"resultMessage":"Абонент найден",
"displayName":"Иванов Иван Иванович +1</i> 234-56-78-90<i>"
}
Отслеживаем статус и скачиваем записи разговоров
В виртуальной АТС «Ростелекома» запись разговоров активируется в личном кабинете. При помощи API можно отслеживать статус этой функции. При обработке завершения вызова в call_events можно увидеть флаг ‘is_record’, который уведомляет пользователя о статусе записи: true означает, что функция записи разговора у пользователя подключена.
Чтобы скачать запись, нужно по идентификатору сессии вызова session_id отправить запрос на api.cloudpbx.rt.ru/get_record.
{
"session_id":"SDsnZugDFmTW7Sec"
}
В ответ придет временная ссылка на скачивание файла с записью разговора.
{
"result": ^_^quotquot^_^,
"resultMessage": "Операция выполнена успешно",
"url": "https://api.cloudpbx.rt.ru/records_new_scheme/record/download/501a8fc4a4aca86eb35955419157921d/188254033036"
}
Время хранения файла задается в настройках личного кабинета. После файл будет удален.
Статистика и отчетность
В личном кабинете на отдельной странице можно увидеть статистику и отчетность по всем вызовам и применить фильтры по статусу и времени. Через API нужно сначала обработать вызов методом /call_events:
{
"session_id":"SDsnZugDFmTW7Sec",
"timestamp":"2019-12-27 15:34:59.349",
"type":"incoming",
"state":"end",
"from_number":"sip:</i^_^gtlt&i;gt^_^@192.168.0.1",
"from_pin":"",
"request_number":"sip:</i^_^gtlt&i;gt^_^@192.168.0.1",
"request_pin":^_^quotʚquot^_^,
"disconnect_reason":"",
"is_record":"true"
}
Затем вызвать метод call_info для обработки массива и отображения вызова в CRM системе.
{
"session_id":"SDsnZugDFmTW7Sec"
}
В ответ придет массив данных, который можно обработать для хранения данных в журнале CRM.
{
"result":0,
"resultMessage":"",
"info":
{
"call_type":1,
"direction":1,
"state":1,
"orig_number":"sip:</i^_^gtlt&i;gt^_^@192.168.0.1",
"orig_pin":null,
"dest_number":"sip:</i^_^gtlt&i;gt^_^@192.168.0.1",
"answering_sipuri":"sip:<a href="mailto:admin@SNovos4.20.rt.ru">admin@example.ru</a>",
"
answering_pin":^_^quotɟquot^_^,
"start_call_date":^_^quotquot^_^,
"duration":14,
"session_log":"0:el:123456789;0:ru:admin;7:ct:admin;9:cc:admin;14:cd:admin;",
"is_voicemail":false,
"is_record":true,
"is_fax":false,
"status_code":^_^quotquot^_^,
"status_string":""
}
}
Другие полезные функции виртуальной АТС
Кроме API, у виртуальной АТС есть еще несколько полезных функций, которые можно использовать. Например, это интерактивное голосовое меню и объединение сотовой и фиксированной связи.
Интерактивное голосовое меню (IVR — Interactive Voice Response) — то, что мы слышим в трубке до того, как ответит человек. По сути, это электронный оператор, который перенаправляет вызовы в соответствующие отделы и отвечает на часть вопросов в автоматическом режиме. Скоро с IVR можно будет работать через API: сейчас мы разрабатываем ПО, которое позволит отслеживать прохождение вызова через IVR и получать информацию о нажатиях клавиш тонального набора при нахождении абонента в голосовом меню.
Для переноса корпоративной телефонии на мобильные телефоны можно либо использовать приложения-софтфоны, либо отдельно подключить услугу Fixed Mobile Convergence (FMC). При любом из способов звонки внутри сети бесплатны, появляется возможность работать с короткими номерами, а звонки можно записывать и вести по ним общую статистику.
Отличие заключается в том, что софтфонам для связи нужен интернет, но они не привязаны к оператору, а FMC привязана к определенному оператору, но может использоваться даже на старых кнопочных телефонах.