- Created by Матвеев Говард Владимирович, last modified by Шапошникова Евгения Андреевна on Apr 09, 2021
По вопросам подключения/интеграции Telecom API необходимо обратиться по почте api.sale@mtt.ru
В письме просьба указать:
- Интересующий функционал/сервис API
- Контактный номер телефона для обратной связи
Наш менеджер свяжется с Вами в ближайшее время.
Точка подключения: https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
Метод: POST
Описание:
Возвращает историю звонков по конкретному номеру.
Входные массивы:
Name | Type | Description |
sip_id | string | Идентификатор SIP |
date_from | string | Начальная дата (необязательный) |
date_to | string | Конечная дата (необязательный) |
Выходные параметры:
Name | Type | Description |
incoming | array | История входящих звонков |
missed | array | История пропущенных звонков |
dialed | array | История исходящих звонков |
Входные параметры:
Name | Type | Description |
cli | string | А-номер |
cld | string | Номер МТТ либо номер для переадресации (В-номер) |
customer_local_time | string | Время платформы (UTC) |
connect_time | string | Время звонка (UTC) |
charged_time | Integer | Сумма charged_time всех плеч агрегированного вызова, для которых charged_amount > 0 |
charged | Float | Стоимость вызова |
destination | string | Направление вызова |
curr | string | Валюта клиента |
disconnect_cause | Integer | Причина завершения последнего плеча вызова |
used_quantity | Integer | Общее время соединений в ходе сессии, измеряется в секундах |
h323_conf_id | string | Идентификатор записи, по которому можно получить ссылку на скачивание |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
{ "id": "3", "jsonrpc": "2.0", "method": "getCallHistory", "params": { "sip_id": "74996480000", "date_from": "30.10.2019 10:23:35", "date_to": "30.10.2019 22:23:35" } } |
Ответ:
Успешный ответ:
{ "jsonrpc": "2.0", "id": "3", "result": { "incoming": [], "missed": [], "dialed": [ { "cli": "79103880489", "cld": "79103880490", "customer_local_time": "2018-02-06 16:51:17", "connect_time": "2018-02-06 16:51:17", "charged_time": "0", "charged": 0, "destination": "RUSSIAN FEDERATION", "curr": "RUB", "disconnect_cause": "16", "used_quantity":"32", "h323_conf_id": "07A9B59A 05F65003 13B136EE D90263EE" }, { "cli": "79057979388", "cld": "79103880490", "customer_local_time": "2018-02-07 16:50:15", "connect_time": "2018-02-07 16:50:15", "charged_time": "0", "charged": 0, "destination": "RUSSIAN FEDERATION", "curr": "RUB", "used_quantity":"32", "disconnect_cause": "17" "h323_conf_id": "07A9B59A 05F65003 13B136EE D90263EE" } ], "callback": [], "success": 1 } } |
Не успешный ответ:
{ "jsonrpc": "2.0", "id": "3", "error": { "code": -32602, "message": "Invalid params", "data": "Invalid begin date" } } |
Не успешный ответ (неправильный SIP id):
{ "jsonrpc": "2.0", "id": "3", "error": { "code": -32001, "message": "Data not found", "data": "No data found" } } |
Описание:
Возвращает историю звонков, по всему лицевому счету (по всем номерам).
Входные параметры:
Name | Type | Description | |||||||||||||||
type* | string |
| |||||||||||||||
customer_name* | string | customer_name | |||||||||||||||
date_from* | string | Начальная дата и время (YYYY-MM-DD HH24:Mi-SS) | |||||||||||||||
date_to* | string | Конечная дата и время (YYYY-MM-DD HH24:Mi-SS) | |||||||||||||||
filter | string | Номер, для фильтрации вызовов по "cli" и "cld" | |||||||||||||||
order | string | Сортировка - возможные значения desc (по умолчанию) и asc | |||||||||||||||
record_count* | int | Количество возвращаемых записей (не более 1000) |
* обязательные параметры
Выходные массивы:
Name | Type | Description |
incoming | array | История входящих звонков |
missed | array | История пропущенных звонков |
dialed | array | История исходящих звонков |
forwarded | array | История переадресованных вызовов |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Необязательные параметры:
При отсутствующих параметрах date_from и date_to будут выданы результаты работы за полчаса от текущего момента.
В любом случае, количество строк в результате будет ограниченно 1000.
Выходные параметры:
Name | Type | Description |
cli | string | А-номер |
cld | string | Номер МТТ либо номер для переадресации (В-номер) |
customer_local_time | string | Время платформы |
connect_time | string | Время звонка |
charged_time | Integer | Сумма charged_time всех плеч агрегированного вызова, для которых charged_amount > 0 |
charged | Float | Стоимость вызова |
destination | string | Направление вызова |
h323_conf_id | string | Идентификатор записи, по которому можно получить ссылку на скачивание |
h323_incoming_conf_id | string | Идентификатор записи входящего вызова, h323_conf_id в массиве incoming |
curr | string | Валюта клиента |
disconnect_cause | Integer | Причина завершения последнего плеча вызова |
setup_time_ms | Integer | время установления соединения в мс |
account_id | string | Номер клиента, номер МТТ |
used_quantity | Integer | Общее время соединений в ходе сессии, измеряется в секундах |
h323_conf_id | string | Идентификатор записи, по которому можно получить ссылку на скачивание |
| Boolean | Наличие записанного разговора, |
cli - в общем случае телефонный номер с которого поступил вызов, cld - номер на который поступил вызов.
В общем случае, за исключением forwarded, account_id и cli будут совпадать.
В случае forwarded в cli будет номер с которого поступил звонок переадресованный на номер cld.
Пример:
Запрос:
JSON:
|
Ответ:
Успешный ответ:
|
Не успешный ответ:
|
Комментарий:
cli - откуда
cld - куда
Коды причины ISUP |
== 1= unallocated number |
== 2= no route to network |
== 3= no route to destination |
== 16 normal call clearing |
== 17 user busy |
== 18 no user responding |
== 19 no answer from the user |
== 20 subscriber absent |
== 21 call rejected |
== 22 number changed (w/o diagnostic) |
== 22 number changed (w/ diagnostic) |
== 23 redirection to new destination |
== 26 non-selected user clearing |
== 27 destination out of order |
== 28 address incomplete |
== 29 facility rejected |
== 31 normal unspecified |
Ресурсы недоступны |
== 34 no circuit available |
== 38 network out of order |
== 41 temporary failure |
== 42 switching equipment congestion |
== 47 resource unavailable |
Сервис или опция недоступны. |
Этот вид событий указывает, что имеются временные проблемы при обработке запроса, которые оборудование самостоятельно устранит через какое-то время. |
== 55 incoming calls barred within CUG |
== 57 bearer capability not authorized |
== 58 bearer capability not presently |
available |
== 65 bearer capability not implemented |
== 70 only restricted digital avail |
== 79 service or option not implemented |
Неверное сообщение |
== 87 user not member of CUG |
== 88 incompatible destination |
Ошибка протокола |
== 102 recovery of timer expiry |
== 111 protocol error |
Взаимодействие с другими сетям |
== 127 interworking unspecified |
Интерфейс взаимодействия - REST API.
Аутентификация - Basic Auth.
Метод: Get
Пример запроса для получения ссылки на запись разговора в формате wav:
https://rc.mtt.ru/v1/records/<h323_conf_id>/urls
Пример запроса для получения ссылки на запись разговора в формате mp3 необходимо обращаться на отличающийся от стандартного URL:
https://rc.mtt.ru/v2/records/<h323_conf_id>/urls?format=mp3
, где h323_conf_id - параметр h323_conf_id разговора, который можно получить в результатах получения статистики 'getCallHistory' и 'getServiceHistoryByCustomer'.
Пример запроса:
https://rc.mtt.ru/v1/records/0000B3A4_55F311E4_A2420025_9062EDC4/urls
Пример ответа (JSON):
[
]
Это прямая ссылка на скачивание файла.
В ситуациях определяемых вендором (в зависимости от размера записи или при логических действиях со звонком), один вызов может быть поделен на несколько записей, в таком случае ответ будут выглядеть следующим образом:
[
"http://rs.mtt.ru/%/AA7C6C7E_932911E9_B87E5CB9_01FED6FC_1.wav",
"http://rs.mtt.ru/%/AA7C6C7E_932911E9_B87E5CB9_01FED6FC_2.wav"
]
Точка подключения: https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
Метод: POST
Описание:
Обновляет список номеров, на которые будет осуществляться переадресация вызова.
Входные параметры:
Name | Type | Description |
sid_id | string | Идентификатор SIP |
followmeStruct | array of followmeStruct | Структуру followmeStruct см. ниже в примере успешного запроса |
followmeStruct:
Name | Type | Description |
timeout | string | Таймаут (в секундах) |
redirect_number | string | Номер для перенаправления вызова. Формат номера РФ:Е.164 без "+", н-р, 74951234567 |
name | string | Символьное имя номера для перенаправления вызова |
active | string | Активность (Y/N) |
period | string | Период (дни недели и диапазон времени) активности перенаправления на данный номер |
period_description | string | Описание периода перенаправления вызова |
follow_order | string | Порядок следования номера при перенаправлении вызова |
domain* | string | Домен |
use_tcp* | string | Использовать TCP (Y/N) |
keep_original_cli* | string | Отображение АОН звонящему (Y/N/I) Y - отображение реального номера звонящего (по умолчанию) N - отображение в качестве номера звонящего sip_id I - отображение реального номера звонящего, используется при настроенной схеме (на стороне МТТ) проигрывания приветственного/информационного сообщения (Premedia) для звонящего/принимающего вызов абонента. |
keep_original_cld* | string | Оставлять оригинальный CLD (Y/N) |
* - необязательные параметры
Выходные параметры:
Name | Type | Description |
success | number | 1 = список успешно обновлён |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
{ "id": "1", "jsonrpc": "2.0", "method": "setFollowme", "params": ["74951345897", [ { "timeout": 15, "redirect_number": "79684881033", "name": "79684881033", "active": "Y", "period": "always", "period_description": "Always", "follow_order": 1 }, { "timeout": 15, "redirect_number": "79636793312", "name": "79636793312", "active": "Y", "period": "always", "period_description": "Always", "follow_order": 2 } ] ] } |
Ответ:
Успешный ответ:
{ "jsonrpc": "2.0", "id": "1", "result": { "success": 1 } } |
Не успешный ответ:
// при вызове с несуществующим SIP ID
{ "jsonrpc": "2.0", "id": "1", "error": { "code": -32001, "message": "Data not found" } } // У агента нет доступа к аккаунта { "jsonrpc": "2.0", "id": "1", "error": { "code":-32002, "message":"Permission denied", "data":"You can not access to this sip_id" } } |
Описание:
Возвращает список номеров для переадресации вызовов.
Входные параметры:
Name | Type | Description |
sip_id | string | Идентификатор SIP |
Выходные параметры:
Name | Type | Description |
followme_struct | array of followmeStruct | followmeStruct содержит номер для переадресации вызова и временной интервал, в котором эта переадресация работает |
followmeStruct:
Name | Type | Description |
I_FOLLOW_ORDER | string | Порядок следования номера при перенаправлении вызова |
ACTIVE | string | Активность (Y/N) |
NAME | string | Символьное имя номера для перенаправления вызова |
REDIRECT_NUMBER | string | Номер для перенаправления вызова |
PERIOD | string | Период (дни недели и диапазон времени) активности перенаправления на данный номер |
PERIOD_DESCRIPTION | string | Описание периода перенаправления вызова |
TIMEOUT | string | Таймаут (в секундах) |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
{ "id": "1", "jsonrpc": "2.0", "method": "getFollowme", "params": ["74951345987"] } |
Ответ:
Успешный ответ:
{ "jsonrpc": "2.0", "id": "1", "result": { "sip_id": "883140776011039", "i_account": "44635974", "followme_struct": [ 3, [ { "I_FOLLOW_ORDER": "1", "ACTIVE": "Y", "NAME": "79684881033", "REDIRECT_NUMBER": "79684881033", "PERIOD": "hr{9}min{0-59}wd{mo-fr},hr{10}min{0-58}wd{mo-fr}", "PERIOD_DESCRIPTION": "hr{9}min{0-59}wd{mo-fr},hr{10}min{0-58}wd{mo-fr}", "TIMEOUT": "15" }, { "I_FOLLOW_ORDER": "2", "ACTIVE": "Y", "NAME": "79684881034", "REDIRECT_NUMBER": "79684881034", "PERIOD": "hr{11}min{0-59}wd{mo-fr},hr{12}min{0-58}wd{mo-fr}", "PERIOD_DESCRIPTION": "hr{11}min{0-59}wd{mo-fr},hr{12}min{0-58}wd{mo-fr}", "TIMEOUT": "15" }, { "I_FOLLOW_ORDER": "3", "ACTIVE": "Y", "NAME": "79684881035", "REDIRECT_NUMBER": "79684881035", "PERIOD": "hr{13}min{0-59}wd{mo-fr},hr{14-17}wd{mo-fr},hr{18}min{0-58}wd{mo-fr}", "PERIOD_DESCRIPTION": "hr{13}min{0-59}wd{mo-fr},hr{14-17}wd{mo-fr},hr{18}min{0-58}wd{mo-fr}", "TIMEOUT": "15" } ] ] } } |
Не успешный ответ:
// не установлено ни одной переадресации { "jsonrpc": "2.0", "id": "1", "error": { "code": -32001, "message": "Data not found", "data": "No followMe on this account" } }
// Аккаунт не существует { "jsonrpc": "2.0", "id": "1", "error": { "code": -32001, "message": "Data not found", "data": "This account does not exist" } }
// У агента нет доступа к аккаунта { "jsonrpc": "2.0", "id": "1", "error": { "code":-32002, "message":"Permission denied", "data":"You can not access to this sip_id" } } |
Точка подключения: https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
Метод: POST
Описание:
Данная функция возвращает баланс кастомера.
Входные параметры:
Name | Type | Description |
customer_name* | String | Имя существующего кастомера = лицевой счет |
Выходные параметры:
Name | Type | Description |
balance | numeric | Баланс кастомера |
real_balance | numeric | Полный баланс кастомера |
pending_payment |
* Обязательные поля
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
|
Ответ:
Успешный ответ:
|
Не успешный ответ:
|
Точка подключения: https://webapicommon.mtt.ru/index.php
Описание:
Данная функция осуществляет вывод аккаунтов/номеров с лицевого счета
Входные параметры:
Name | Type | Description |
customer_name | string (41) | Лицевой счет |
limit | number | Количество возвращаемых аккаунтов |
offset | number | Смещение |
Выходные параметры:
Name | Type | Description |
account_number | string | Номер, вывод отсоритирован в порядке возрастания |
activation_date | string | Дата активации |
status | string | Статус номера, например "active" |
Авторизация:
Авторизация осуществляется штатными средствами HTTP
Пример:
Запрос:
JSON:
|
Ответ:
Успешный ответ:
|
Не успешный ответ:
|
«Услуга CallBack API»
Функционал позволяет по API:
- Осуществить быстрый дозвон и соединение требуемых номеров A (клиент) и B (пользователь);
- Вызывать сразу несколько номеров клиента (персональных менеджеров) с необходимой логикой дозвона: последовательно, параллельно, рандомно;
- Проиграть аудиосообщение или синтезированный текст в сторону клиента (персонального менеджера), так и в сторону абонента заказавшего звонок (пользователя) при снятии трубки;
- Записать разговор клиента и пользователя, записывается разговор по обоим плечам;
- Задать максимально возможную длительность разговора клиента и пользователя;
- Получать online уведомления о ходе вызова;
- Настроить свой собственный сервис CallBack на базе предоставляемого функционала.
Точка подключения: https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
Метод: POST
Описание:
Данная функция осуществляет callback между А-номером или номерами переданным в поле simpleCallBackFollowmeStruct и B-номером.
Входные параметры:
Name | Type | Description |
id | string | id, маркер запроса, будет выдан в ответе на запрос. |
customer_name* | string | Аккаунт CallBack, выдается МТТ |
b_number* | string | Номер плеча B (по умолчанию). Номер, на который будет совершён звонок, по фактическому ответу плеча A. |
caller_id | string | Номер, который будет показан абоненту плеча В. Данный параметр должен устанавливаться, либо в функции setCallBackFollowme либо в функции makecallbackfollowme. |
callBackURL | string | URL, на который, будут посылаться уведомления о ходе вызова. Строго без http/www. Конечный файл, куда будут отправляться events должен называться event.php |
simpleCallBackFollowmeStruct | array of simpleCallBackFollowmeStruct | Структуру simpleCallBackFollowmeStruct см. в примере успешного запроса |
recordEnable | number | Запись звонка. По умолчанию - 1. Записывается. |
duration | number | Общая продолжительность попытки вызова (сек.) |
client_caller_id | string | Номер, который будет показан абоненту плеча A. По умолчанию - b_number |
direction | numberr | Значение 0 или 1. Направление вызова. По умолчанию 0 - redirect_number (Плечо А)-->b_number (плечо B), 1 - b_number (плечо А)-->redirect_number (Плечо B) |
callDescription | string | Комментарий к вызову. |
dtmf_number | string | Дополнительный номер при наборе. |
maxtime | string | Указывается в секундах. Суммарная максимальная длительность разговора по плечу А и по плечу B. По истечении заданного времени CallBack будет завершен. |
* обязательные поля
simpleCallBackFollowmeStruct:
Name | Type | Description |
order | number |
|
timeout | number | Таймаут (в секундах)- время дозвона с момента отправки Json запроса на осуществление вызова до прекращения дозвона. Рекомендуется устанавливать значение от 15 секунд. |
redirect_number | string | Номер плеча А, по умолчанию. |
type | string | Тип очереди, файла, текста, etc |
name | string | Символьное имя номера для перенаправления вызова |
|
| Плечо для проигрывания файла или сообщения (А или В) |
|
|
|
Выходные параметры:
Name | Type | Description |
callBackCall_id | string | Уникальный идентификатор вызова |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример запроса с ранее установленной структурой вызова (см. setCallBackFollowme):
JSON:
{ "id": "1", "jsonrpc": "2.0", "method": "makeCallBackCallFollowme", "params": { "customer_name" : "883140500000000", "b_number" : "+79157775533" } } |
Пример запроса без предварительной установки структуры вызова - функцией setCallbackfollowme, передача структуры simpleCallBackFollowmeStruct в теле запроса makeCallBackCallFollowme:
JSON:
{
"id": "1",
"jsonrpc": "2.0",
"method": "makeCallBackCallFollowme",
"params": {
"customer_name": "883140500000000",
"b_number": "7xxxxxxx",
"callBackURL": "example.com", - СТРОГО без http/www
"caller_id" : "7xxxxxxxxxx",
"recordEnable" : 1,
"client_caller_id" : "7xxxxxxxxxx",
"simpleCallBackFollowmeStruct": [
{
"order": 1,
"timeout": 25,
"redirect_number": "7xxxxxxxxxx",
"caller_id": "7xxxxxxxxxx",
"type": "ringall",
"name": "sales"
},
{
"order": 2,
"timeout": 25,
"redirect_number": "7xxxxxxxxxx",
"caller_id": "7xxxxxxxxxx",
"type": "ringall",
"name": "sales_2"
},
{
"order": 3,
"type": "text", - задается "Text to speech"( текст в речь)
"value": "Звонок с сайта все продам ру",
"side": "A"
},
{
"order": 4,
"type": "file", - задается ранее установленный файл в функции "SetCallBackPrompt"
"value": "for_all_sales",
"side": "B"
}
]
}
}
Успешный ответ:
{
"jsonrpc": "2.0",
"id": "1",
"result":
{
"callBackCall_id": "1256ffb10774226b390ad1a2bc892c9c"
}
}
Не успешный ответ:
{ "jsonrpc":"2.0", "id":"iar_ringall", "result": { "error":1, "message":"Incorrect redirect_number format" - указан некорректный А - номер ( redirect_number) "message" : "Incorrect B-number format"- указан некорректный B-номер. } } |
Описание:
Данная функция позволяет получить информацию об осуществленном CallBack вызове по его идентификатору.
Входные параметры:
Name | Type | Description |
customer_name | string | Имя Кастомера, созданного в функции |
callBackCall_id | string | Уникальный идентификатор вызова |
Выходные параметры:
Name | Type | Description |
callBackFollowmeCallInfoStruct | array of callBackFollowmeCallInfo | Структуру callBackFollowmeCallInfo см. ниже в примере успешного запроса |
callBackFollowmeCallInfo:
Name | Type | Description |
destination_A | string | Номер, куда дозвонилось плече А |
destination_B | string | Номер, куда дозвонилось плече В |
waiting_period_A | string | Период ожидания плеча А |
waiting_period_В | string | Период ожидания плеча В |
call_back_charged_length_A | string | Длительность вызова плеча А (биллинговая) |
call_back_real_length_A | string | Длительность вызова плеча А (реальная) |
call_back_charged_length_B | string | Длительность вызова плеча B (биллинговая) |
call_back_real_length_B | string | Длительность вызова плеча B (реальная) |
call_back_cost | number | Стоимость вызова |
call_back_status | string | Статус вызова |
call_back_record_URL_A | array | URL для получения записи вызова плеча А (срок действия ссылки 60 сек) |
call_back_record_URL_B | array | URL для получения записи вызова плеча В (срок действия ссылки 60 сек) |
callDescription | string | Комментарий к вызову |
Авторизация:
Авторизация осуществляется штатными средствами HTTP
Пример:
Запрос:
JSON:
|
Ответ:
Успешный ответ:
{
"jsonrpc": "2.0",
"id": "1",
"result":
{
"callBackFollowmeCallInfoStruct":
{
"destination_A": "+79162795520",
"destination_B": "+79852970306",
"waiting_period_A": "12",
"waiting_period_B": "9",
"call_back_charged_length_A": "60",
"call_back_real_length_A": "15",
"call_back_charged_length_B": "60",
"call_back_real_length_B": "5",
"call_back_cost": 2.98,
"call_back_currency": "RUB",
"call_back_status": "ok",
"call_back_record_URL_A":
{
"downloadURL": "http:\/\/fuds.mtt.ru\/download\/75GV5LxVNdQuohMge0NMFpS2Oxwc3jKTmhjWE3987oPTOhCJ7o"
},
"call_back_record_URL_B":
{
"downloadURL": "http:\/\/fuds.mtt.ru\/download\/0bbDerTSCQFVmqzOdFu6pNX1STQCh5dTrdQ3PdajN3ICHdWyyV"
},
"callDescription": ""
}
}
}
Вызов закончился по timeout на стороне А:
{ "jsonrpc":"2.0",
"id":"101",
"error":
{
"code":-32001,
"message":"Data not found",
"data":"Call ended by timeout on side A"
}
}
Вызов отбит на стороне А:
{
"jsonrpc":"2.0",
"id":"101",
"error":
{
"code":-32001,
"message":"Data not found",
"data":"Call ended by cancel on side A"
}
}
Вызов отбит на стороне B:
{
"jsonrpc":"2.0",
"id":"101",
"error":
{
"code":-32001,
"message":"Data not found",
"data":"Call ended by cancel on side B"
}
}
Описание:
Данная функция позволяет получить данные для загрузки файла CallBack prompt.
Входные параметры:
Name | Type | Description |
customer_name* | string | Имя Кастомера |
file_name | string | (Максимум 255 символов) |
Выходные параметры:
Name | Type | Description |
uploadURL | string | Адрес для загрузки файла (POST) |
statusURL | string | Адрес для проверки состояния загрузки (POST) |
maxsize | number | Максимально разрешенный размер файла в байтах |
accepted_formats | object | Допустимые расширения файлов и их MIME типы |
Для загрузки файла клиент должен отправить содержимое файла посредством POST запроса на сформированный uri для загрузки файла. В теле POST данных необходимо передавать только контент файла и ничего более. В результате будет выдан ответ в виде json объекта c полем status имеющем одно из следующих значений:
- wait_porta_upload - файл принят и ожидает загрузки на porta;
- error_maxfilesize - в случае превышения максимального размера файла;
- error_fileformat - в случае несоответствия формата файла ожидаемому;
- error_not_found - в случае если запрос на загрузку файла не найден в БД;
- error_invalid_state - в случае если запрос на загрузку файла находится в состоянии отличном от wait_client_upload;
- error_internal - в случае, если произошла внутренняя ошибка сервиса.
Для проверки состояния загрузки файла клиент должен отправить GET запрос на сформированный uri для проверки статуса загрузки файла. В результате будет выдан ответ в виде json объекта c полем status имеющем одно из следующих значений:
- ok - файл загружен;
- wait_client_upload - ожидается загрузка файлов от клиента;
- wait_upload - файл принят и ожидает загрузки;
- error_maxfilesize - при принятии файла от клиента обнаружено превышение максимального размера файла;
- error_fileformat - при принятии файла от клиента обнаружено несоответствие формата файла ожидаемому;
- error_upload - загрузка файлапо каким-то причинам оказалась неуспешной;
- error_timout - истекло время ожидания загрузки файла от клиента.
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
|
Ответ:
Успешный ответ:
|
Не успешный ответ:
|
Описание:
Данная функция позволяет получить список загруженных клиентом промтов.
Входные параметры:
Name | Type | Description |
customer_name | string | Имя Кастомера |
Выходные параметры:
Name | Type | Description |
result | array | Список загруженных клиентом промптов и дат их загрузки. |
result:
Name | Type | Description |
file_name | string | Имя файла, содержащего загруженный промпт |
date_upload | string | Дата загрузки промпта |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
{ "id": "1", "jsonrpc": "2.0", "method": "getCallBackPromptInfo", "params": { "customer_name" : "883140500000000" } } |
Ответ:
Успешный ответ:
{ : "jsonrpc":"2.0", : "id":"1", : "result": : [ : : { : : : "file_name":"01_mamita_surumi.wav", : : : "date_upload":"12.08.2015" : : }, : : { : : : "file_name":"Enchantment.wav", : : : "date_upload":"12.08.2015" : : } : ] } |
Не успешный ответ:
{ "jsonrpc":"2.0", "id":"101", "error": { "code":-32001, "message":"Data not found", "data":"Error on get CallBack Prompt Info" } } |
Описание:
Данная функция создает список номеров, на которые будет осуществляться переадресация CallBack вызова, плечо А.
Предварительная установка структуры вызова (callBackFollowmeStruct).
Входные параметры:
Name | Type | Description |
customer_name* | string | Имя Кастомера, созданного в функции |
callBackFollowmeStruct* | array of callBackFollowmeStruct | Структуру callBackFollowmeStruct см. ниже в примере успешного запроса |
caller_id | string | Номер, который будет показан абоненту плеча В. Данный параметр должен устанавливаться, либо в функции setCallBackFollowme либо в функции makecallbackfollowme. |
defaultBNumber | string | Номер по умолчанию, для дозвона на плечо B |
callBackFollowmeStruct:
Name | Type | Description |
order | number | Порядок следования номера при перенаправлении(переадресации) вызова |
timeout | number | Таймаут (в секундах)- время дозвона с момента отправки Json запроса на осуществление вызова до прекращения дозвона. Рекомендуется устанавливать значение от 10 секунд. |
redirect_number | string | Номер для перенаправления вызова (реальный номер, который будет осуществлен вызов. Плечо А.) |
type | string | Тип очереди, файла, текста. |
name | string | Символьное имя номера для перенаправления вызова, например "sales1"/"sales2"/"boss" |
side | string | Плечо для проигрывания файла или сообщения (А или В) |
value | string | Информация для проигрывания или имя файла |
Пояснения к параметру "type"
1) Тип очереди:
Ringall - вызываются все участники структуры, переданные в callBackFollowmeStruct (плечо А) ;
Lineral - вызов участников группы ( плечо А), переданных в callBackFollowmeStruct, происходит последовательно.
2) Тип проигрываемого сообщения для плеча А/B:
"type": "text", - задается "Text to speech"(текст в речь);
"type": "file", задается ранее установленный файл в функции "SetCallBackPrompt".
Выходные параметры:
Name | Type | Description |
success | number | 1 = Структура успешно добавлена |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
|
Ответ:
Успешный ответ:
|
Не успешный ответ:
|
Описание:
Данная функция позволяет получить список номеров, на которые будет осуществляться переадресация CallBack вызова, плечо А.
Вывод предварительно установленной структуры вызова setCallBackFollowme.
Входные параметры:
Name | Type | Description |
customer_name | string | Имя Customer |
callBackFollowmeStruct:
Name | Type | Description |
order | number | Порядок следования номера при перенаправлении вызова |
timeout | number | Таймаут (в секундах) |
redirect_number | string | Номер для перенаправления вызова |
type | string | Тип очереди, файла, текста, etc |
name | string | Символьное имя номера для перенаправления вызова |
side | string | Плечо для проигрывания файла или сообщения (А или В) |
value | string | Информация для проигрывания или имя файла |
Выходные параметры:
Name | Type | Description |
callBackFollowmeStruct | array of callBackFollowmeStruct | Структуру callBackFollowmeStruct см. ниже в примере успешного запроса |
caller_id | string | Номер, который будет показан абоненту плеча В |
defaultBNumber | string | Номер по умолчанию, для дозвона на плечо B |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
{ "id": "101", "jsonrpc": "2.0", "method": "getCallBackFollowme", "params": { "customer_name" : "883140500000000"} } |
Ответ:
Успешный ответ:
{ "jsonrpc": "2.0", "id": "101", "result": { "callBackFollowmeStruct": [ { "order": 1, "timeout": 25, "redirect_number": "79684881033", "type":"ringall", "name": "sales" }, { "order": 2, "timeout": 25, "redirect_number": "79522222222", "type":"ringall", "name": "sales" }, { "order": 3, "timeout": 25, "redirect_number": "79152323233", "type":"ringall", "name": "sales" }, { "order": 4, "timeout": 15, "redirect_number": "79636793312", "type":"lineral", "name": "sales_chief" }, { "order": 5, "timeout": 20, "redirect_number": "79631112233", "type":"lineral", "name": "chief" } ], "caller_id": "74951001010", "defaultBNumber" : "79889998877" } } |
Не успешный ответ:
{ "jsonrpc": "2.0", "id": "101", "error": { "code": -32602, "message": "Invalid params", "data": "Invalid type" } } |
Описание:
Данная функция удаляет список номеров, на которые будет осуществляться переадресация CallBack вызова, плечо А.
Входные параметры:
Name | Type | Description |
customer_name | string | Имя Кастомера |
Выходные параметры:
Name | Type | Description |
success | number | 1 = список успешно удален |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
{ "id": "1", "jsonrpc": "2.0", "method": "deleteCallBackFollowme", "params": { "customer_name":"883140500000000" } } |
Ответ:
Успешный ответ:
{ "jsonrpc": "2.0", "id": "1", "result": { "success": 1 } } |
Не успешный ответ:
{ "jsonrpc": "2.0", "id": "1", "error": { "code": -32001, "message": "Data not found", "data": "Followme not found" } } |
Уведомления о ходе вызова
2015/08/13 11:45:26 http://xxx.xxx.xxx.xxx/listener/event.php?event=start_side_A&id=e031c89159fbba8b80025cd6fb534a77 2015/08/13 11:45:28 http://xxx.xxx.xxx.xxx/listener/event.php?event=pickup_side_A&id=e031c89159fbba8b80025cd6fb534a77&phone_A=+номер телефона, поднявший трубку ( плечо А) 2015/08/13 11:45:28 http://xxx.xxx.xxx.xxx/listener/event.php?event=start_side_B&id=e031c89159fbba8b80025cd6fb534a77 2015/08/13 11:45:32 http://xxx.xxx.xxx.xxx/listener/event.php?event=start_talk&id=e031c89159fbba8b80025cd6fb534a77 2015/08/13 11:45:36 http://xxx.xxx.xxx.xxx/listener/event.php?event=end_side_B&id=e031c89159fbba8b80025cd6fb534a77 2015/08/13 11:45:36 http://xxx.xxx.xxx.xxx/listener/event.php?event=end_side_A&id=e031c89159fbba8b80025cd6fb534a77 |
start_side_A - инициация вызова на плечо А
pickup_side_A - абонент плеча А снял трубку
start_side_B - инициация вызова на плечо B
event=start_talk - разговор между абонентами
event=end_side_B/event=end_side_A - окончание разговора по плечу B и А
Описание: функционал позволяет клиенту, в момент поступления звонка от пользователя:
- получать от платформы МТТ запрос к API клиента по арендованному номеру, для получения номера переадресации;
- осуществить онлайн перенаправление входящего вызова на полученный от API клиента номер телефона;
- проиграть информационное сообщение звонящему пользователю так и принимающему вызов клиенту;
- отбить входящий вызов, при необходимости проиграть информационное сообщение перед отбоем;
- получать онлайн уведомления (Events) в ходе вызова;
- менять URL API клиента при необходимости;
- резервировать настройки переадресации при недоступности клиентского URL.
В момент входящего вызова на номер клиента платформа МТТ производит POST запрос (c ip - 80.75.132.186) к API клиента методом getControlCallFollowMe по полученному номеру.
Пример POST запроса к API клиента:
{
"id": "1",
"jsonrpc": "2.0",
"method": "getControlCallFollowMe",
"params":
{
"sip_id": " 79586488002",
"numberA": "79154368886",
"h323_conf_id": "BC5F236C 5AD211E9 81BA5CB9 01FED6FC"
}
}
Входные параметры:
Response
Name | Type | Description |
sip_id | string | номер клиента по которому запрашивается алгоритм переадресации вызова. Формат номера 7+10 цифр (E.164), всегда |
numberA | string | оригинальный А-номер РФ, номер с которого поступил вызов на "sip_id". Формат номера, тот который пришел на сеть МТТ, может быть и +7/8/7 + 10 цифр |
h323_conf_id | string | Уникальный id звонка на платформе МТТ |
Пример ответа от API клиента:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"redirect_type": 1,
"event_URL": "http://домен/stub.php",
"client_id": "1235",
"file_to_A": "47f51cac1b50fd136334697b11aa406a",
"file_to_B": "3806efe36d0f1bfccb45ffae8e152c7c",
"followme_struct": [1, [
{
"I_FOLLOW_ORDER": "1",
"ACTIVE": "Y",
"NAME": "79684881033",
"REDIRECT_NUMBER": "79684881033",
"PERIOD": "always",
"PERIOD_DESCRIPTION": "always",
"TIMEOUT": "15"
} ]]
}
}
Должен соответствовать нотации JsonRPC.
Выходные параметры:
Response
Name | Type | Description |
redirect_type* | int | Тип переадресации 1 - одиночная, 2- последовательная, 3- параллельная |
followme_struct* | структура | Структура с параметрами и номерами переадресации (REDIRECT_NUMBER) |
event_URL | string | URL для отправки онлайн уведомлений о ходе звонка* |
client_id | string | Сквозной идентификатор вызова от API клиента |
file_to_A | string | Аудио сообщение в сторону звонящего пользователя, при отсутствии параметра аудио сообщение проигрываться не будет. file_id, получаемый методом getCustomerPrompts, ранее загруженного промта через API метод createCustomerPrompt, см. пункт "Premedia API" |
file_to_B | string | Аудио сообщение в сторону принимающего вызов клиента, при отсутствии параметра аудио сообщение проигрываться не будет. file_id, получаемый методом getCustomerPrompts, ранее загруженного промта через API метод createCustomerPrompt, см. пункт "Premedia API" |
followme_struct
Name | Type | Description |
I_FOLLOW_ORDER | string | Порядок следования номера при перенаправлении вызова |
ACTIVE | string | Активность (Y/N), Y - вызов пройдет на REDIRECT_NUMBER, N - вызов отобьется. |
NAME | string | Символьное имя номера для перенаправления вызова |
REDIRECT_NUMBER | string | Номер для перенаправления вызова |
PERIOD | string | Always |
DTMF | string | Ввод добавочного номера. Список возможных символов: 0-9,*#,w,W. w - пауза на пол секунды, W - пауза на одну секунду. Пример: "WWW1W3151#" - после ответа IVR клиента, через 3 секунды будет отправлена цифра "1", далее через 1 секунду отправлена последовательность из 4-х цифр "3151", # - символ окончания ввода. |
PERIOD_DESCRIPTION | string | Описание периода перенаправления вызова |
TIMEOUT | string | Таймаут (в секундах), время ожидания ответа. |
* Обязательные параметры
Запрос к API клиента отправляется на URL, структура: <схема>://<логин>:<пароль>@<хост>:<порт>/<URL-путь>
В данном случае:
- в качестве схемы могут быть использованы протоколы http/https;
- в качестве логина/пароля будут переданы реквизиты аутентификации;
- хост - доменное имя или IP-адрес сервера API клиента;
- порт 80/443.
Получив ответ от API клиента, МТТ переводит вызовы согласно полученным параметрам переадресации.
Отбой входящего вызова
Для отбоя входящего звонка необходимо использовать след. структуру, пример:
{
"jsonrpc": "2.0",
"id": "12345",
"result": {
"redirect_type": 1,
"followme_struct": [1, [{
"ACTIVE": "N"
}]]
}
}
либо структуру с REDIRECT_NUMBER и "ACTIVE": "N", пример:
{
"jsonrpc": "2.0",
"id": "12345",
"result": {
"redirect_type": 1,
"followme_struct": [1, [{
"I_FOLLOW_ORDER": 1,
"ACTIVE": "N",
"NAME": "имя",
"REDIRECT_NUMBER": "номер",
"PERIOD": "always",
"PERIOD_DESCRIPTION": "Always",
"TIMEOUT": "30"
}]]
}
}
Причем, если в ответе присутствует параметр "file_to_A", пример:
{
"jsonrpc": "2.0",
"id": "12345",
"result": {
"redirect_type": 1,
"file_to_A": "3d221eb1aadf4d035bd87891abc82de7",
"event_URL": "https://url/events/prod.php",
"followme_struct": [1, [{
"ACTIVE": "N"
}]]
}
}
то перед отбоем входящего вызова, звонящий абонент услышит информационное сообщение (например: "номер не используется") - file_to_A.
Предлагаем использовать данную структуру на неактивных номерах (без REDIRECT_NUMBER ).
Изменение клиентского URL
Клиент самостоятельно по средствам API может сменить URL для приема запроса getControlCallFollowMe, описание метода API:
Описание:
Данный метод позволяет установить или обнулить URL.
Точка входа : https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
POST запрос
Входные параметры:
Name | Type | Description |
sip_id | string | sip_id аккаунта, для обнуления передается пустое значение |
url | string | Строка содержащая url, для обнуления передается пустое значение |
Выходные параметры:
Name | Type | Description |
success | number | Индикатор успеха |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
{ "id": "1", "jsonrpc": "2.0", "method": "updateCallControlURL", "params": { "sip_id":"73432143178", "url":"" } } |
Ответ:
Успешный ответ:
{ "jsonrpc": "2.0", "id": 1, "result": { "success":1 } } |
Не успешный ответ:
{ "jsonrpc": "2.0", "id": "1", "error": { "code": -32002, "message": "Permission denied", "data": "agent does not have access to this account" } } |
Events уведомлений о ходе вызова
1. Инициация вызова на REDIRECT_NUMBER
{
"date_time": 1558613711,
"data": "event=o_79684881033_2019-05-23-15-15-11",
"event": {
"type": "o"
},
"redirect_number": "79684881033",
"h323_conf_id": " BC5F236C 5AD211E9 81BA5CB9 01FED6FC ",
"numberA": "79154368886",
"sip_id": "79586488002",
"client_id ": "1235"
}
2. REDIRECT_NUMBER снял трубку
{
"date_time": 1558624521,
"data": "event=s_79684881033_2019-05-23-15-15-11&cause=16",
"event": {
"type": "s",
"cause": "16"
},
"redirect_number": "79684881033",
"h323_conf_id": " BC5F236C 5AD211E9 81BA5CB9 01FED6FC ",
"numberA": "79154368886",
"sip_id": "79586488002".
"client_id ": "1235"
}
3. Окончание вызова:
{
"date_time": 1558624559,
"data": "event=h_79684881033_2019-05-23-15-15-11&cause=16",
"event": {
"type": "h",
"cause": "16"
},
"redirect_number": "79684881033",
"h323_conf_id": " BC5F236C 5AD211E9 81BA5CB9 01FED6FC ",
"numberA": "79154368886",
"sip_id": "79586488002".
"client_id ": "1235"
}
, где
"type": "o" - инициация вызова на REDIRECT_NUMBER
"type": "s" - REDIRECT_NUMBER снял трубку
"type": "h" - окончание вызова
"h323_conf_id" - уникальный id звонка в запросе getControlCallFollowMe
"cause" - причина отбоя по ISUP
"client_id" - cквозной идентификатор вызова от API клиента
"date_time" - unix timestamp
"numberA" - оригинальный А-номер РФ, номер с которого поступил вызов на "sip_id". Формат номера, тот который пришел на сеть МТТ, может быть и +7/8/7 + 10 цифр
"sip_id" - номер клиента по которому запрашивается алгоритм переадресации вызова. Формат номера 7+10 цифр (E.164), всегда
"redirect_number" - Номер для перенаправления вызова
"side" - сторона отбоя вызова: А - инициатор вызова (звонящий), B - принимающая сторона
Резервирование переадресации входящего вызова
Для осуществления резервирования переадресации входящего вызова при недоступности клиентского URL необходимо установить "оффлайн" переадресации ("number") для конкретного sip_id методом API:
Точка входа : https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
POST запрос
Описание:
Метод setReserveCallControlNumber
позволяет установить или обнулить номер резерва для услуги УВВ.
Входные параметры:
Name | Type | Description |
sip_id | string | sip_id аккаунта |
number | string | Строка содержащая number |
Выходные параметры:
Name | Type | Description |
success | number | Индикатор успеха |
Авторизация:
Авторизация осуществляется штатными средствами HTTP
Пример:
Запрос:
JSON:
|
Ответ:
Успешный ответ:
|
Не успешный ответ:
|
Для всех кодов ответа от клиентского URL на запрос логики переадресации getControlCallFollowMe , отличных от HTTP 200, МТТ использует заранее предустановленную «оффлайн» переадресацию.
Просмотр установленного клиентского URL и резервного номера для "оффлайн" переадресации
Для этого используется метод API:
Точка входа : https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
POST запрос
Описание:
Метод getAccountCustomFields позволяет получить установленный URL и резервный номер для "оффлайн" переадресации
Входные параметры:
Name | Type | Description |
sip_id | string | sip_id аккаунта, номер МТТ |
Выходные параметры:
Name | Type | Description |
GN_IP_IPCR | number | URL клиента для отправки запроса getControlCallFollowMe |
GN_IPCR_RESERVE | number | Резервный номер для "оффлайн" переадресации |
i_account | number | внутренний идентификатор на платформе МТТ |
Авторизация:
Авторизация осуществляется штатными средствами HTTP
Пример:
Запрос:
JSON:
{ "jsonrpc": "2.0", "method": "getAccountCustomFields", "id": "1", "params": {"sip_id":"79584630000" } } |
Ответ:
{ "jsonrpc": "2.0", "id": "1", "result": { "account_custom_fields": { "GN_IP_IPCR": "https://www.domen.ru/mtt/", "GN_IPCR_RESERVE": "79307084160", "i_account": 113408082 } } } |
Не успешный ответ (не предоставлен доступ к указанному методу):
{ "jsonrpc": "2.0", "id": "1", "error": { "code": -32002, "message": "Permission denied", "data": "agent does not have access to this account" } } |
Сценарий - клиент отправляет API запрос на платформу МТТ, МТТ осуществляет вызов на полученный номер пользователя, при ответе пользователя ему проигрывается информационное сообщение с последующим отбоем.
Функционал позволяет:
- осуществлять исходящий вызов на номер пользователя по API;
- воспроизводить синтезированный текст по средствам TTS;
- выбирать голос, язык, эмоцию и скорость диктора при синтезе текста;
- получать онлайн уведомления о ходе информирования по каждому исходящему вызову;
- получать причины недозвона до номера пользователя;
- получать всю необходимую информация: дата и время исходящего вызова, длительность прослушивания синтезированного текста, причины недозвона до номера пользователя и др.;
- использовать подстановку собственных А-номеров по заранее согласованному списку.
Точка входа : https://sb-api.mtt.ru/v1/sb
Авторизация: Basic Auth
API реализован в виде POST-запросов в соответствии со спецификацией JSON-RPC (http://www.jsonrpc.org/specification).
Входные параметры:
Name | Type | Description |
method | string | metod |
data | Набор данных |
Описание:
Метод инициирует вызов на номер с заданными параметрами.
data:
Параметр | Описание | Значение по умолчанию |
b_number* | Номер пользователя, на который инициируем вызов: Б-номер телефона, строго 11 цифр, E.164 | none |
sip_id* | Номер МТТ, учетная запись | none |
messId* | Идентификатор запроса со стороны клиента МТТ | none |
messText* | Текст для воспроизведения пользователю | none |
a_number | Номер для отображения пользователю при входящем звонке: А-номер телефона, строго 11 цифр, E.164 | Равен sip_id |
langCode | Язык. · ru-RU (по умолчанию) — русский язык, · en-US — английский язык.· | ru |
voice_name | Голос синтезированной речи. · женские голоса: alyss, jane, oksana и omazh; · мужские голоса: zahar, ermil, erkanyavas. | erkanyavas |
emotion | Эмоциональная окраска голоса. · good — радостный, доброжелательный; · evil — раздраженный; · neutral — нейтральный. | neutral |
speed_speech | Скорость (темп) синтезированной речи. · 3.0 — самый быстрый темп; · 1.0 — средняя скорость человеческой речи; · 0.1 — самый медленный темп. | 1.0 |
* - обязательные параметры
Авторизационные данные для Basic Auth, method, sip_id выделяются на стороне МТТ при активации коммерческой среды.
Возвращаемые параметры:
Параметр | Описание |
id | Идентификатор запроса со стороны клиента МТТ = messId |
CallID | уникальный ID на стороне сервиса (МТТ) для идентификации вызова |
success | Флаг успешного - 1, неуспешного - 0 отработки запроса. |
error | Ошибка и её описание |
Пример:
Запрос:
JSON:
{ "method": "metod", "data":{ "messId": "1255490", "sip_id": "79580000000", "a_number": "79581000000", "b_number": "79100000000", "messText": "Информационное сообщение для Вас" } } |
Успешный ответ:
{ "result": { "success": 1 }, "id": "1255490", "CallID": "00035c7d92bb061e" } |
Варианты неуспешного ответа:
Невалиден формат b_number: |
{ "result": { "success": 0, "error": "\"b_number\" should be in e164 format" }, "id": "1255490", "CallID": "00035c7d92260ed6" } |
Невалиден формат a_number: |
{ "result": { "success": 0, "error": "\"a_number\" should be in e164 format" }, "id": "1255490", "CallID": "00035c7d92260edc" } |
Нет messId |
{ "result": { "success": 0, "error": "\"messId\" not found in request body" }, "id": "00035c7d92bb099a" } |
Неверно указан method |
{ "message": "access forbidden" } |
Неверно указан sip id |
{ { "result": { "success": 0, "error": "Forbidden" }, "id": "1255490", "CallID": "00035c7d9226611f" } } |
Онлайн уведомления отправляются на предоставленный клиентом URL.
Формат онлайн уведомлений:
"date_time=дата и время&id=messId&CallID=CallID&event=o_b_number" - инициация вызова на b_number
"date_time=дата и время&id=messId&CallID=CallID&event=h_b_number_cause_duration" - факт разъединения или недозвона
где:
Параметр | Описание |
---|---|
event=o | cсобытие инициации вызова на b_number |
event=h | событие разъединения/окончание вызова |
date_time | дата и время события |
CallID | уникальный ID на стороне сервиса (МТТ) для идентификации вызова |
cause* | причина разъединения |
duration | длительность прослушивания синтезированного текста |
* - все существующие cause приведены в п. Получение статистики.
Примеры:
Абонент снял трубку, прослушал текст:
[{"date_time=2019-03-29-11-37-13&id=1255490&CallID=00035c7d92bb0971&event=o_79100000000"},
{"date_time=2019-03-29-11-37-27&id=1255490&CallID=00035c7d92bb0971&event=h_79100000000_16_4"}]
Абонент занят:
[{"date_time=2019-03-29-09-33-46&id=1255490&CallID=00035c7d92bb0935&event=o_79100000000"},
{"date_time=2019-03-29-09-33-53&id=1255490&CallID=00035c7d92bb0935&event=h_79100000000_17_0"}]
Абонент недоступен:
[{"data":"date_time=2019-03-29-09-41-18&id=1255490&CallID=00035c7d92bb093b&event=o_79100000000"},
{"date_time=2019-03-29-09-41-38&id=1255490&CallID=00035c7d92bb093b&event=h_79100000000_20_0"}]
Функционал позволяет в API запросе дополнительно указать структуру действий, наряду с текстом информирования для синтеза: перевод абонента на оператора, получения обратной связи на URL.
Описание - клиент присылает API запрос на инициацию вызова, включающий текст для клиента и структуру DTMF параметров.
При выборе абонентом DTMF (в том числе вариант с проговариванием голосом: один, два...) с:
- type=transfer - идет перенаправление вызова (callback) на полученный номер, с передачей онлайн событий о ходе вызова.
- type=notify - идет нотификация/event на полученный URL (https). По факту осуществления нотификации абоненту проговаривается стандартный текст "Спасибо за Ваш выбор, до свидания!"
Точка входа : https://sb-api.mtt.ru/v1/sb
Авторизация осуществляется штатными средствами HTTP (basic auth).
Для инициации вызова необходимо выполнить POST запрос.
Входные параметры:
Name | Type | Description |
method | string | method |
data | Набор данных инициации вызова | |
dtmf | Набор данных по возможным dtmf и действиям |
Описание:
Метод инициирует вызов на номер с заданными параметрами.
data:
Параметр | Описание | Значение по умолчанию |
b_number* | Номер пользователя, на который инициируем вызов: Б-номер телефона, строго 11 цифр, E.164 | none |
sip_id* | Номер МТТ, учетная запись | none |
messId* | Идентификатор запроса со стороны клиента МТТ | none |
messText* | Текст для воспроизведения пользователю | none |
a_number* | Номер для отображения пользователю при входящем звонке: А-номер телефона, строго 11 цифр, E.164 | none |
langCode | Язык. · ru-RU (по умолчанию) — русский язык, · en-US — английский язык; · tr-TR — турецкий язык. | ru |
voice_name | Голос синтезированной речи. · женские голоса: alyss, jane, oksana и omazh; · мужские голоса: zahar, ermil, erkanyavas. | erkanyavas |
emotion | Эмоциональная окраска голоса. · good — радостный, доброжелательный; · evil — раздраженный; · neutral — нейтральный. | neutral |
speed_speech | Скорость (темп) синтезированной речи. · 3.0 — самый быстрый темп; · 1.0 — средняя скорость человеческой речи; · 0.1 — самый медленный темп. | 1.0 |
dtmf:
Параметр | Описание | Значение по умолчанию |
dtmf_id* | · цифра dtmf, целое число от 1-9. Возможно произношение голосом: один, два, три и т.д. | none |
type* | · notify - нотификация по https на URL клиента · transfer - перевод на номер | none |
value* | · URL, задается через https при type: notify, пример: https://app.domain.ru/action/ · номер - строго 11 цифр при type: transfer , формат E.164, пример 79587561010 | none |
* - обязательные параметры
Возвращаемые параметры:
Параметр | Описание |
id | Идентификатор запроса со стороны клиента МТТ = messId |
CallID | уникальный ID на стороне сервиса (МТТ) для идентификации вызова |
success | Флаг успешного - 1, неуспешного - 0 отработки запроса. |
error | Ошибка и её описание |
Пример:
Запрос:
JSON:
{ "method": "ivr-api", "data": { "messId": "12345678", "sip_id": "74996489150", "b_number": "79103880489", "messText": "Здравствуйте, ваш заказа исполнен и готов к выдаче, нажмите 1 если готовы к самовывозу, 2 нужна доставка, 3 если хотите соединится с оператором для уточнения информации по заказу" "lang_code": "ru-RU", "voice_name": "oksana", "emotion": "neutral", "speed_speech": 1, "dtmf": [{ "dtmf_id": "1", "type": "notify", "value": "https://domain.ru/mtt/event.php" }, { "dtmf_id": "2", "type": "notify", "value": "https://domain.ru/mtt/event.php" }, { "dtmf_id": "3", "type": "transfer", "value": "74997090111" } ] } } |
Успешный ответ:
{ "result": { "success": 1 }, "id": "1255490", "CallID": "00035c7d92bb0971" } |
Варианты неуспешного ответа:
Невалиден формат b_number: |
{ "result": { "success": 0, "error": "\"b_number\" should be in e164 format" }, "id": "1255490", "CallID": "00035c7d92260ed6" } |
Невалиден формат a_number: |
{ "result": { "success": 0, "error": "\"a_number\" should be in e164 format" }, "id": "1255490", "CallID": "00035c7d92260edc" } |
Формат URL отличный от https: |
{ "result": { "success": 0, "error": "\"notify\" value is not allowed" }, "id": "1255490", "CallID": "00215e8250bf2070" } |
Неверно указан method |
{ "message": "access forbidden" } |
Неверно указан sip id |
{ { "result": { "success": 0, "error": "Forbidden" }, "id": "1255490", "CallID": "00035c7d9226611f" } } |
Event уведомления - онлайн события о ходе вызова
Уведомления отправляются POST запросом в формате JSON
Параметр | Описание |
event=o | cобытие инициации вызова на b_number |
event=h | событие разъединения/окончание вызова |
event=n | Нотификация по факту выбора type: notify |
duration | Длительность вызова |
date_time | дата и время события, формат 2019-03-29-11-37-13 |
cause* | причина разъединения |
CallID | уникальный ID на стороне сервиса (МТТ) для идентификации вызова |
redirect_number | Номер из параметра value при type:transfer |
b_number | См. описание соответствующего параметра метода инициации вызова |
1. Вызов b_number
1.1 Формат события инициация вызова на b_number
{ "date_time": "date_time", "id": "messId", "CallID": "CallID", "event": "o_b_number } |
1.2 Формат события окончания вызова
{ "date_time": "date_time", "id": "messId", "CallID": "CallID", "event": "h_ b_number_cause_duration*" } |
* - в duration указано общее время вызова: TTS+разговор с оператором
Примеры:
Абонент снял трубку, прослушал текст:
{ "date_time": "2019-03-29-11-37-13", "id": "1255490", "CallID": "00035c7d92bb0971", "event": "o_79103880489" } { "date_time": "2019-03-29-11-37-20", "id": "1255490", "CallID": "00035c7d92bb0971", "event": "h_79103880489_16_4" } |
Абонент занят
{ "date_time": "2019-03-29-11-37-13", "id": "1255490", "CallID": "00035c7d92bb0971", "event": "o_79103880489" } { "date_time": "2019-03-29-11-37-15", "id": "1255490", "CallID": "00035c7d92bb0971", "event": "h_79103880489_17_0" } |
Абонент недоступен:
{ "date_time": "2019-03-29-11-37-13", "id": "1255490", "CallID": "00035c7d92bb0971", "event": "o_79103880489" } { "date_time": "2019-03-29-11-37-20", "id": "1255490", "CallID": "00035c7d92bb0971", "event": "h_79103880489_20_0" } |
2. Уведомление при выборе dtmf
2.1 Формат события при type:transfer
Инициация вызова на redirect_number:
{ "date_time": "date_time", "id": "messId", "CallID": "CallID", "dtmf": "dtmf_id", "type": "transfer", "event": "o_redirect_number" } |
Окончание переадресованного вызова:
{ "date_time": "date_time", "id": "messId", "CallID": "CallID", "dtmf": "dtmf_id", "type": "transfer", "event": "h_redirect_number_cause_duration*" } |
* - в duration указано время переадресованного вызова, т.е. время общения с оператором
Пример:
Инициация вызова на redirect_number при выборе dtmf=2:
{ "date_time": "2019-03-29-11-38-00", "id": "1255490", "CallID": "00035c7d92bb0971", "dtmf": "2", "type": "transfer", "event": "o_78001000101" } |
Окончание переадресованного вызова:
{ "date_time": "2019-03-29-11-38-00", "id": "1255490", "CallID": "00035c7d92bb0971", "dtmf": "2", "type": "transfer", "event": "h_78001000101_16_30" } |
2.2 Формат события при type:callback
{ "date_time": "date_time", "id": "messId", "CallID": "CallID", "dtmf": "dtmf_id", "type": "notify", "event": "n_b_number" } |
Пример:
{ "date_time": "2019-03-29-11-37-13", "id": "1255490", "CallID": "00035c7d92bb0971", "dtmf": "1", "type": "notify", "event": "n_79103880489" } |
2.3 Уведомление при не выборе абонентом dtmf
Формат при не выборе dtmf
{ "date_time": "date_time", "id": "messId", "CallID": "CallID", "dtmf": "null", "type": "notify", "event": "n_b_number" } |
Пример:
{ "date_time": "2019-03-29-11-37-13", "id": "1255490", "CallID": "00035c7d92bb0971", "dtmf": "null", "type": "notify", "event": "n_79103880489" } |
3. Общий пример уведомлений о ходе вызова
Кейс: Клиент отправил запрос указанный в примере, МТТ инициировал вызов абоненту (b_number), абонент снял трубку, прослушал сообщение (TTS), выбрал dtmf=3 и перевелся на соответствующий redirect_number, после общения с оператором вызов завершился.
{ "date_time": "2019-03-29-11-37-13", "id": "1255490", "CallID": "00035c7d92bb0971", "event": "o_79103880489" } { "date_time": "2019-03-29-11-37-55", "id": "1255490", "CallID": "00035c7d92bb0971", "dtmf": "3", "type": "transfer", "event": "o_74997090111" } { "date_time": "2019-03-29-11-38-45", "id": "1255490", "CallID": "00035c7d92bb0971", "dtmf": "3", "type": "transfer", "event": "h_74997090111_16_30" } { "date_time": "2019-03-29-11-37-20", "id": "1255490", "CallID": "00035c7d92bb0971", "event": "h_79103880489_16_50" } |
* Возможные cause:
Коды причины ISUP |
== 1= unallocated number |
== 2= no route to network |
== 3= no route to destination |
== 16 normal call clearing |
== 17 user busy |
== 18 no user responding |
== 19 no answer from the user |
== 20 subscriber absent |
== 21 call rejected |
== 22 number changed (w/o diagnostic) |
== 22 number changed (w/ diagnostic) |
== 23 redirection to new destination |
== 26 non-selected user clearing |
== 27 destination out of order |
== 28 address incomplete |
== 29 facility rejected |
== 31 normal unspecified |
== 34 no circuit available |
== 38 network out of order |
== 41 temporary failure |
== 42 switching equipment congestion |
== 47 resource unavailable |
Точка подключения:https://msapi.mtt.ru:443/
Для получения номеров аккаунта необходимо сделать GET запрос к /v2/accounts/{accountSID}/numbers.
Входящие параметры:
Name | Type | Description |
limit | int | Лимит выводимых данных |
offset | int | Смешение относительно начала |
Возвращаемые параметры:
Name | Type | Description |
page | int | Номер страницы, начинается с 0. |
limit | int | Количество возвращенных записей на странице (по умолчанию 20(максимальное кол-во)). |
next | string | URI к следующей части списка. |
prev | string | URI, к предыдущей части списка. |
total | int | Общее количество записей в списке. |
numbers | Json array | Список номеров. |
numbers/number | string | Номер |
numbers/direction | string | Разрешенное направление отправки |
Примерзапроса:
curl –X GET 'v2/accounts/{accountSID}/numbers' \
-u {accountSID}:{Token}
Ответ SMSM:
{
"page": 1,
"total": 1,
"limit": 20,
"offset": 0,
"prev": "",
"next": "",
"numbers": [
{
"number": "35800445016",
"direction": "OUT"
}
]
}
Примерзапросас limit, offset
v2/accounts/{accountSID}/numbers?offset=5&limit=5
Запрос возвращает список из 5-ти номеров начиная с 6-го номера.
Для отправки сообщения необходимо сделать POST запрос к
/v2/accounts/{account_sid}/messages
Входящиепараметры:
Name | Type | Description |
from | string | Номер отправителя |
to | string | Номер получателя |
text | string | Текст сообщения |
tag | string | Необязательное пользовательское поле, может использоваться для установки уникального идентификатора каждого сообщения. |
Возвращаемые параметры:
Name | Type | Description |
status_code | integer | Статус запроса |
status_message | string | Статус сообщения |
uri | string | url откуда может быть загружена информация о созданном сообщении, msg(последняя часть uri) - идентификатор успешно созданного сообщения; |
request_id | string | Уникальный идентификатор ошибки |
error | string | Описание ошибки |
Authorization:
Basic HTTP auth.
Example:
Request:
JSON:
/v2/accounts/accefd5c385-f2aa-3dd4-9c0b-01abf00cccfe/messages
{
"from": "79587625004",
"to": "79587625004",
"text": "Hello, I am sending message"
}
Response:
Successfull:
{
"status_code": 201,
"status_message": "CREATED",
"uri": "/v2/accounts/accefd5c385-f2aa-3dd4-9c0b-01abf00cccfe/messages/msgb0789d2f-8932-400d-8768-b6c12abbb872"
}
Unsuccessfull:
{
"status_code": 400,
"request_id": "7f4d9823-fd41-4697-ba9b-11940e7932d0",
"error": "Invalid params: text shouldn't be empty"
}
{
"status_code": 400,
"request_id": "7f4d9823-fd41-4697-ba9b-11940e7932d0",
"error": "Invalid params: text shouldn't be empty"
}
Для получения истории сообщений необходимо выполнить GET запрос к /v2/accounts/{accountSID}/messages.
Входящие параметры:
Name | Type | Description |
AccountSID | string | Идентификатор аккаунта |
authToken | string | Пароль |
Пример запроса:
curl –X GET 'v2/accounts/{accountSID}/messages?limit=5' \
-u {accountSID}:{authToken}
Возвращаемые параметры:
Name | Type | Description |
page | int | Номер страницы, начинается с 0. |
limit | int | Количество возвращенных записей на странице (по умолчанию 20(максимальное кол-во)). |
next | string | URI к следующей части списка. |
prev | string | URI, к предыдущей части списка. |
total | int | Общее количество записей в списке. |
messages | Json array | Список сообщений. |
messages /message_sid | string | Идентификатор сообщения. |
messages /created_at | string | Дата создания. |
messages /account_sid | string | Идентификатор аккаунта. |
messages /number | string | Внешний номер, с/на который отправлено сообщение |
messages /external_number | string | Наш номер с/на который отправлено сообщение |
messages /text | string | Текст сообщения. |
messages/direction | string | Направление сообщения: "inbound" или "outbound". |
messages/status | string | Текущий статус сообщения. |
messages/segment_count | string | Количество частей в сообщении |
Пример ответа:
JSON
{
"page": 1,
"total": 379,
"limit": 5,
"offset": 0,
"prev": "",
"next": "http://172.16.102.108:8985/v2/accounts/accefd5c385-f2aa-3dd4-9c0b-01abf00cccfe/messages?limit=5&offset=5",
"messages": [
{
"account_sid": "accefd5c385-f2aa-3dd4-9c0b-01abf00cccfe",
"message_sid": "msg204815e0-68d3-4193-999b-d142b749fd39",
"text": "работают",
"created_at": 1518091728,
"direction": "inbound",
"number": "79587625002",
"external_number": "79057259771",
"status": "received",
"segment_count": 1,
},
{
"account_sid": "accefd5c385-f2aa-3dd4-9c0b-01abf00cccfe",
"message_sid": "msg660c1d96-bdd3-4e62-a682-9665309b5cc3",
"text": "tester2 Privet!",
"created_at": 1518091728,
"direction": "inbound",
"number": "79587625002",
"external_number": "79166597045",
"status": "received",
"segment_count": 1,
},
{
"account_sid": "accefd5c385-f2aa-3dd4-9c0b-01abf00cccfe",
"message_sid": "msgfe14221b-4dff-4959-9962-de507af92f4a",
"text": "оистатусики",
"created_at": 1518091728,
"direction": "inbound",
"number": "79587625002",
"external_number": "79057259771",
"status": "received",
"segment_count": 1,
},
{
"account_sid": "accefd5c385-f2aa-3dd4-9c0b-01abf00cccfe",
"message_sid": "msg9c8045b5-0fab-4b8f-b0ee-278dcd93fdfc",
"text": "шик",
"created_at": 1518091728,
"direction": "inbound",
"number": "79587625002",
"external_number": "79057259771",
"status": "received",
"segment_count": 1,
},
{
"account_sid": "accefd5c385-f2aa-3dd4-9c0b-01abf00cccfe",
"message_sid": "msg9b23d61c-c28b-40cb-bd2c-adf290a3219c",
"text": "статусы в группе не проверишь)",
"created_at": 1518091728,
"direction": "inbound",
"number": "79587625002",
"external_number": "79166597045",
"status": "received",
"segment_count": 1,
}
]
}
Фильтр по параметрам.
Для фильтрации возвращаемого списка сообщений необходимо задать значения параметров в запросе GET.
Примерзапроса:
curl –X GET
'v2/accounts/{accountSID}/messages?direction=outbound&status=delivered \
-u {accountSID}:{authToken}
Возможна фильтрация возвращаемого списка по следующим параметрам:
· limit,
· message_sid,
· number,
· external_number,
· number_sid,
· direction,
· status,
Для получения информации по сообщении необходимо выполнить GET запрос к /v2/accounts/{accountSID}/messages/{messageSID}
Примерзапроса:
JSON
curl –X GET 'v2/accounts/{accountSID}/messages/{messageSID} \
-u {accountSID}:{authToken}
Примерответа:
JSON
{
"page": 1,
"total": 1,
"limit": 5,
"offset": 0,
"prev": "",
"next": "",
"messages": [
{
"account_sid": "accefd5c385-f2aa-3dd4-9c0b-01abf00cccfe",
"message_sid": "msg204815e0-68d3-4193-999b-d142b749fd39",
"text": "работают",
"created_at": 1518091728,
"direction": "inbound",
"number": "79587625002",
"external_number": "79057259771",
"status": "received",
"segment_count": 1,
}
]
}
Event уведомления высылаются на URL Клиента при:
ü Отправке SMS сообщения и дальнейшем изменении статуса данного SMS сообщения;
ü Входящем SMS сообщении.
Отправка Event уведомлений производится на URL Клиента, методом POST или GET на выбор Клиента, при этом URL должен быть строго в формате https обязательно с валидным сертификатом, пример event уведомлений:
Исходящая смс:
account_sid=acc560115b3-4831-3618-9c44-959590da3d44&direction=outbound&from=79587625012&hash=view&message_sid=msg96f3f40d-d0cf-3af4-99fc-b73653aa6f2e&status=queued&text=test+inbound&to=79587643270
account_sid=acc560115b3-4831-3618-9c44-959590da3d44&direction=outbound&from=79587625012&hash=view&message_sid=msg96f3f40d-d0cf-3af4-99fc-b73653aa6f2e&status=prebilling&text=test+inbound&to=79587643270
account_sid=acc560115b3-4831-3618-9c44-959590da3d44&direction=outbound&from=79587625012&hash=view&message_sid=msg96f3f40d-d0cf-3af4-99fc-b73653aa6f2e&status=sent&text=test+inbound&to=79587643270
account_sid=acc560115b3-4831-3618-9c44-959590da3d44&direction=outbound&from=79587625012&hash=view&message_sid=msg96f3f40d-d0cf-3af4-99fc-b73653aa6f2e&status=delivered&text=test+inbound&to=79587643270
Входящаясмс:
account_sid=acc560115b3-4831-3618-9c44-959590da3d44&direction=inbound&from=79587643270&hash=view&message_sid=msge7316966-5975-4418-8f5a-a7224fb130f9&status=received&text=Test+inbound&to=79587625012
Запрос отправляется со следующим заголовком:
application/x-www-form-urlencoded
Premedia API позволяет:
ü Загружать промт и воспроизводить его в сторону звонящего и/либо в сторону принимающего вызов при переадресации;
ü Устанавливать text-to-speech и воспроизводить его в сторону звонящего и/либо в сторону принимающего вызов при переадресации;
ü Управление основными сценариями Premedia API:
- "scenario_id": "1" - проигрывание промта/TTS в сторону А-номера
- "scenario_id": "2" - проигрывание промта/TTS в сторону принимающего вызов (С-номер)
- "scenario_id": "3" - проигрывание промта/TTS в сторону А-номера и в сторону принимающего вызов (С-номер - redirect number)
Точка подключения: https://gapi.mtt.ru:6443/v1/api
Авторизация: Basic Auth
Метод: POST
Создаёт prompt/TTS
Входные параметры:
Name | Type | Description |
customer_name* | string | Идентификатор customer'а. |
prompt_type | string | 'file' || 'text' (дефолтное значение 'file'). Если 'text', то prompt_file_contents посредством TextToSpeech преобразуется в mp3 файл. |
prompt_name* | string | Название prompt'а (обязательно наличие расширения mp3 !!!) |
prompt_file_contents* | string | Содержимое файла prompt'а в кодировке base64. Формат файлов mp3. (для TTS - UTF-8!!!) |
* - обязательные поля
Выходные параметры:
Name | Type | Description |
success | boolean | Флаг успеха |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
|
Возвращает информацию о всех промтах предустановленных для customer'а в premedia api.
Входные параметры:
Name | Type | Description |
customer_name* | string | Идентификатор customer'а. |
* - обязательные поля
Выходные параметры:
Name | Type | Description |
id | integer | Идентификатор промта в premedia api |
name | string | Название файла промта |
Авторизация:
Авторизация осуществляется штатными средствами HTTP
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
"file_id": "c20ed66245ae695fc35f846ef3f35e94"
"file_id": "a11b494d3952ff1fb2b7de375524db41"
|
Не успешный ответ:
JSON
|
Описание:
Удаляет prompt customer'а.
Входные параметры:
Name | Type | Description |
customer_name* | string | Идентификатор customer'а. По соглашению было принято использовать i_customer. |
prompt_name* | string | Имя prompt'а |
* - обязательные поля
Выходные параметры:
Name | Type | Description |
success | bool | Успешность выполнения |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
|
@ "scenario_id": "1" - проигрывание промта/TTS в сторону А-номера;
@ "scenario_id": "2" - проигрывание промта/TTS в сторону принимающего вызов (С-номер);
@ "scenario_id": "3" - проигрывание промта/TTS в сторону А-номера и в сторону принимающего вызов (С-номер - redirect number).
Входные параметры:
Name | Type | Description |
sip_id* | string | Идентификатор account'а. |
scenario_id* | integer | Идентификатор сценария |
answer | integer | Флаг предответного состояния - 0, 1 (default 0) |
* - обязательные поля
Выходные параметры:
Name | Type | Description |
success | bool | Успешность выполнения |
Авторизация:
Авторизация осуществляется штатными средствами HTTP
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
|
Метод привязывает к аккаунту уже загруженный ранее промт, согласно ранее установленному сценарию.
Входные параметры:
Name | Type | Description |
sip_id* | string | Идентификатор account'а. |
prompt_name* | integer | Имя промпта (ранее загруженного) |
side* | string | Какому плечу (A или B) будет проигрываться промпт |
* - обязательные поля
Выходные параметры:
Name | Type | Description |
success | bool | Успешность выполнения |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
|
Удаляет у account'а привязку промта, установленного для указанного плеча.
Входные параметры:
Name | Type | Description |
sip_id* | string | Идентификатор account'а. |
side* | string | К какому плечу (A или B) привязанный промпт нужно удалить |
* - обязательные поля
Выходные параметры:
Name | Type | Description |
success | bool | Успешность выполнения |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
|
Просмотр установленного сценария Premedia c выводом привязанных промтов.
Входные параметры:
Name | Type | Description |
sip_id* | string | Идентификатор account'а. |
* - обязательные поля
Выходные параметры:
Name | Type | Description |
sip_id | string | Идентификатор промпта в премедиа апи |
answer | boolean | Значение флага ответного/предответного состояния |
diversion | boolean | Значение флага установки переадресации |
scenario_id | integer | Идентификатор сценария |
scenario_name | string | Наименование сценария |
prompts | array | Инфо о промтах привязанных к аккаунту для плечей A,B |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Устанавливает настройки переадресациии на Premedia аккаунте.
Входные параметры:
Name | Type | Description |
sip_id* | string | Идентификатор аккаунта |
sequence | string:range(Order,Random,Simultaneous) | Тип сортировки при обзвоне списка правил. По умолчанию Order |
caller_id | string | Отображаемый номер А-номер при переадресации Допустимый формат: ^7\d{10}$ ("7"+10цифр). |
followmeStructure | array | Mассив настроек follow_me |
* - обязательные поля
Формат настроек follow_me:
Name | Type | Description |
redirect_number | string | Номер для переадресации |
name | string | Наименование follow_me записи |
timeout | integer | По умолчанию 15 |
active | string:range(Y,N) | Флаг активно/неактивно |
follow_order | integer | Номер в очереди переадресации |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
|
Возвращает информацию о настройках переадресаций account'а.
Входные параметры:
Name | Type | Description |
sip_id* | string | Идентификатор account'а. |
* - обязательные поля
Выходные параметры:
Name | Type | Description |
sip_id | string | Идентификатор account'а. |
sequence | stringstring:range(Order,Random,Simultaneous) | Тип сортировки при обзвоне списка правил. |
caller_id | string | Отображаемый А-номер при переадресации |
followmeStructure | array | Mассив настроек follow_me |
Формат элементов followmeStructure:
Name | Type | Description |
redirect_number | string | Номер для переадресации |
name | string | Наименование follow_me записи |
timeout | integer | Величина таймаута |
active | string:range(Y,N) | Флаг активно/неактивно |
follow_order | integer | Номер в очереди переадресации |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
|
Доступ к функции осуществляется по протоколу HTTPS:
Точка подключения: https://gapi.mtt.ru:6443/v1/api
Авторизация: Basic Auth
Метод: POST
Описание:
Данная функция добавляет номера Клиенту.
Входные параметры:
Name | Type | Description |
region_code* | string | Код региона, например (MOW) |
quantity* | string | Количество добавляемых номеров |
dial_code | string | Код набора (напр. 495) |
* - обязательные поля
Выходные параметры:
Name | Type | Description |
number_list | int | Список добавленных номеров |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
{
"id": "1",
"jsonrpc": "2.0",
"method": "addNumbers",
"params":
{
"region_code" : "MOW",
"quantity" : 2,
"dial_code" : 495
}
}
Ответ:
Успешный ответ:
JSON
{
"jsonrpc": "2.0",
"id": "1",
"result": [
{
"number_list": [
{
"number": 74950000131,
"result": {
"status": "Success"
}
},
{
"number": 74950000132,
"result": {
"status": "Success"
}
}
]
}
]
}
Не успешный ответ:
{
"jsonrpc": "2.0",
"id": "1",
"error": {
"code": -32602,
"message": "Invalid params",
"data": [
{
"code": "B_INSUFFICIENT_FUNDS_FOR_NUMBERS",
"attribute": "quantity",
"message": "Insufficient funds to connect 2 numbers",
"tpl": "Insufficient funds to connect {value} numbers",
"tplParams": {
"value": 2,
"attribute": "quantity"
}
}
]
}
}
Для возможности покупки номеров определенного региона по API необходимо добавление хотя бы одного номера данного региона на лицевой счет.
Данное действие производится через персонального менеджера.
Доступ к функции осуществляется по протоколу HTTPS:
Точка подключения: https://gapi.mtt.ru:6443/v1/api
Авторизация: Basic Auth
Метод: POST
Description:
Добавляет номер в Global Black List.
Input parameters:
Name | Type | Description |
gbl_rule | string | Phone number to be forbidden |
Output parameters:
Name | Type | Description |
success | integer: [0,1] | Result success flag |
Authorization:
Basic HTTP Auth.
Пример:
Запрос:
JSON
{
"id": "1",
"jsonrpc": "2.0",
"method": "addGBLRule",
"params":
{
"gbl_rule": "79266966166"
}
}
Response:
Successfull:
JSON
{
"jsonrpc":"2.0",
"id":"1",
"result":
{
"success":1
}
}
Unsuccessfull:
{
"jsonrpc":"2.0",
"id":"1",
"error":
{
"code":-32603,
"message":"Internal error",
"data":
[
{
"code":"A_CAPI_CREATE_RATE",
"attribute":"Destination",
"message":"Failed to create new rate for Destination «79266966166»",
"tpl":"Failed to create new rate for {attribute} «{value}»",
"tplParams":
{
"value":"79266966166",
"attribute":"Destination"
}
}
]
}
}
Description:
Удаляет номера из Global Black List.
Input parameters:
Name | Type | Description |
gbl_rule | string | Phone number to be forbidden |
Output parameters:
Name | Type | Description |
success | integer: [0,1] | Result success flag |
Authorization:
Basiс HTTP Auth.
Пример:
Запрос:
JSON
{
"id": "1",
"jsonrpc": "2.0",
"method": "deleteGBLRule",
"params":
{
"gbl_rule": "79266966166"
}
}
Response:
Successfull:
JSON
{
"jsonrpc":"2.0",
"id":"1",
"result":
{
"success":1
}
}
Unsuccessfull:
{
"jsonrpc":"2.0",
"id":"1",
"error":
{
"code":-32001,
"message":"Data not found",
"data":
[
{
"code":"V_VALUE_NOT_FOUND",
"attribute":"gbl_rule",
"message":"gbl_rule «79266966166» not found.",
"tpl":"{attribute} «{value}» not found.",
"tplParams":
{
"value":"79266966166",
"attribute":"gbl_rule"
}
}
]
}
}
Description:
Получает все номера из Global Black List установленные для учётной записи.
Input parameters:
Name | Type | Description |
Output parameters:
Name | Type | Description |
gbl_rules | array | Array of phone numbers |
Authorization:
Basis HTTP Auth.
Пример:
Запрос:
JSON
{
"id": "1",
"jsonrpc": "2.0",
"method": "getGBLRules",
"params":
{
}
}
Response:
Successfull:
JSON
{
"jsonrpc":"2.0",
"id":"1",
"result":
[
79663089363,
79266966166
]
}
Unsuccessfull:
{
"jsonrpc":"2.0",
"id":"1",
"error":
{
"code":-32603,
"message":"Internal error",
"data":
[
{
"code":"A_CAPI_GET_RATES",
"attribute":"Tariff",
"message":"Failed to get rates for Tariff",
"tpl":"Failed to get rates for {attribute}",
"tplParams":
{
"attribute":"Tariff"
}
}
]
}
}
«WEB SDK» – продукт, предоставляющий возможность размещения в Web приложение Клиента функционала голосовой телефонной связи. Данный продукт предоставляется с необходимостью:
- добавление библиотеки javascript в Web приложение Клиента;
- приобретением номера из любой номерной емкости МТТ (АВС, DEF или 7800).
Данный продукт имеет следующий функционал:
- Входящая связь;
- Исходящая связь;
- Удержание вызова;
- Трансфер, объединение абонентов 2-соединений (абонента входящего звонка с абонентом исходящего звонка).
Документация:
https://flashphoner.com/documentation/ (Актуальная версия 5.0.2971)
Демо стенд WebSdk:
- https://webrtcapp.mtt.ru/examples/demo/sip/phone-ui/Phone.html
- https://webrtcapp.mtt.ru/examples/demo/sip/phone/phone.html
Для получения параметров подключения к сети МТТ необходимо обратиться к персональному менеджеру.
По умолчанию в запросах в сторону API клиента отрыты только 80 и 443 порты.
16 Comments
gnezdoapi
Что озночает id в теле запроса и почему оно отличается для разных методов?
Ляпин Михаил Вадимович
id - можете передавать собственное значение, переданное значение вернется в ответе на API запрос.
gnezdoapi
Где взять описания причин для поля disconnect_cause, там магические числовые константы. Требуется описание всех возможных причин disconnect_cause
Ляпин Михаил Вадимович
Добавлена информация по Disconnect_cause в п. Получение статистики
gnezdoapi
Если сделать вызов через makeCallBackCallFollowme с id=556677, то события Events по этому вызову будут возвращаться с этим же id=556677 ?
Ляпин Михаил Вадимович
id=556677 вернется в ответе на запрос makeCallBackCallFollowme, в Events будет возвращаться callBackCall_id вызова.
gnezdoapi
Параметр
used_quantity
Integer
Общее время соединений в ходе сессии
В каких единицах измерения (секунды, минуты,...)?
Ляпин Михаил Вадимович
Секунды
gnezdoapi
Коллеги, все вышеперечисленное есть в едином документе, который можно скачать?
Ляпин Михаил Вадимович
Для получения документации в формате .doc или ,pdf прошу обратиться к персональному менеджеру.
gnezdoapi
Подскажите, какие ещё бывают статусы в SMS API у
кроме: "received" ?
Ляпин Михаил Вадимович
Для исходящих сообщений:
queued - sms в очереди на отправку
prebilling - проверка биллингом
sent - sms отправлена
delivered - sms доставлена
Для входящих сообщений:
received - sms принята
gnezdoapi
Подскажите пожалуйста, можете дополнить описание функции setCallBackPrompt для случая синтезированного текста?
Ляпин Михаил Вадимович
Текст для синтеза передается в самом запросе на инициацию вызова, см. пример по функции API - makeCallBackCallFollowme
gnezdoapi
В документации для функции getServiceHistoryByCustomer приведен пример c запросом входящего (incoming) трафика, а в успешном результате данные исходящего (dialed) трафика Народ не путается ?
Ляпин Михаил Вадимович
Спасибо. Было исправлено.