Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »

Предупреждение

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

Аутентификация OAuth 2.0

 Настройка

Для аутентификации запросов используется протокол OAuth 2.0.
OAuth 2.0 — протокол авторизации, позволяющий выдать одному сервису (приложению) права на доступ к ресурсам пользователя на другом сервисе. Протокол избавляет от необходимости доверять приложению логин и пароль, а также позволяет выдавать ограниченный набор прав, а не все сразу.

Порядок настройки и использования протокола следующий:

  1. Необходимо открыть страницу услуги Открытое API в ЛК МТТБ;
  2. Подключить услугу «Открытое API». При этом осуществляется проверка достаточности необходимых денежных средств, выполняются прочие юридические и административные процедуры, формируются документы для подписания;
  3. Нажать на кнопку Создать в разделе Мои интеграции. Необходимо указать наименование интеграции (цифра 1 на рисунке) и ссылку, на которой будет производиться обработка нотификации по протоколу https (Redirect URI, цифра 2 на рисунке.). Сервер должен иметь соответствующий доверенный сертификат;
  4. Нажать на кнопку Сгенерировать. Произойдёт генерация Секретного ключа и Уникального идентификатора (Id клиента, цифра 3 и 4 на рисунке), а также осуществится проверка доступности данного сервера со стороны решения. Сгенерированные данные, а так же адрес сервиса аутентификации решения (цифра 5 на рисунке) можно удобно скопировать в буфер обмена;
  5. Дальнейшие настройки необходимо провести на стороне стороннего приложения. Ввести в системе Уникальный идентификатор и Секретный ключ из предыдущего шага. Приложение должно произвести первичную авторизацию и отобразить окно ввода учётных данных от ЛК МТТ Бизнес. Если все данные введены верно, решение выдаст приложению два токена: токен доступа (access_token) и токен обновления (refresh_token);
  6. Срок годности токена доступа (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+/oauth2)

scope

Обязательно должен быть установлено значение https://mtt.ru/auth.tokens.readwrite

response_type

Обязательно должен быть установлено значение "code"

state

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

