Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

Оглавление:

Функционал позволяет в 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.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.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"
}

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