Документация по Открытое API

Для аутентификации запросов используется протокол 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

После выполнения запроса, будет выполнен редирект на страницу ввода логина и пароля в ЛК МТТ Бизнес. После успешного подтверждения логина и пароля, будет выполнен редирект на указанный 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+/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) на новый путём использования токена обновления (refresh_token).
Параметры:
POST / https://\{{hostoauth}}/oauth/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"
}

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

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

https://openapi.mtt.ru

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

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

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

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

https://openapi.mtt.ru

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

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

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

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

https://openapi.mtt.ru

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

{
"result": {
"total": 1,
"terminals_list": [{
"terminal": "883140777380595",
"workplace": "883140777380595"
}]
}
}

Описание:
Нотификация об изменении структуры РМ в ЛК МТТ Бизнес.
Параметры нотификации:

Пример нотификации:
{
"event": "vpbxNotifications",
"result": {
"eventType": "numbersChanged"
}
}

Описание:
Нотификация об изменении структуры РМ в ЛК МТТ Бизнес. Возникает при изменении настроек в ЛК МТТ Бизнес.
Параметры нотификации:

Пример нотификации:
{
"event": "vpbxNotifications",
"result": {
" eventType ": "workplacesChanged"
}
}

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

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

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

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

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

https://openapi.mtt.ru

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

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

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

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

https://openapi.mtt.ru

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

Пример запроса:
{
"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

Пример запроса:
{
"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
Параметры нотификации

Пример запроса
{
"params": {
"numbers": ["880023213", "880034344"],
"isParking": true
}
}
Пример ответа
{ "success": 1 }

Описание:
Сообщение о начале входящего вызова.
При поступлении входящего вызова на внешнюю нумерацию пользователя, вызов «паркуется» на 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"
}
}
}

Описание:
Сообщение о перенаправлении вызова на РМ пользователя МТТ Бизнес.
Пример нотификации:
{
"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"
}
}
}