- Created by Абдукадыров Далер Давронжонович, last modified by Щериканова Евгения Александровна on May 19, 2021
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 12 Next »
Предупреждение
При использовании мобильной версии могут быть недоступны некоторые элементы управления страницей. Вы можете переключиться на версию для компьютера или скачать приложение Confluence, чтобы получить доступ ко всем элементам управления страницей.
Аутентификация OAuth 2.0
Для аутентификации запросов используется протокол OAuth 2.0.
OAuth 2.0 — протокол авторизации, позволяющий выдать одному сервису (приложению) права на доступ к ресурсам пользователя на другом сервисе. Протокол избавляет от необходимости доверять приложению логин и пароль, а также позволяет выдавать ограниченный набор прав, а не все сразу.
Порядок настройки и использования протокола следующий:
- Необходимо открыть страницу услуги Открытое API в ЛК МТТБ;
- Подключить услугу «Открытое API». При этом осуществляется проверка достаточности необходимых денежных средств, выполняются прочие юридические и административные процедуры, формируются документы для подписания;
- Нажать на кнопку Создать в разделе Мои интеграции. Необходимо указать наименование интеграции (цифра 1 на рисунке) и ссылку, на которой будет производиться обработка нотификации по протоколу https (Redirect URI, цифра 2 на рисунке.). Сервер должен иметь соответствующий доверенный сертификат;
- Нажать на кнопку Сгенерировать. Произойдёт генерация Секретного ключа и Уникального идентификатора (Id клиента, цифра 3 и 4 на рисунке), а также осуществится проверка доступности данного сервера со стороны решения. Сгенерированные данные, а так же адрес сервиса аутентификации решения (цифра 5 на рисунке) можно удобно скопировать в буфер обмена;
- Дальнейшие настройки необходимо провести на стороне стороннего приложения. Ввести в системе Уникальный идентификатор и Секретный ключ из предыдущего шага. Приложение должно произвести первичную авторизацию и отобразить окно ввода учётных данных от ЛК МТТ Бизнес. Если все данные введены верно, решение выдаст приложению два токена: токен доступа (access_token) и токен обновления (refresh_token);
- Срок годности токена доступа (access_token) – 2 часа, токена обновления (refresh_token) - 3 календарных дня. При истечении срока годности токена доступа (access_token) он должен быть обновлен с использованием токена обновления (refresh_token) и уникального идентификатора интеграции (Id клиента). В случае истечения срока действия токена доступа (access_token) решение будет отвечать кодом ответа HTTP 401 (Unauthorized).
Необходимо отметить, что для каждой новой интеграции будут сгенерированы свои уникальные ключи. Даже в рамках одного личного кабинета, каждая интеграция - уникальна.
Описание:
Первичная регистрация производит запрос аккредитационных данных с проверкой регистрации в ЛК МТТ Бизнес.
Параметры:
GET/ https://\{{hostoauth}}/oauth/authorize
Параметр | Описание/значение |
client_id | Значение получается из ЛК МТТ Бизнес |
redirect_uri | URL переадресации кода (например, {+}http://localhost:9090+ |
scope | Обязательно должен быть установлено значение https://mtt.ru/auth.tokens.readwrite |
response_type | Обязательно должен быть установлено значение "code" |
state | не обязательный параметр, но служит для защиты от CSRF, а также позволяет хранить состояние в процессе авторизации. |
После выполнения запроса, будет выполнен редирект на страницу ввода логина и пароля в ЛК МТТ Бизнес. После успешного подтверждения логина и пароля, будет выполнен редирект на указанный redirect_uri с передачей кода (например: http://localhost:9090/callback?code=Yzk5ZDczMzRlNDEwY&state=xyz).
Используя полученный код авторизации, приложение далее сможет выполнить генерацию access_token и refresh_token.
Описание:
Запрос производит генерацию токена доступа (access_token) и токена обновления (refresh_token).
Токен доступа (access_token) – токен, с которым клиентское приложение осуществляет запросы к разрешенным Открытому API, выдается на 2 часа.
Токен обновления (refresh_token) - используется для получения нового токена доступа без повторного ввода пароля. Выдается на 3 дня.
Параметры:
POST / https://\{{hostoauth}}/oauth/token
Параметр | Описание/значение |
client_id | Значение генерируется и задается из ЛК МТТ Бизнес |
client_secret | Значение генерируется и задается из ЛК МТТ Бизнес |
code | Значение, которое было передано на redirect_uri при первичной регистрации |
redirect_uri | URL переадресации кода (например, {+}http://localhost:9090+ |
scope | Обязательно должен быть установлено значение https://mtt.ru/auth.tokens.readwrite![]() |
grant_type | Обязательно должен быть установлено значение "authorization_code" |
Параметры ответа:
Параметр | Описание/значение |
access_token | Токен доступа |
expires_in | Длительность действия в секундах |
refresh_token | Токен обновления |
scope | |
token_type | Bearer |
Пример ответа:
{
"access_token": "MMRLZJU5NTETMTNHZI0ZNZIYLWJHOTGTNJY1M2ZMM2YZNMYX",
"expires_in": 7200,
"refresh_token": "YWFHNGFHYMQTMTUYMI01ZTM0LTKZM2QTYZU2YZIWNJQ0MJE0",
"scope": "https://mtt.ru/auth/openapi.readwrite",
"token_type": "Bearer"
}
Описание:
Обменивает вышедший из употребления токен доступа (access_token) на новый путём использования токена обновления (refresh_token).
Параметры:
POST / https://\{{hostoauth}}/oauth/token
Параметр | Описание/значение |
client_id | Значение генерируется и задается из ЛК МТТ Бизнес |
client_secret | Значение генерируется и задается из ЛК МТТ Бизнес |
grant_type | Обязательно должно быть установлено значение "refresh_token" |
Параметры ответа:
Параметр | Описание/значение |
access_token | Токен доступа |
expires_in | Длительность действия в секундах |
refresh_token | Токен обновления |
scope | |
token_type | Bearer |
Пример ответа:
{
"access_token": "MMRLZJU5NTETMTNHZI0ZNZIYLWJHOTGTNJY1M2ZMM2YZNMYX",
"expires_in": 7200,
"refresh_token": "YWFHNGFHYMQTMTUYMI01ZTM0LTKZM2QTYZU2YZIWNJQ0MJE0",
"scope": " https://mtt.ru/auth.tokens.readwrite ",
"token_type": "Bearer"
}
Методы для работы с настройками ВАТС МТТ Бизнес
Группа методов запросов и нотификации предназначены для получения информации о настройке ВАТС в ЛК: внешней нумерации и составе РМ пользователей МТТ Бизнес.
При изменении настроек пользователем в ЛК МТТ Бизнес отрабатывают соответствующие методы нотификации, которые возвращают новую, обновленную информацию.
Для всех методов используется единый адрес для отправки запросов: https://openapi.mtt.ru
Для получения нотификаций необходимо настроить сервер по адресу Redirect URI указанному при подключении интеграции в ЛК МТТ Бизнес и по пути /events нужно настроить слушателя событий (обработчик POST запросов). Дополнительно специально подписываться нигде не нужно, вы будете получать все события на свой сервер redirect_uri/events.
Описание:
Получает информацию о внешней нумерации пользователя МТТ Бизнес. Для работы используется auth_token в соответствии с протоколом OAuth 2.0.
Адрес для отправки запроса:
Параметры:
GET / externalNumbersInfo
Параметры ответа:
Параметр | Описание/значение |
total | Общее количество номеров в ответе |
numbersList | Массив РМ с их описанием |
numbersList / number | Внешний номер |
numbersList / type | Тип номера В ВАТС |
Пример ответа
{
"result": {
"total": 1,
"numbersList": [{
"number": "78005560251",
"type": null
}]
}
}
Описание:
Получает список РМ ЛС МТТ Бизнес. Для работы используется auth_token в соответствии с протоколом OAuth 2.0.
Адрес для отправки запроса:
Параметры:
GET / workPlacesInfo
Параметры ответа:
Параметр | Описание/значение |
Total | Общее количество РМ в ответе |
workplacesList | Массив РМ с их описанием |
workplacesList/ name | Наименование РМ |
workplacesList/ workplace | SIP ID РМ ВАТС |
Пример ответа
{
"result": {
"total": 1,
"workplacesList": [{
"workplace": "883140777716581",
"name": "Администратор"
}]
}
Описание:
Получение списка терминалов (локаций) ЛС МТТ Бизнес с привязкой к РМ. Для работы используется auth_token в соответствии с протоколом OAuth 2.0.
Адрес для отправки запроса:
Параметры:
GET / terminalsInfo
Параметры ответа:
Параметр | Описание/значение |
Total | Общее количество РМ в ответе |
terminalsList | Массив РМ с их описанием |
terminalsList / terminale | SIP ID терминала |
terminalsList / workplace | SIP ID РМ |
{
"result": {
"total": 1,
"terminals_list": [{
"terminal": "883140777380595",
"workplace": "883140777380595"
}]
}
}
Описание:
Нотификация об изменении структуры РМ в ЛК МТТ Бизнес.
Параметры нотификации:
Параметр | Описание/значение |
Event | Тип нотификации. vpbxNotifications – нотификация об изменении в структуре ВАТС |
eventType | numbersChanged |
Пример нотификации:
{
"event": "vpbxNotifications",
"result": {
"eventType": "numbersChanged"
}
}
Описание:
Нотификация об изменении структуры РМ в ЛК МТТ Бизнес. Возникает при изменении настроек в ЛК МТТ Бизнес.
Параметры нотификации:
Параметр | Описание/значение |
Event | Тип нотификации. vpbxNotifications – нотификация об изменении в структуре ВАТС |
eventType | workplacesChanged |
Пример нотификации:
{
"event": "vpbxNotifications",
"result": {
" eventType ": "workplacesChanged"
}
}
Методы для работы с вызовами
Группа методов для работы с вызовами позволяет получать информацию о вызовах и их состояниях, осуществлять управление вызовами, настраивать режим «парковки» для внешних номеров.
Для всех методов используется единый адрес для отправки запросов: https://openapi.mtt.ru
Для получения нотификаций необходимо настроить сервер по адресу Redirect URI указанному при подключении интеграции в ЛК МТТ Бизнес и по пути /events нужно настроить слушателя событий (обработчик POST запросов). Дополнительно специально подписываться нигде не нужно, вы будете получать все события на свой сервер redirect_uri/events.
Описание:
Производит инициализацию вызова с использованием пользовательского РМ или терминала и вызов указанного в запросе номера. Алгоритм работы ВАТС:
- ВАТС инициирует вызов на рабочее место Оператора (параметр callerId).
- Дожидается принятия вызова оператором ("поднятия трубки"). Если Оператор не отвечает в течении одной минуты, то дальнейшая работа метода прерывается.
- После успешного ответа Оператора, ВАТС инициирует второй исходящий вызов на номер абонента (параметр calleeId) и производит объединение вызовов.
Необходимо учесть последовательность: второе плечо (вызов на calleeId) осуществляется только после ответа «первого плеча» (SIP ID РМ callerId).
Параметр callerId обычно "подтягивается" из CRM системы по данным текущего рабочего места Оператора настроенного в CRM системе.
Адрес для отправки запроса:
Параметры:
POST/ makeCall
Параметр | Описание/значение |
callerId | SIP ID РМ (не терминала, только РМ) с которого осуществляется вызов. На этот SIP ID будет создано первое плечо. Как только пользователь ответит на вызов, то будет создаваться второе плечо в сторону вызываемого номера. |
calleeId | Вызываемый номер (Абонент Б) |
Пример запроса:
{
"params": {
"calleeId": "89219462761",
"callerId": "883140582526566"
}
}
Пример ответа:
{
"result": {
"call": {
"id": "7NKe6!8fa1FMSlc6ypZdb1GSV6ZN@10.133.51.137"
},
"success": 1
},
}
Описание:
Завершает плечо вызова, что позволяет продолжить обработку по стандартному маршруту, который настроен в ЛК ВАТС МТТ Бизнес. Данной командой можно прекратить «парковку» вызова, так как в момент парковки создаётся дополнительное плечо.
Адрес для отправки запроса:
Параметры:
POST/ terminateCall
Параметр | Описание/значение |
Call | Идентификатор вызова |
call/id | Call-ID - Идентификатор плеча вызова |
call/tag | Tag вызова. Дополнительный идентификатор вызова |
transportId | Внутренний идентификатор транспорта из нотификации |
Пример запроса:
{
"params": {
"call": {
"id": "b9111e52e5d011e9aec7ac162d8cda20_00015D95DB072BFC_7022A1~2o",
"tag": "133609"
},
"transportId": "10.133.51.137:5070"
}
}
Пример ответа:
{
"result": {
"success": 1
}
}
Описание:
Выполняет перевод (трансфер) вызова на указанный номер (SIP ID). Данный метод используется для управления вызовами и осуществления альтернативного распределения вызовов, взамен настроенного в ЛК МТТ Бизнес. Возможно два варианта использования:
- перевод уже отвеченного вызова во время разговора. Пока не ответит номера Абонента Б, в линии будет играть мелодия ожидания.
- перевод ещё не отвеченного вызова. Вызывающий абонент при этом слышит обычные гудки (КПВ). При реализации кейса "маршрутизация на персонального менеджера", сначала необходимо получить нотификацию с информацией о вызове и затем выполнить данный метод для его перевода на необходимое рабочее место.
Адрес для отправки запроса:
Параметры:
POST/transferCall
Параметр | Описание/значение |
call | Идентификатор вызова |
call/id | Call-ID - Идентификатор плеча вызова |
call/tag | Tag вызова. Дополнительный идентификатор вызова |
calleeId | Номер (SPI ID) Абонента Б |
transportId | Внутренний идентификатор транспорта из нотификации |
Пример запроса:
{
"params": {
"call": {
"id": "b9111e52e5d011e9aec7ac162d8cda20_00015D95DB072BFC_7022A1~2o",
"tag": "133609"
},
" calleeId ": "883140582526566",
"transportId": "10.133.51.137:5070"
}
}
Пример ответа:
{
"result": {
"success": 1
}
}
Описание:
Устанавливает или снимает внешний номер(а) с парковки. Если у внешнего номера активирована «парковка», то при поступлении входящего вызова он не распределяется по логике ВАТС МТТ Бизнес, а на 5 секунд устанавливается на «парковку». Нотификация об этом передаётся по API во внешнее приложение. В течении этих 5 секунд по API ожидается команда перераспределения входящего вызова. Если в течении 5 секунд команды на перенаправление вызова не последовало, то задействуется ранее настроенная для номера логика распределения вызов в ВАТС МТТ Бизнес. При помощи данного метода реализуется кейс «маршрутизация на персонального менеджера».
Адрес для отправки запроса:
Параметры:
POST / setParkingNumbers
Параметры нотификации
Параметр | Описание/значение |
numbers | Массив номеров из внешней нумерации клиента |
isParking | True, если устанавливается |
Пример запроса
{
"params": {
"numbers": ["880023213", "880034344"],
"isParking": true
}
}
Пример ответа
{ "success": 1 }
Нотификация о вызовах
Методы нотификации о вызовах предназначены для получения информации о начале и окончании вызова, прохождении вызова по РМ пользователей МТТ Бизнес и прикрепления записи разговора.
Параметр | Описание/значение |
Event | Тип нотификации. callNotifications для нотификации о вызовах |
callInfo | Информация по вызову |
callInfo/call | Идентификатор вызова |
callInfo/call/id | Call-ID - Идентификатор плеча вызова |
callInfo/call/tag | Tag вызова. Дополнительный идентификатор вызова |
callInfo/callee | Описание Абонента Б |
callInfo/caller | Описание Абонента А |
callInfo/startTime | Время операции |
callInfo/state | trying – пытаемся дозвониться, |
callInfo/transportId | Внутренний идентификатор транспорта |
callInfo/type | Incoming – входящий, |
callInfo/duration | Длительность вызова |
callInfo/{callee,caller}/accountId | Идентификатор аккаунта терминала |
callInfo/{callee,caller}/centrexId | Идентификатор пользователя в МТТ Бизнес. Одинаковый для всех запросов в рамках одного пользователя. |
callInfo/{callee,caller}/displayId | Отображаемый идентификатор |
callInfo/{callee,caller}/dispayName | Отображаемое имя |
callInfo/{callee,caller}/forwarderList | Список идентификаторов, через которые прошел вызов до получения сообщения |
callInfo/{callee,caller}/id | SIP ID ВАТС (если есть) |
callInfo/duration | Длительность вызова при завершении |
сallInfo/ reason | Текст причины окончания вызова |
сallInfo/ reasonCode | Код причины окончания вызова |
сallInfo/urlRecord | Ссылка на запись разговора |
Описание:
Сообщение о начале входящего вызова.
При поступлении входящего вызова на внешнюю нумерацию пользователя, вызов «паркуется» на 5 сек для принятия решения о его последующем перераспределении. При «парковке» создается отдельное «плечо» вызова, которое передается в сообщении.
Сообщение предназначено для:
- выполнения необходимых проверок, анализа параметров и создания сущностей.
перенаправления вызова на РМ пользователя ВАТС.
выдачи команды на прекращение «парковки» и отправки вызова по маршруту, который настроен в логике распределения вызовов ВАТС МТТ Бизнес.
Пример нотификации
{
"event": "callNotifications",
"result": {
"callInfo": {
"call": {
"id": "c166e238a4c211ea9d373863bb43daf8_00015ED635780FC7~1o",
"tag": "hswdfry52vmykfla____.o"
},
"callee": {
"accountId": "74996497803",
"centrexId": "67821426",
"displayId": "74996497803",
"displayName": "",
"forwarderList": [],
"id": "74996497803"
},
"caller": {
"accountId": "78124241500@pstn",
"displayId": "78124241500",
"forwarderList": [],
"id": "78124241500"
},
"startTime": "2020-06-02 11:18:16",
"state": "trying",
"transportId": "10.133.33.136:5073",
"type": "incoming"
}
}
}
Описание:
Сообщение о начале исходящего вызова.
Пример нотификации:
{
"event": "callNotifications",
"result": {
"callInfo": {
"call": {
"id": "SDfe2n901-b510751695c9e53584301f0c0e8d98c9200@127.0.0.1",
"tag": "sdfe2n901-281028329"
},
"callee": {
"displayId": "+79219462761",
"forwarderList": [],
"id": "+79219462761"
},
"caller": {
"accountId": "883140582526566",
"centrexId": "48212857",
"displayId": "78005560251",
"forwarderList": [],
"id": "78005560251"
},
"startTime": "2020-06-24 15:01:45",
"state": "trying",
"transportId": "10.133.51.137:5070",
"type": "outgoing"
}
}
}
Сообщение о готовности записи разговора. Запись разговора формируется в виде файла в формате *.mp3, который может быть скачан по указанной в нотификации ссылке. Файл имеет срок хранения, по умолчанию равный 90 дням.
Пример нотификации:
{
"event": "callNotifications",
"result": {
"callInfo": {
"accountId": "883140777446532",
"call": {
"id": "SDvapac01-3bd7d743109f2668f16de50c9ab53559100@127.0.0.1"
},
"state": "recorded",
"urlRecord": "https://openapi-stage.mtt.ru/records/34380859/2020/12/18/9B58D12A_EC9D5E37_56485D37_0EE913E5.mp3"
}
}
}
Описание:
Сообщение о перенаправлении вызова на РМ пользователя МТТ Бизнес.
Пример нотификации:
{
"event": "callNotifications",
"result": {
"callInfo": {
"call": {
"id": "SDfe2n901-b510751695c9e53584301f0c0e8d98c9200@127.0.0.1",
"tag": "sdfe2n901-281028329"
},
"callee": {
"displayId": "+79219462761",
"forwarderList": [],
"id": "+79219462761"
},
"caller": {
"accountId": "883140582526566",
"centrexId": "48212857",
"displayId": "78005560251",
"forwarderList": [],
"id": "78005560251"
},
"startTime": "2020-06-24 15:01:45",
"state": "showing",
"transportId": "10.133.51.137:5070",
"type": "outgoing"
}
}
}
Описание:
Сообщение о соединении вызова с РМ пользователя МТТ Бизнес.
Пример нотификации:
{
"event": "callNotifications",
"result": {
"callInfo": {
"call": {
"id": "SDfe2n901-b510751695c9e53584301f0c0e8d98c9200@127.0.0.1",
"tag": "sdfe2n901-281028329"
},
"callee": {
"displayId": "79219462761",
"forwarderList": [],
"id": "79219462761"
},
"caller": {
"accountId": "883140582526566",
"centrexId": "48212857",
"displayId": "78005560251",
"forwarderList": [],
"id": "78005560251"
},
"startTime": "2020-06-24 15:01:55",
"state": "connected",
"transportId": "10.133.51.137:5070",
"type": "outgoing"
}
}
}
Описание:
Сообщение об окончании вызова на РМ пользователя МТТ Бизнес, например, в случае его перевода на другое РМ.
Пример нотификации:
{
"event": "callNotifications",
"result": {
"callInfo": {
"call": {
"id": "SDfe2n901-b510751695c9e53584301f0c0e8d98c9200@127.0.0.1",
"tag": "sdfe2n901-281028329"
},
"callee": {
"displayId": "+79219462761",
"forwarderList": [],
"id": "+79219462761"
},
"caller": {
"accountId": "883140582526566",
"centrexId": "48212857",
"displayId": "78005560251",
"forwarderList": [],
"id": "78005560251"
},
"startTime": "2020-06-24 15:01:45",
"state": "hiding",
"transportId": "10.133.51.137:5070",
"type": "outgoing"
}
}
}
Описание:
Вызов завершён в рамках ВАТС МТТ Бизнес.
Пример нотификации:
Успешный входящий вызов завершён на стороне пользователя МТТ Бизнес.
{
"event": "callNotifications",
"result": {
"callInfo": {
"call": {
"id": "c166e238a4c211ea9d373863bb43daf8_00015ED635780FC7~2o",
"tag": "hswddry52ykfcb2a____.o"
},
"callee": {
"accountId": "883140777828305",
"centrexId": "67821426",
"displayId": "883140777828305",
"display_name": "74996497803",
"extensionId": "",
"forwarderList": [{
"id": "an_prd100275045-3881851"
},
{
"id": "scheme_prd100275045-3885981"
}
],
"id": "883140777828305"
},
"caller": {
"accountId": "78124241500@pstn",
"displayId": "78124241500",
"forwarderList": [],
"id": "78124241500"
},
"duration": 4,
"reason": "Answer leg disconnected",
"reasonCode": null,
"state": "finished",
"transportId": "10.133.33.136:5073",
"type": "incoming"
}
}
}
Успешный исходящий вызов завершён на стороне вызываемого абонента.
{
"event": "callNotifications",
"result": {
"callInfo": {
"call": {
"id": "SDfe2n901-b510751695c9e53584301f0c0e8d98c9200@127.0.0.1",
"tag": "sdfe2n901-281028329"
},
"callee": {
"displayId": "79219462761",
"forwarderList": [],
"id": "79219462761"
},
"caller": {
"accountId": "883140582526566",
"centrexId": "48212857",
"displayId": "78005560251",
"forwarderList": [],
"id": "78005560251"
},
"duration": 3,
"reason": "Originate leg disconnected",
"reasonCode": null,
"state": "finished",
"transportId": "10.133.51.137:5070",
"type": "outgoing"
}
}
}
- No labels