API информирование с динамическим определением действий (перевод/нотификация на URL)

Оглавление:

Функционал позволяет в API запросе дополнительно указать структуру действий, наряду с текстом информирования для синтеза: перевод абонента на оператора, получения обратной связи на URL. Метод инициирует вызов на номер с заданными параметрами.

Клиент присылает API запрос на инициирование вызова, включающий текст для клиента и структуру DTMF параметров.
При выборе абонентом DTMF (в том числе вариант с проговариванием голосом: один, два...) с:

type=transfer - идет перенаправление вызова (callback) на полученный номер, с передачей онлайн событий о ходе вызова.
type=notify - идет нотификация/event на полученный URL (https). По факту осуществления нотификации абоненту проговаривается стандартный текст "Спасибо за Ваш выбор, до свидания!"

Точка подключения: https://sb-api.mtt.ru/v1/sb

Авторизация: Basic Auth

Метод: POST

Входные параметры

Name	Type	Description
method	string	method
data		Набор данных инициировании вызова
dtmf		Набор данных по возможным dtmf и действиям

data

Параметр	Описание	Значение по умолчанию
b_number*	Номер пользователя, на который инициируем вызов: Б-номер телефона, строго 11 цифр, E.164	none
sip_id*	Номер МТТ, учетная запись	none
messId*	Идентификатор запроса со стороны клиента МТТ	none
messText*	Текст для воспроизведения пользователю	none
a_number*	Номер для отображения пользователю при входящем звонке: А-номер телефона, строго 11 цифр, E.164	none
langCode	Язык. Допустимые значения: ru-RU (по умолчанию) — русский язык, en-US — английский язык; tr-TR — турецкий язык.	ru
voice_name	Голос синтезированной речи. Можно выбрать один из следующих голосов: женские голоса: alyss, jane, oksana и omazh; мужские голоса: zahar, ermil, erkanyavas.	erkanyavas
emotion	Эмоциональная окраска голоса. Допустимые значения: good — радостный, доброжелательный; evil — раздраженный; neutral — нейтральный.	neutral
speed_speech	Скорость (темп) синтезированной речи. Скорость речи задается дробным числом в диапазоне от 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"
            }
        ]
    }
}

Успешный ответ

JSON

{
    "result": {
        "success": 1
    },
    "id": "1255490",
    "CallID": "00035c7d92bb0971"
}

Не успешный ответ

JSON

//Невалиден формат 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

JSON

{
    "date_time": "date_time",
    "id": "messId",
    "CallID": "CallID",
    "event": "o_b_number
}

1.2 Формат события окончания вызова

JSON

{
    "date_time": "date_time",
    "id": "messId",
    "CallID": "CallID",
    "event": "h_ b_number_cause_duration*"
}

* - в duration указано общее время вызова: TTS+разговор с оператором

Примеры:

Абонент снял трубку, прослушал текст:

JSON

{
    "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"
}

Абонент занят

JSON

{
    "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"
}

Абонент недоступен:

JSON

{
    "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:

JSON

{
    "date_time": "date_time",
    "id": "messId",
    "CallID": "CallID",
    "dtmf": "dtmf_id",
    "type": "transfer",
    "event": "o_redirect_number"
}

Окончание переадресованного вызова:

JSON

{
    "date_time": "date_time",
    "id": "messId",
    "CallID": "CallID",
    "dtmf": "dtmf_id",
    "type": "transfer",
    "event": "h_redirect_number_cause_duration*"
}

* - в duration указано время переадресованного вызова, т.е. время общения с оператором

Пример:

Инициирование вызова на redirect_number при выборе dtmf=2:

JSON

{
    "date_time": "2019-03-29-11-38-00",
    "id": "1255490",
    "CallID": "00035c7d92bb0971",
    "dtmf": "2",
    "type": "transfer",
    "event": "o_78001000101"
}

Окончание переадресованного вызова:

JSON

{
    "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

JSON

{
    "date_time": "date_time",
    "id": "messId",
    "CallID": "CallID",
    "dtmf": "dtmf_id",
    "type": "notify",
    "event": "n_b_number"
}

Пример:

JSON

{
    "date_time": "2019-03-29-11-37-13",
    "id": "1255490",
    "CallID": "00035c7d92bb0971",
    "dtmf": "1",
    "type": "notify",
    "event": "n_79103880489"
}

2.3 Уведомление при не выборе абонентом dtmf

Формат при не выборе dtmf

JSON

{
    "date_time": "date_time",
    "id": "messId",
    "CallID": "CallID",
    "dtmf": "null",
    "type": "notify",
    "event": "n_b_number"
}

Пример:

JSON

{
    "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, после общения с оператором вызов завершился.

JSON

{
    "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"
}

Your Rating:

Page tree

API информирование с динамическим определением действий (перевод/нотификация на URL)

Входные параметры

data

dtmf

Выходные параметры

Пример

Успешный ответ

Не успешный ответ

Event уведомления - онлайн события о ходе вызова