| Expand | |||
|---|---|---|---|
| |||
| Expand | |||
| |||
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 | Идентификатор записи, по которому можно получить ссылку на скачивание | |
{ "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" } } | |||
{ "jsonrpc": "2.0", "id": "3", "error": { "code": -32001, "message": "Data not found", "data": "No data found" } } | |||
| Expand | |||
| |||
Name | Type | Description | type* | string |
Name | Type | Description |
incoming | array | История входящих звонков |
missed | array | История пропущенных звонков |
dialed | array | История исходящих звонков |
forwarded | array | История переадресованных вызовов |
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
incomingarrayИстория входящих звонковmissedarrayИстория пропущенных звонковdialedarrayИстория исходящих звонковforwardedarrayИстория переадресованных вызововАвторизация:
Авторизация осуществляется штатными средствами 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
Стоимость вызова
destinationstringНаправление вызоваh323_conf_idstringИдентификатор записи, по которому можно получить ссылку на скачиваниеh323_incoming_conf_idstringИдентификатор записи входящего вызова, h323_conf_id в массиве incomingcurrstringВалюта клиентаdisconnect_cause
Integer
Причина завершения последнего плеча вызова
setup_time_ms
Integer
время установления соединения в мс
account_id
string
Номер клиента, номер МТТ
used_quantity
Integer
Общее время соединений в ходе сессии, измеряется в секундах
h323_conf_id
string
Идентификатор записи, по которому можно получить ссылку на скачивание
voice_record_exist
Boolean
Наличие записанного разговора, false - нет записи, true - запись есть (сформировалась)
cli - в общем случае телефонный номер с которого поступил вызов, cld - номер на который поступил вызов.
В общем случае, за исключением forwarded, account_id и cli будут совпадать.
В случае forwarded в cli будет номер с которого поступил звонок переадресованный на номер cld.
Пример:
Запрос:
JSON:
{
"jsonrpc": "2.0",
"id": "1",
"method": "getServiceHistoryByCustomer",
"params":{
"type": "dialed",
"customer_name": "110011256",
"date_from": "2017-09-14 16:01:05",
"date_to": "2017-09-14 16:01:10",
"order": "DESC"
}
}
Ответ:
Успешный ответ:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"dialed": [
{
"cli": "79066899000",
"cld": "74959333223",
"customer_local_time": "2017-09-14 16:01:09",
"connect_time": "2017-09-14 16:01:09",
"charged_time": "119",
"charged": 2.48,
"destination": "Россия фикс.",
"h323_conf_id": "2B23D937 BD9BCF86 E89D407D 44DA0162",
"h323_incoming_conf_id": "AC4D7D28 994C11E7 88C6AC16 2D8CE148",
"curr": "RUB",
"setup_time_ms": "4581",
"disconnect_cause": "16",
"account_id": "74951349387",
"used_quantity": "119",
"voice_record_exist": false
},
{
"cli": "79262049647",
"cld": "79775133876",
"customer_local_time": "2017-09-14 16:01:08",
"connect_time": "2017-09-14 16:01:08",
"charged_time": "60",
"charged": 0,
"destination": "Россия фикс.",
"h323_conf_id": "C2D68D0D 584EEE9A 2697A64B 9A0A0F53",
"h323_incoming_conf_id": "92E21D30 994C11E7 8FD7AC16 2D8CE148",
"curr": "RUB",
"setup_time_ms": "8575",
"disconnect_cause": "16",
"account_id": "883140584982783",
"used_quantity": "35",
"voice_record_exist": false
},
{
"cli": "74993018267",
"cld": "79104080307",
"customer_local_time": "2017-09-14 16:01:07",
"connect_time": "2017-09-14 16:01:07",
"charged_time": "0",
"charged": 0,
"destination": "Россия фикс.",
"h323_conf_id": "7EFDAECB 8A53BF45 63F48E8E 273A7F83",
"h323_incoming_conf_id": "92E26222 994C11E7 8FD7AC16 2D8CE148",
"curr": "RUB",
"setup_time_ms": "2000",
"disconnect_cause": "17",
"account_id": "883140587615452",
"used_quantity": "0",
"voice_record_exist": false
}
],
"success": 1
}
}
Не успешный ответ:
{
"jsonrpc": "2.0",
"id": "3",
"error": {
"code": -32602,
"message": "Invalid params",
"data": "Invalid begin date"
}
}
Комментарий:
cli - откуда
cld - куда
| title | Disconnect cause |
|---|
| title | Получение записи разговора |
|---|
Интерфейс взаимодействия - REST API.
Аутентификация - Basic Auth.
Метод: Get
Пример запроса для получения ссылки на запись разговора в формате wav:
https://rc.mtt.ru/v1/records/<h323_conf_id>/urls
Пример запроса для получения ссылки на запись разговора в формате mp3:
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"
]
| title | Установка и получение номера переадресации |
|---|
Точка подключения: https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
Метод: POST
| title | setFollowme |
|---|
Описание:
Обновляет список номеров, на которые будет осуществляться переадресация вызова.
Входные параметры:
Name
Type
Description
sid_idstringИдентификатор SIPfollowmeStructarray of followmeStructСтруктуру followmeStruct см. ниже в примере успешного запросаfollowmeStruct:
Name
Type
Description
timeoutstringТаймаут (в секундах)redirect_numberstringНомер для перенаправления вызова. Формат номера РФ:Е.164 без "+", н-р, 74951234567 namestringСимвольное имя номера для перенаправления вызоваactivestringАктивность (Y/N)periodstringПериод (дни недели и диапазон времени) активности перенаправления на данный номерperiod_descriptionstringОписание периода перенаправления вызоваfollow_orderstringПорядок следования номера при перенаправлении вызоваdomain*stringДоменuse_tcp*stringИспользовать TCP (Y/N)keep_original_cli*stringОтображение АОН звонящему (Y/N/I)Y - отображение реального номера звонящего (по умолчанию)N - отображение в качестве номера звонящего sip_idI - отображение реального номера звонящего, используется при настроенной схеме (на стороне МТТ) проигрывания приветственного/информационного сообщения (Premedia) для звонящего/принимающего вызов абонента. keep_original_cld*stringОставлять оригинальный CLD (Y/N)* - необязательные параметры
Выходные параметры:
Name
Type
Description
successnumber1 = список успешно обновлёнАвторизация:
Авторизация осуществляется штатными средствами 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"
}
}
| title | getFollowme |
|---|
Описание:
Возвращает список номеров для переадресации вызовов.
Входные параметры:
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"
}
}
| title | Получение баланса лицевого счета |
|---|
Точка подключения: https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
Метод: POST
| title | getCustomerBalance |
|---|
Описание:
Данная функция возвращает баланс кастомера.
Входные параметры:
Name
Type
Description
customer_name*
String
Имя существующего кастомера = лицевой счет
Выходные параметры:
Name
Type
Description
balance
numeric
Баланс кастомера
real_balance
numeric
Полный баланс кастомера
pending_payment
* Обязательные поля
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
{
"jsonrpc":"2.0",
"method":"getCustomerBalance",
"params":
[
"110000000"
],
"id":1
}
Ответ:
Успешный ответ:
{
"jsonrpc":"2.0",
"id":1,
"result":
{
"balance":121.54,
"real_balance":711.54
}
}
Не успешный ответ:
{
"jsonrpc": "2.0",
"id": "1",
"error":
{
"code": -32001,
"message": "Data not found"
}
}
// Данный проверочный код невалиден для переданных sip_id и phone_num
| title | Вывод всех аккаунтов, привязанных к лицевому счету |
|---|
Точка подключения: https://webapicommon.mtt.ru/index.php
| title | getCustomerAccountsShort |
|---|
Описание:
Данная функция возвращает все аккаунты кастомера.
Входныепараметры:Name | Type | Description |
customer_name* | String | Имя существующего кастомера |
Выходные параметры:
Name
Type
Description
account_list
array of AccountInfo
Список аккаунтов кастомера
AccountInfo
Name
Type
Description
sip_id
string
Идентификатор аккаунта
activation_date
date(format:Y-m-d)
Дата активации аккаунта
* Обязательные поля
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
|
Ответ:
Успешный ответ:
{
"jsonrpc":"2.0",
"id":"1",
"result":
{
"accountList":
[
{
"sip_id":"883140005556637",
"activation_date":"2016-11-18"
},
{
"sip_id":"883140005556631",
"activation_date":"2016-07-29"
},
{
"sip_id":"883140005556632",
"activation_date":"2016-07-29"
}
]
}
}
Не успешный ответ:
{
"jsonrpc":"2.0",
"id":"1",
"error":
{
"code":-32002,
"message":"Permission denied",
"data":"agent does not have access to this account"
}
}
| title | Функционал CallBack API |
|---|
Функционал позволяет по API:
- Осуществить быстрый дозвон и соединение требуемых номеров A (клиент) и B (пользователь);
- Вызывать сразу несколько номеров клиента (персональных менеджеров) с необходимой логикой дозвона: последовательно, параллельно, рандомно;
- Проиграть аудиосообщение или синтезированный текст в сторону клиента (персонального менеджера), так и в сторону абонента заказавшего звонок (пользователя) при снятии трубки;
- Записать разговор клиента и пользователя, записывается разговор по обоим плечам;
- Задать максимально возможную длительность разговора клиента и пользователя;
- Получать online уведомления о ходе вызова;
- Настроить свой собственный сервис CallBack на базе предоставляемого функционала.
Точка подключения: https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
Метод: POST
| title | makeCallBackCallFollowme |
|---|
Описание:
Данная функция осуществляет callback между А-номером или номерами переданным в поле simpleCallBackFollowmeStruct и B-номером.
Входные параметры:
Name
Type
Description
stringid, маркер запроса, будет выдан в ответе на запрос.customer_name*stringАккаунт CallBack, выдается МТТb_number*stringНомер плеча B (по умолчанию). Номер, на который будет совершён звонок, по фактическому ответу плеча A.caller_idstringНомер, который будет показан абоненту плеча В. Данный параметр должен устанавливаться, либо в функции setCallBackFollowme либо в функции makecallbackfollowme.callBackURLstringURL, на который, будут посылаться уведомления о ходе вызова. Строго без http/www. Конечный файл, куда будут отправляться events должен называться event.phpsimpleCallBackFollowmeStructarray of simpleCallBackFollowmeStructСтруктуру simpleCallBackFollowmeStruct см. в примере успешного запроса recordEnablenumberЗапись звонка. По умолчанию - 1. Записывается.durationnumberОбщая продолжительность попытки вызова (сек.)client_caller_idstringНомер, который будет показан абоненту плеча A. По умолчанию - b_numberdirectionnumberrЗначение 0 или 1. Направление вызова. По умолчанию 0 - redirect_number (Плечо А)-->b_number (плечо B), 1 - b_number (плечо А)-->redirect_number (Плечо B)callDescriptionstringКомментарий к вызову.dtmf_numberstring
Дополнительный номер при наборе.
* обязательные поля
simpleCallBackFollowmeStruct:
Name
Type
Description
ordernumberПорядок следования номера при перенаправлении вызоваtimeoutnumberТаймаут (в секундах)- время дозвона с момента отправки Json запроса на осуществление вызова до прекращения дозвона. Рекомендуется устанавливать значение от 15 секунд.redirect_numberstringНомер плеча А, по умолчанию.typestringТип очереди, файла, текста, etcnamestringСимвольное имя номера для перенаправления вызоваsidestringПлечо для проигрывания файла или сообщения (А или В)valuestringИнформация для проигрывания или имя файлаВыходные параметры:
Name
Type
Description
callBackCall_idstringУникальный идентификатор вызоваАвторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример запроса с ранее установленной структурой вызова (см. setCallBackFollowme):
JSON:
{ "id": "1", "jsonrpc": "2.0", "method": "makeCallBackCallFollowme", "params": { "customer_name" : "883140500000000", "b_number" : "+79157775533" } } |
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-номер.
}
}
| title | getCallBackFollowmeCallInfo |
|---|
Описание:
Данная функция позволяет получить информацию об осуществленном CallBack вызове по его идентификатору.
Входные параметры:
Name
Type
Description
customer_namestringИмя Кастомера, созданного в функции callBackCall_idstringУникальный идентификатор вызоваВыходные параметры:
Name
Type
Description
callBackFollowmeCallInfoStructarray of callBackFollowmeCallInfoСтруктуру callBackFollowmeCallInfo см. ниже в примере успешного запросаcallBackFollowmeCallInfo:
Name
Type
Description
destination_AstringНомер, куда дозвонилось плече Аdestination_BstringНомер, куда дозвонилось плече Вwaiting_period_AstringПериод ожидания плеча А waiting_period_ВstringПериод ожидания плеча В call_back_charged_length_AstringДлительность вызова плеча А (биллинговая)call_back_real_length_AstringДлительность вызова плеча А (реальная)call_back_charged_length_BstringДлительность вызова плеча B (биллинговая)call_back_real_length_BstringДлительность вызова плеча B (реальная)call_back_costnumberСтоимость вызоваcall_back_statusstringСтатус вызоваcall_back_record_URL_AarrayURL для получения записи вызова плеча А (срок действия ссылки 60 сек)call_back_record_URL_BarrayURL для получения записи вызова плеча В (срок действия ссылки 60 сек)callDescriptionstringКомментарий к вызовуАвторизация:
Авторизация осуществляется штатными средствами HTTP
Пример:
Запрос:
JSON:
{
"id": "101",
"jsonrpc": "2.0",
"method": "getCallBackFollowmeCallInfo",
"params": {
"customer_name" : "883140500000000",
"callBackCall_id" : "1256ffb10774226b390ad1a2bc892c9c"
}
}
Ответ:
Успешный ответ:
{
"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"
}
}
| title | setCallBackPrompt |
|---|
Описание:
Данная функция позволяет получить данные для загрузки файла CallBack prompt.
Входные параметры:
Name | Type | Description |
customer_name* | string | Имя Кастомера |
file_name | string | (Максимум 255 символов) |
Выходные параметры:
Name
Type
Description
uploadURLstring
Адрес для загрузки файла (POST)
statusURLstring
Адрес для проверки состояния загрузки (POST)
maxsizenumber
Максимально разрешенный размер файла в байтах
accepted_formatsobject
Допустимые расширения файлов и их 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:
|
Ответ:
Успешный ответ:
{
"jsonrpc":"2.0",
"id":"1",
"result":
{
"uploadURL":"https:\/\/fuds1.mtt.ru\/upload\/fd36dc6c32ce0bb33d5084c877b09675",
"statusURL":"https:\/\/fuds1.mtt.ru\/status\/fd36dc6c32ce0bb33d5084c877b09675",
"maxsize":1048576,
"accepted_formats":
{
"aif":[
"audio\/x-aiff",
"audio\/aiff"
],
...
}
}
}
Не успешный ответ:
{
"jsonrpc": "2.0",
"id": "1",
"error":
{
"code": -32002,
"message": "Permission denied",
"data": "agent does not have access to this customer"
}
}
| title | getCallBackPromptInfo |
|---|
Описание:
Данная функция позволяет получить список загруженных клиентом промтов.
Входные параметры:
Name | Type | Description |
customer_name | string | Имя Кастомера |
Выходные параметры:
Name
Type
Description
resultarray Список загруженных клиентом промптов и дат их загрузки.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"
}
}
| title | setCallBackFollowme |
|---|
Описание:
Данная функция создает список номеров, на которые будет осуществляться переадресация CallBack вызова, плечо А.
Предварительная установка структуры вызова (callBackFollowmeStruct).
Входные параметры:
Name
Type
Description
customer_name*stringИмя Кастомера, созданного в функции callBackFollowmeStruct*array of callBackFollowmeStructСтруктуру callBackFollowmeStruct см. ниже в примере успешного запросаcaller_idstringНомер, который будет показан абоненту плеча В.Данный параметр должен устанавливаться, либо в функции setCallBackFollowme либо в функции makecallbackfollowme.defaultBNumberstringНомер по умолчанию, для дозвона на плечо BcallBackFollowmeStruct:
Name
Type
Description
ordernumberПорядок следования номера при перенаправлении(переадресации) вызоваtimeoutnumberТаймаут (в секундах)- время дозвона с момента отправки Json запроса на осуществление вызова до прекращения дозвона. Рекомендуется устанавливать значение от 10 секунд.redirect_numberstringНомер для перенаправления вызова (реальный номер, который будет осуществлен вызов. Плечо А.)typestringТип очереди, файла, текста.namestringСимвольное имя номера для перенаправления вызова, например "sales1"/"sales2"/"boss"sidestringПлечо для проигрывания файла или сообщения (А или В)valuestringИнформация для проигрывания или имя файлаПояснения к параметру "type"
1) Тип очереди:
Ringall - вызываются все участники структуры, переданные в callBackFollowmeStruct (плечо А) ;
Lineral - вызов участников группы ( плечо А), переданных в callBackFollowmeStruct, происходит последовательно.
2) Тип проигрываемого сообщения для плеча А/B:
"type": "text", - задается "Text to speech"(текст в речь);
"type": "file", задается ранее установленный файл в функции "SetCallBackPrompt".
Выходные параметры:
Name | Type | Description |
success | number | 1 = Структура успешно добавлена |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON:
{
"id": "1",
"jsonrpc": "2.0",
"method": "setCallBackFollowme",
"params": {
"customer_name": "883140500000000",
"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,
"type": "text", - задается "Text to speech"( текствречь) "value": "Звонок с сайта все продам ру",
"side": "A"
},
{
"order": 6,
"type": "file", задается ранее установленный файл в функции "SetCallBackPrompt"
"value": "for_all_sales",
"side": "B"
}
],
"caller_id": "74951001010",
"defaultBNumber": "79511234567"
}
}
Ответ:
Успешный ответ:
|
Не успешный ответ:
{
"jsonrpc":"2.0",
"id":"101",
"result":
{
"error":1,
"error_description":"Side A not clear. Delete before insert" - попытка установки логики звонка поверх имеющейся логики. Необходимо выполнить deleteCallBackFollowme.
}
}
| title | getCallBackFollowme |
|---|
Описание:
Данная функция позволяет получить список номеров, на которые будет осуществляться переадресация 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"
}
}
| title | deleteCallBackFollowme |
|---|
Описание:
Данная функция удаляет список номеров, на которые будет осуществляться переадресация 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"
}
}
| title | Events уведомления |
|---|
Уведомления о ходе вызова
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 и А
| title | Функционал Управление входящим вызовом |
|---|
Описание: функционал позволяет клиенту, в момент поступления звонка от пользователя:
- получать от платформы МТТ запрос к 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
Ввод добавочного номера.Список возможных символов: 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:
| title | updateCallControlURL |
|---|
Описание:
Данный метод позволяет установить или обнулить 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 уведомлений о ходе вызова
| Expand | ||
|---|---|---|
| ||
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" - Номер для перенаправления вызова |
Резервирование переадресации входящего вызова
Для осуществления резервирования переадресации входящего вызова при недоступности клиентского URL необходимо установить "оффлайн" переадресации ("number") для конкретного sip_id методом API:
| title | setReserveCallControlNumber |
|---|
Точка входа : https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
POST запрос
Описание:
Метод setReserveCallControlNumber позволяет установить или обнулить номер резерва для услуги УВВ.
Входные параметры:
Name
Type
Description
sip_id stringsip_id аккаунтаstringСтрока содержащая numberВыходные параметры:
Name
Type
Description
success number Индикатор успеха Авторизация:
Авторизация осуществляется штатными средствами HTTP
Пример:
Запрос:
JSON:
{ "id": "1", "jsonrpc": "2.0", "method": "setReserveCallControlNumber", "params": { "sip_id":"73432143178", "number":"79991112233" }}
Ответ:
Успешный ответ:
{ "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" }}
Для всех кодов ответа от клиентского URL на запрос логики переадресации getControlCallFollowMe , отличных от HTTP 200, МТТ использует заранее предустановленную «оффлайн» переадресацию.
Просмотр установленного клиентского URL и резервного номера для "оффлайн" переадресации
Для этого используется метод API:
| title | getAccountCustomFields |
|---|
Точка входа : https://webapicommon.mtt.ru/index.php
Авторизация: Basic Auth
POST запрос
Описание:
Метод getAccountCustomFields позволяет получить установленный URL и резервный номер для "оффлайн" переадресации
Входные параметры:
Name
Type
Description
sip_id stringsip_id аккаунта, номер МТТВыходные параметры:
Name
Type
Description
GN_IP_IPCR number URL клиента для отправки запроса getControlCallFollowMe GN_IPCR_RESERVEnumber Резервный номер для "оффлайн" переадресацииi_accountnumber внутренний идентификатор на платформе МТТАвторизация:
Авторизация осуществляется штатными средствами 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" } }
| title | Автоматическое информирование по API (Голосовые SMS) |
|---|
Сценарий - клиент отправляет 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
Язык.
Допустимые значения:
· ru-RU (по умолчанию) — русский язык,
· en-US — английский язык.·
ru
Голос синтезированной речи.
Можно выбрать один из следующих голосов:
· женские голоса: alyss, jane, oksana и omazh;
· мужские голоса: zahar, ermil, erkanyavas.
erkanyavas
Эмоциональная окраска голоса.
Допустимые значения:
· good — радостный, доброжелательный;
· evil — раздраженный;
· neutral — нейтральный.
neutral
Скорость (темп) синтезированной речи.
Скорость речи задается дробным числом в диапазоне от 0.1 до 3.0. Где:
· 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" - факт разъединения или недозвона
где:
* - все существующие 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"}]
| title | API информирование с динамическим определением действий (перевод/нотификация на URL) |
|---|
Функционал позволяет в 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
Язык.
Допустимые значения:
· ru-RU (по умолчанию) — русский язык,
· en-US — английский язык;
· tr-TR — турецкий язык.
ru
Голос синтезированной речи.
Можно выбрать один из следующих голосов:
· женские голоса: alyss, jane, oksana и omazh;
· мужские голоса: zahar, ermil, erkanyavas.
erkanyavas
Эмоциональная окраска голоса.
Допустимые значения:
· good — радостный, доброжелательный;
· evil — раздраженный;
· neutral — нейтральный.
neutral
Скорость (темп) синтезированной речи.
Скорость речи задается дробным числом в диапазоне от 0.1 до 3.0. Где:
· 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
| title | SMS API |
|---|
Точка подключения:https://msapi.mtt.ru:443/
| title | GetNumbers - Получение номеров аккаунта |
|---|
Для получения номеров аккаунта необходимо сделать GET запрос к /accounts/{accountSID}/numbers.
Входящие параметры:
Name
Type
Description
limitint
Лимит выводимых данных
offsetint
Смешение относительно начала
Возвращаемые параметры:
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 {Login}:{Password}
Ответ 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-го номера.
| title | Messagessending – Отправка сообщений |
|---|
Для отправки сообщения необходимо сделать POST запрос к
/v2/accounts/{account_sid}/messages
Входящиепараметры:
Name
Type
Description
from
string
Номер отправителя
to
string
Номер получателя
text
string
Текст сообщения
tag
string
Необязательное пользовательское поле, может использоваться для установки уникального идентификатора каждого сообщения.
Возвращаемые параметры:
Name
Type
Description
status_codeinteger Статус запроса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"
}
| title | GetMessageHistory - Получение истории сообщения |
|---|
Для получения истории сообщений необходимо выполнить GET запрос к /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,| title | Get Message Info - Получение информации по сообщению |
|---|
Для получения информации по сообщении необходимо выполнить GET запрос к /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, } ]}| Expand | ||
|---|---|---|
| ||
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 |
| title | Premedia API |
|---|
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
| title | CreateCustomerPrompt |
|---|
Создаёт 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
Загрузка prompta (аудио файла)
{
"id": "1",
"jsonrpc": "2.0",
"method": "createCustomerPrompt",
"params":
{
"customer_name" : "110000777",
"prompt_name": "116",
"prompt_type" : "file",
"prompt_file_contents": "����h���'�"
}
}
Загрузкатекста (TTS) {
"id": "1",
"jsonrpc": "2.0",
"method": "createCustomerPrompt",
"params":
{
"customer_name" : "110000777",
"prompt_name": "116",
"prompt_type" : "text",
"prompt_file_contents": "Ваш звонок судьбоносен для нас"
}
}
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
{
"jsonrpc": "2.0",
"id": "1",
"error": {
"code": -32601,
"message": "Data not found",
"data": [
{
"code": "V_VALUE_NOT_FOUND",
"attribute": "customer_id",
"message": "customer_name «79991234568» not found.",
"tpl": "{attribute} «{value}» not found.",
"tplParams": {
"value": "79991234568",
"attribute": "customer_name"
}
}
]
}
}
{
"jsonrpc":"2.0",
"id":55585,
"error":
{
"code":-32602,
"message":"Invalid params",
"data":
[
{
"code":"V_VALUE_ALREADY_EXISTS",
"attribute":"prompt_name",
"message":"prompt_name «TTS_file12.wav» already exists.",
"tpl":"{attribute} «{value}» already exists.",
"tplParams":
{
"value":"TTS_file12.wav",
"attribute":"prompt_name"
}
}
]
}
}
| title | GetCustomerPrompts |
|---|
Возвращает информацию о всех промтах предустановленных для customer'а в premedia api.
Входные параметры:
Name
Type
Description
customer_name*stringИдентификатор customer'а.* - обязательные поля
Выходные параметры:
Name
Type
Description
id
integer
Идентификатор промта в premedia apinamestringНазвание файла промтаАвторизация:
Авторизация осуществляется штатными средствами HTTP
Пример:
Запрос:
JSON
{
"id": "1",
"jsonrpc": "2.0",
"method": "getCustomerPrompts",
"params":
{
"customer_name": 110000777
}
}
Ответ:
Успешный ответ:
JSON
{
"jsonrpc":"2.0",
"id":"1",
"result":
{
"prompts_list":
[
{
"id":1,
"name":"116.mp3",
"file_id": "c20ed66245ae695fc35f846ef3f35e94"
},
{
"id":2,
"name":"TTS_116.mp3",
"file_id": "a11b494d3952ff1fb2b7de375524db41"
}
]
}
}
Не успешный ответ:
JSON
{
"jsonrpc":"2.0",
"id":"1",
"error":
{
"code":-32001,
"message":"Data not found",
"data":
[
{
"code":"V_VALUE_NOT_FOUND",
"attribute":"i_customer",
"message":"customer_name «1012» not found.",
"tpl":"{attribute} «{value}» not found.",
"tplParams":
{
"value":1012,
"attribute":"customer_name"
}
}
]
}
}
| title | DeleteCustomerPrompt |
|---|
Описание:
Удаляет prompt customer'а.
Входные параметры:
Name | Type | Description |
customer_name* | string | Идентификатор customer'а. По соглашению было принято использовать i_customer. |
prompt_name* | string | Имя prompt'а |
* - обязательные поля
Выходные параметры:
Name | Type | Description |
success | bool | Успешность выполнения |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
{
"jsonrpc":"2.0",
"id":"1",
"error":
{
"code":-32001,
"message":"Data not found",
"data":
[
{
"code":"V_VALUE_NOT_FOUND",
"attribute":"prompt_name",
"message":"prompt_name «file4.wav.mp3a» not found.",
"tpl":"{attribute} «{value}» not found.",
"tplParams":
{
"value":"file4.wav.mp3a",
"attribute":"prompt_name"
}
}
]
}
}
| title | UpdatePremediaAccountSettings |
|---|
@ "scenario_id": "1" - проигрывание промта/TTS в сторону А-номера;
@ "scenario_id": "2" - проигрывание промта/TTS в сторону принимающего вызов (С-номер);
@ "scenario_id": "3" - проигрывание промта/TTS в сторону А-номера и в сторону принимающего вызов (С-номер - redirect number).
Входные параметры:
Name
Type
Description
sip_id*stringИдентификатор account'а.scenario_id*integerИдентификатор сценария
answerintegerФлаг предответного состояния - 0, 1 (default 0)
* - обязательные поля
Выходные параметры:
Name | Type | Description |
success | bool | Успешность выполнения |
Авторизация:
Авторизация осуществляется штатными средствами HTTP
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32001,
"message": "Data not found",
"data": [
{
"code": "V_VALUE_NOT_FOUND",
"attribute": "sip_id",
"message": "sip_id «79991111112» not found.",
"tpl": "{attribute} «{value}» not found.",
"tplParams": {
"value": "79991111112",
"attribute": "sip_id"
}
}
]
}
}
{
"jsonrpc":"2.0",
"id":45630,
"error":
{
"code":-32001,
"message":"Data not found",
"data":
[
{
"code":"V_VALUE_NOT_FOUND",
"attribute":"scenario_id",
"message":"scenario_id «4» not found.",
"tpl":"{attribute} «{value}» not found.",
"tplParams":
{
"value":"4",
"attribute":"scenario_id"
}
}
]
}
}
{
"jsonrpc":"2.0",
"id":45630,
"error":
{
"code":-32602,
"message":"Invalid params",
"data":
[
{
"code":"V_VALUE_NOT_IN_LIST",
"attribute":"answer",
"message":"answer 3 must be one of those valid values 0,1.",
"tpl":"{attribute} {currentvalue} must be one of those valid values {value}.",
"tplParams":
{
"attribute":"answer",
"currentvalue":"3",
"value":"0,1"
}
}
]
}
}
| title | SetAccountPrompt |
|---|
Метод привязывает к аккаунту уже загруженный ранее промт, согласно ранее установленному сценарию.
Входные параметры:
Name
Type
Description
sip_id*stringИдентификатор account'а.prompt_name*integerИмя промпта (ранее загруженного)
side*string
Какому плечу (A или B) будет проигрываться промпт
* - обязательные поля
Выходные параметры:
Name | Type | Description |
success | bool | Успешность выполнения |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32001,
"message": "Data not found",
"data": [
{
"code": "V_VALUE_NOT_FOUND",
"attribute": "sip_id",
"message": "sip_id «79991111112» not found.",
"tpl": "{attribute} «{value}» not found.",
"tplParams": {
"value": "79991111112",
"attribute": "sip_id"
}
}
]
}
}
{
"jsonrpc":"2.0",
"id":45630,
"error":
{
"code":-32602,
"message":"Invalid params",
"data":
[
{
"code":"V_VALUE_NOT_IN_LIST",
"attribute":"side",
"message":"side C must be one of those valid values A, B.",
"tpl":"{attribute} {currentvalue} must be one of those valid values {value}.",
"tplParams":
{
"attribute":"side",
"currentvalue":"C",
"value":"A, B"
}
}
]
}
}
| title | UnsetAccountPrompt |
|---|
Удаляет у account'а привязку промта, установленного для указанного плеча.
Входные параметры:
Name
Type
Description
sip_id*stringИдентификатор account'а.side*string
К какому плечу (A или B) привязанный промпт нужно удалить
* - обязательные поля
Выходные параметры:
Name | Type | Description |
success | bool | Успешность выполнения |
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
|
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32001,
"message": "Data not found",
"data": [
{
"code": "V_VALUE_NOT_FOUND",
"attribute": "sip_id",
"message": "sip_id «79991111112» not found.",
"tpl": "{attribute} «{value}» not found.",
"tplParams": {
"value": "79991111112",
"attribute": "sip_id"
}
}
]
}
}
| title | getPremediaAccountSettings |
|---|
Просмотр установленного сценария Premedia c выводом привязанных промтов.
Входные параметры:
Name | Type | Description |
sip_id* | string | Идентификатор account'а. |
* - обязательные поля
Выходные параметры:
Name
Type
Description
sip_idstringИдентификатор промпта в премедиа апиanswerbooleanЗначение флага ответного/предответного состоянияdiversionbooleanЗначение флага установки переадресацииscenario_idintegerИдентификатор сценарияscenario_namestringНаименование сценарияpromptsarrayИнфо о промтах привязанных к аккаунту для плечей A,BАвторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
{
"id": "1",
"jsonrpc": "2.0",
"method": "getPremediaAccountSettings",
"params":
{
"sip_id" : "74951348579"
}
}
Ответ:
Успешный ответ:
JSON
{
"jsonrpc":"2.0",
"id":"1",
"result":
{
"sip_id":"74951348579",
"answer":false,
"diversion":true,
"scenario_id":3,
"scenario_name":"Premedia Сценарий 3",
"prompts":
{
"a_prompt":
{
"id":2,
"name":"116.mp3"
},
"b_prompt":
{
"id":2,
"name":"TTS_116.mp3"
}
}
}
}
| title | setFollowme |
|---|
Устанавливает настройки переадресациии на Premedia аккаунте.
Входные параметры:
Name
Type
Description
sip_id*stringИдентификатор аккаунта
sequence
string:range(Order,Random,Simultaneous)
Тип сортировки при обзвоне списка правил. По умолчанию Order
caller_id
string
Отображаемый номер А-номер при переадресации
Допустимый формат: ^7\d{10}$ ("7"+10цифр).
followmeStructurearray
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
{
"jsonrpc":"2.0",
"method":"setFollowme",
"id":45630,
"params":{
"sip_id":"74951348579",
"caller_id":"74951348579",
"sequence": "Simultaneous",
"followmeStructure": [
{
"redirect_number": "79163777604",
"name": "79163777604",
"active": "Y",
"timeout":15,
"follow_order": 1
},
{
"redirect_number": "79636793312",
"name": "79636793312",
"active": "Y",
"follow_order": 2
}
]
}
}
Ответ:
Успешный ответ:
JSON
|
Не успешный ответ:
JSON
{
"jsonrpc":"2.0",
"id":45630,
"error":
{
"code":-32602,
"message":"Invalid params",
"data":
[
{
"code":"V_REGEX_DO_NOT_MATCH",
"attribute":"caller_id",
"message":"The caller_id property must match regular expression /^7\\d{10}$/.",
"tpl":"The {attribute} property must match regular expression {pattern}.",
"tplParams":
{
"attribute":"caller_id",
"pattern":"/^7\\d{10}$/"
}
}
]
}
}
{
jsonrpc":"2.0",
"id":45630,
"error":
{
"code":-32603,
"message":"Internal error",
"data":
[
{
"code":"A_CAPI_SET_FOLLOWME",
"attribute":"sip_id",
"message":"Failed to set follow_me for account sip_id «74951346313»",
"tpl":"Failed to set follow_me for account {attribute} «{value}»",
"tplParams":
{
"attribute":"sip_id",
"value":"74951346313"
}
}
]
}
}
| title | getFollowmeAccountSettings |
|---|
Возвращает информацию о настройках переадресаций account'а.
Входные параметры:
Name
Type
Description
sip_id*stringИдентификатор account'а.* - обязательные поля
Выходные параметры:
Name
Type
Description
sip_idstringИдентификатор account'а.sequencestringstring:range(Order,Random,Simultaneous)Тип сортировки при обзвоне списка правил.caller_idstringОтображаемый А-номер при переадресации
followmeStructurearrayMассив настроек follow_meФормат элементов followmeStructure:
Name
Type
Description
redirect_numberstringНомер для переадресации
namestringНаименование follow_me записиtimeoutintegerВеличина таймаута
activestring:range(Y,N)Флаг активно/неактивно
follow_orderintegerНомер в очереди переадресации
Авторизация:
Авторизация осуществляется штатными средствами HTTP.
Пример:
Запрос:
JSON
{
"id": "1",
"jsonrpc": "2.0",
"method": "getFollowmeAccountSettings",
"params":
{
"sip_id" : "74951348579"
}
}
Ответ:
Успешный ответ:
JSON
{
"jsonrpc":"2.0",
"id":"1",
"result":
{
"sip_id":"74951348579",
"sequence":"Order",
"caller_id":"74951348579",
"followmeStructure":
[
{
"redirect_number":"79163777604",
"name":"79163777604",
"active":"Y",
"follow_order":"1",
"timeout":"25"
},
{
"redirect_number":"79636793312",
"name":"79636793312",
"active":"Y",
"follow_order":"2",
"timeout":"15"
}
]
}
}
Не успешный ответ:
JSON
{
"jsonrpc":"2.0",
"id":"1",
"error":
{
"code":-32002,
"message":"Permission denied",
"data":
[
{
"code":"C_PERMISSION_DENIED",
"attribute":"common\\models\\premedia\\api\\Account",
"message":"You don't have access to this common\\models\\premedia\\api\\Account «».",
"tpl":"You don't have access to this {attribute} «{value}».",
"tplParams":
{
"value":"",
"attribute":"common\\models\\premedia\\api\\Account"
}
}
]
}
}
{
"jsonrpc":"2.0",
"id":45630,
"error":
{
"code":-32602,
"message":"Invalid params",
"data":
[
{
"code":"V_VALUE_NOT_FOUND",
"attribute":"sip_id",
"message":"sip_id « 74951346313» not found.",
"tpl":"{attribute} «{value}» not found.",
"tplParams":
{
"attribute":"sip_id",
"value":" 74951346313"
}
}
]
}
}
| title | Покупка номеров по API |
|---|
Доступ к функции осуществляется по протоколу HTTPS:
Точка подключения: https://gapi.mtt.ru:6443/v1/api
Авторизация: Basic Auth
Метод: POST
| title | addNumbers |
|---|
Описание:
Данная функция добавляет номера Клиенту.
Входные параметры:
Name
Type
Description
region_code*
string
Код региона, например (MOW)
quantity*
string
Количество добавляемых номеров
dial_codestring
Код набора (напр. 495)
* - обязательные поля
Выходные параметры:
Name
Type
Description
number_listint Список добавленных номеровАвторизация:
Авторизация осуществляется штатными средствами 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 необходимо добавление хотя бы одного номера данного региона на лицевой счет.
Данное действие производится через персонального менеджера.
| title | Функционал управления черным списком (BlackList) |
|---|
Доступ к функции осуществляется по протоколу HTTPS:
Точка подключения: https://gapi.mtt.ru:6443/v1/api
Авторизация: Basic Auth
Метод: POST
| title | addGBLRule |
|---|
Description:
Добавляет номер в Global Black List.
Input parameters:
Name
Type
Description
gbl_rule
string
Phone number to be forbidden
Output parameters:
Name
Type
Description
successinteger: [0,1]Result success flagAuthorization:
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"
}
}
]
}
}
| title | deleteGBLRule |
|---|
Description:
Удаляет номера из Global Black List.
Input parameters:
Name
Type
Description
gbl_rule
string
Phone number to be forbidden
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"
}
}
]
}
}
| title | getGBLRules |
|---|
Description:
Получает все номера из Global Black List установленные для учётной записи.
Input parameters:
Name
Type
Description
Output parameters:
Name
Type
Description
gbl_rulesarrayArray of phone numbersAuthorization:
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"
}
}
]
}
}
| title | WebSdk - звонок с сайта |
|---|
«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
Для получения параметров подключения к сети МТТ необходимо обратиться к персональному менеджеру.
| |
По вопросам подключения/интеграции Telecom API необходимо обратиться по почте api.sale@mtt.ru В письме просьба указать:
Наш менеджер свяжется с Вами в ближайшее время. |
| Info | ||||
|---|---|---|---|---|
| ||||
|
По умолчанию в запросах в сторону API клиента отрыты только 80 и 443 порты.