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

в 7:05, , рубрики: api, Блог компании Ростелеком, виртуальные атс, Ростелеком, системное администрирование

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

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

Основная задача API виртуальной АТС «Ростелекома» —  взаимодействие с CRM или сайтами компаний. Например, на API реализованы виджеты «обратный звонок» и «звонок с сайта» для основных систем управления: WordPress, Bitrix, OpenCart. API позволяет:

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

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

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

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

Также в личном кабинете администратор домена может ограничить по 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^_^gt&#1234567890;lt&i;gt^_^@192.168.0.1",
        "from_pin":"",
        "request_number":"sip:</i^_^gt&#1234567890;lt&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^_^gt&#1234567890;lt&i;gt^_^@192.168.0.1",
        "from_pin":"",
        "request_number":"sip:</i^_^gt&#1234567890;lt&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^_^gt&#1234567890;lt&i;gt^_^@192.168.0.1",
                "orig_pin":null,
                "dest_number":"sip:</i^_^gt&#1234567890;lt&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":^_^quot&#1577450084;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":^_^quotquot^_^,
                "status_string":""
        }
}

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

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

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

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

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

Автор: RTteam

Источник

* - обязательные к заполнению поля


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js