После выполнения запроса, будет выполнен редирект на страницу ввода логина и пароля в ЛК МТТ Бизнес. После успешного подтверждения логина и пароля, будет выполнен редирект на указанный redirect_uri с передачей кода (например: http://localhost:9090/oauth2?code=Yzk5ZDczMzRlNDEwY&state=xyz).
Используя полученный код авторизации, приложение далее сможет выполнить генерацию access_token и refresh_token.

 Запрос токена доступа (access_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+/oauth2)

scope

Обязательно должен быть установлено значение

https://mtt.ru/auth.tokens.readwrite

grant_type

Обязательно должен быть установлено значение "authorization_code"

Параметры ответа:

Параметр

Описание/значение

access_token

Токен доступа

expires_in

Длительность действия в секундах

refresh_token

Токен обновления

scope

Разрешения для токена (

https://mtt.ru/auth.tokens.readwrite

)

token_type

Bearer

Пример ответа:
{
"access_token": "MMRLZJU5NTETMTNHZI0ZNZIYLWJHOTGTNJY1M2ZMM2YZNMYX",
"expires_in": 7200,
"refresh_token": "YWFHNGFHYMQTMTUYMI01ZTM0LTKZM2QTYZU2YZIWNJQ0MJE0",
"scope": "https://mtt.ru/auth/openapi.readwrite",
"token_type": "Bearer"
}

 Обновление токена доступа (access_token)

Описание:

Обменивает вышедший из употребления токен доступа (access_token) на новый путём использования токена обновления (refresh_token).
Параметры:
POST / https://\{{hostoauth}}/oauth/token

Параметр

Описание/значение

client_id

Значение генерируется и задается из ЛК МТТ Бизнес

client_secret

Значение генерируется и задается из ЛК МТТ Бизнес

grant_type

Обязательно должно быть установлено значение "refresh_token"

Параметры ответа:

Параметр

Описание/значение

access_token

Токен доступа

expires_in

Длительность действия в секундах

refresh_token

Токен обновления

scope

Разрешения для токена (

https://mtt.ru/auth.tokens.readwrite

)

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.

Адрес для отправки запроса:

https://openapi.mtt.ru

Параметры:
GET / externalNumbersInfo
Параметры ответа:

Параметр

Описание/значение

total

Общее количество номеров в ответе

numbersList

Массив РМ с их описанием

numbersList / number

Внешний номер

numbersList / type

Тип номера В ВАТС


Пример ответа
{
"result": {
"total": 1,
"numbersList": [{
"number": "78005560251",
"type": null
}]
}
}

 Получение списка рабочих мест в ЛК МТТ Бизнес

Описание:
Получает список РМ ЛС МТТ Бизнес. Для работы используется auth_token в соответствии с протоколом OAuth 2.0.

Адрес для отправки запроса:

https://openapi.mtt.ru

Параметры:
GET / workPlacesInfo
Параметры ответа:

Параметр

Описание/значение

Total

Общее количество РМ в ответе

workplacesList

Массив РМ с их описанием

workplacesList/ name

Наименование РМ

workplacesList/ workplace

SIP ID РМ ВАТС



Пример ответа
{
"result": {
"total": 1,
"workplacesList": [{
"workplace": "883140777716581",
"name": "Администратор"
}]
}

 Получение списка терминалов в ЛК МТТ Бизнес

Описание:
Получение списка терминалов (локаций) ЛС МТТ Бизнес с привязкой к РМ. Для работы используется auth_token в соответствии с протоколом OAuth 2.0.

Адрес для отправки запроса:

https://openapi.mtt.ru

Параметры:
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.

 Инициализация (оригинация) входящего вызова)

Описание:
Производит инициализацию вызова с использованием пользовательского РМ или терминала и вызов указанного в запросе номера. Алгоритм работы ВАТС:

  1. ВАТС инициирует вызов на рабочее место Оператора (параметр callerId).
  2. Дожидается принятия вызова оператором ("поднятия трубки"). Если Оператор не отвечает в течении одной минуты, то дальнейшая работа метода прерывается.
  3. После успешного ответа Оператора, ВАТС инициирует второй исходящий вызов на номер абонента (параметр calleeId) и производит объединение вызовов. 

Необходимо учесть последовательность: второе плечо (вызов на calleeId) осуществляется только после ответа «первого плеча» (SIP ID РМ callerId).

Параметр callerId обычно "подтягивается" из CRM системы по данным текущего рабочего места Оператора настроенного в CRM системе.

Адрес для отправки запроса:

https://openapi.mtt.ru

Параметры:
POST/ makeCall

Параметр

Описание/значение

callerId

SIP ID РМ (не терминала, только РМ) с которого осуществляется вызов. На этот SIP ID будет создано первое плечо. Как только пользователь ответит на вызов, то будет создаваться второе плечо в сторону вызываемого номера.

calleeId

Вызываемый номер (Абонент Б)

Пример запроса:
{
"params": {
"calleeId": "89219462761",
"callerId": "883140582526566"
}
}
Пример ответа:
{
"result": {
"call": {
"id": "7NKe6!8fa1FMSlc6ypZdb1GSV6ZN@10.133.51.137"
},
"success": 1
},
}

 Команда завершения плеча вызова

Описание:
Завершает плечо вызова, что позволяет продолжить обработку по стандартному маршруту, который настроен в ЛК ВАТС МТТ Бизнес. Данной командой можно прекратить «парковку» вызова, так как в момент парковки создаётся дополнительное плечо.

Адрес для отправки запроса:

https://openapi.mtt.ru

Параметры:
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). Данный метод используется для управления вызовами и осуществления альтернативного распределения вызовов, взамен настроенного в ЛК МТТ Бизнес. Возможно два варианта использования:

  • перевод уже отвеченного вызова во время разговора. Пока не ответит номера Абонента Б, в линии будет играть мелодия ожидания.
  • перевод ещё не отвеченного вызова. Вызывающий абонент при этом слышит обычные гудки (КПВ). При реализации кейса "маршрутизация на персонального менеджера", сначала необходимо получить нотификацию с информацией о вызове и затем выполнить данный метод для его перевода на необходимое рабочее место. 

Адрес для отправки запроса:

https://openapi.mtt.ru

Параметры:
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 секунд команды на перенаправление вызова не последовало, то задействуется ранее настроенная для номера логика распределения вызов в ВАТС МТТ Бизнес. При помощи данного метода реализуется кейс «маршрутизация на персонального менеджера».

Адрес для отправки запроса:

https://openapi.mtt.ru

Параметры:
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 – пытаемся дозвониться,
connected – соединен,
finished - закончен,
recorded - записан,
showing - показывается,
hiding - скрывается

callInfo/transportId

Внутренний идентификатор транспорта

callInfo/type

Incoming – входящий,
Outgoing - исходящий

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