- Created by Матвеев Говард Владимирович, last modified by Ляпин Михаил Вадимович on Feb 10, 2020
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 52 Next »
Точка подключения: 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 | Время платформы |
connect_time | string | Время звонка |
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 | Начальная дата и время (необязательный) | |||||||||||||||
date_to | string | Конечная дата и время (необязательный) | |||||||||||||||
filter | string | Номер, для фильтрации вызовов по "cli" и "cld" | |||||||||||||||
order | string | Сортировка - возможные значения ASC (по умолчанию) и DESC | |||||||||||||||
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:
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 | Имя существующего кастомера |
Выходные параметры:
Name | Type | Description |
account_list | array of AccountInfo | Список аккаунтов кастомера |
AccountInfo
Name | Type | Description |
sip_id | string | Идентификатор аккаунта |
activation_date | date(format:Y-m-d) | Дата активации аккаунта |
* Обязательные поля
Авторизация:
Авторизация осуществляется штатными средствами 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.
Пример запроса с ранее установленной структурой вызова (см. п. 2.5):
JSON:
{ "id": "1", "jsonrpc": "2.0", "method": "makeCallBackCallFollowme", "params": { "customer_name" : "883140500000000", "b_number" : "+79157775533" } } |
Пример запроса без предварительной установки структуры вызова - функцией setCallbackfollowme (п.2.5), передача структуры 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" - Номер для перенаправления вызова
Резервирование переадресации входящего вызова
Для осуществления резервирования переадресации входящего вызова при недоступности клиентского 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": ["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 — английский язык; · 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 |
* - обязательные параметры
Авторизационные данные для 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"}]
Точка подключения:https://msapi.mtt.ru:443/
Для получения номеров аккаунта необходимо сделать GET запрос к /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 {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-го номера.
Для отправки сообщения необходимо сделать 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 запрос к /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 запрос к /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
Для получения параметров подключения к сети МТТ необходимо обратиться к персональному менеджеру.
- No labels