Виртуальная АТС Ростелекома: что и как можно сделать через API

9p4zilg_eledccytuo6hslf19f0.png

Современный бизнес воспринимает городские телефоны как устаревшую технологию: сотовая связь обеспечивает мобильность и постоянную доступность сотрудников, соцсети и мессенджеры являются более легким и быстрым каналом общения. Чтобы не отставать от своих конкурентов, офисные АТС все больше становятся похожи на них: они переходят в облака, управляются через web-интерфейс и интегрируются с другими системами через API. В этом посте мы расскажем, какие есть функции у API виртуальной АТС «Ростелекома» и как через него работать с основными функциями виртуальной АТС.
Основная задача API виртуальной АТС «Ростелекома» —  взаимодействие с CRM или сайтами компаний. Например, на API реализованы виджеты «обратный звонок» и «звонок с сайта» для основных систем управления: WordPress, Bitrix, OpenCart. API позволяет:

  • Получать информацию, уведомлять о статусе и совершать вызовы по запросу из внешней системы;
  • Получить временную ссылку на запись разговора;
  • Управлять и получать параметры ограничений у пользователей;
  • Получить информацию о пользователе вирутальной АТС;
  • Запросить истории списаний и начислений по вызовам;
  • Выгрузить журнал звонков.


Как работает API


Интеграционный API и внешняя система взаимодействуют между собой при помощи HTTP-запросов. В личном кабинете администратор задает адреса, куда должны приходить запросы к API и куда должны отправляться запросы от API. У внешней системы должен быть публичный адрес, доступный из интернета, с установленным SSL-сертификатом.

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":"test_user_1@mail.gov","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:


Далее нужно подключить обработчик /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 234-56-78-90"
}


Отслеживаем статус и скачиваем записи разговоров


В виртуальной АТС «Ростелекома» запись разговоров активируется в личном кабинете. При помощи API можно отслеживать статус этой функции. При обработке завершения вызова в call_events можно увидеть флаг «is_record», который уведомляет пользователя о статусе записи: true означает, что функция записи разговора у пользователя подключена.

Чтобы скачать запись, нужно по идентификатору сессии вызова session_id отправить запрос на api.cloudpbx.rt.ru/get_record.

{
        "session_id":"SDsnZugDFmTW7Sec"
}


В ответ придет временная ссылка на скачивание файла с записью разговора.

{
        "result": ^_^quot

Время хранения файла задается в настройках личного кабинета. После файл будет удален.

Статистика и отчетность


В личном кабинете на отдельной странице можно увидеть статистику и отчетность по всем вызовам и применить фильтры по статусу и времени. Через API нужно сначала обработать вызов методом /call_events:

       {
        "session_id":"SDsnZugDFmTW7Sec",
        "timestamp":"2019-12-27 15:34:59.349",
        "type":"incoming",
        "state":"end",
        "from_number":"sip:


Затем вызвать метод call_info для обработки массива и отображения вызова в CRM системе.

     {
        "session_id":"SDsnZugDFmTW7Sec"
}


В ответ придет массив данных, который можно обработать для хранения данных в журнале CRM.

{
        "result":0,
        "resultMessage":"",
        "info":
        {
                "call_type":1,
                "direction":1,
                "state":1,
                "orig_number":"sip:admin@example.ru",
                "
                  answering_pin":^_^quotɟquot^_^,
                "start_call_date":^_^quot�quot^_^,
                "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":^_^quot

Другие полезные функции виртуальной АТС


Кроме API, у виртуальной АТС есть еще несколько полезных функций, которые можно использовать. Например, это интерактивное голосовое меню и объединение сотовой и фиксированной связи.

Интерактивное голосовое меню (IVR — Interactive Voice Response) — то, что мы слышим в трубке до того, как ответит человек. По сути, это электронный оператор, который перенаправляет вызовы в соответствующие отделы и отвечает на часть вопросов в автоматическом режиме. Скоро с IVR можно будет работать через API: сейчас мы разрабатываем ПО, которое позволит отслеживать прохождение вызова через IVR и получать информацию о нажатиях клавиш тонального набора при нахождении абонента в голосовом меню.

Для переноса корпоративной телефонии на мобильные телефоны можно либо использовать приложения-софтфоны, либо отдельно подключить услугу Fixed Mobile Convergence (FMC). При любом из способов звонки внутри сети бесплатны, появляется возможность работать с короткими номерами, а звонки можно записывать и вести по ним общую статистику. 

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

© Habrahabr.ru