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

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


Точка подключения: 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

Ошибка и её описание

Пример

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



Кейс: Клиент отправил запрос указанный в примере, МТТ инициировал вызов абоненту (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"
}