Запрос на отправку голосовых сообщений#

IVR HTTP API позволяет Партнеру направлять запросы Сервис-провайдеру на отправку абоненту IVR-сообщений.

Формат запроса#

  • Методы запроса: GET или POST;

  • максимальная длина URI GET-запроса: 1024 символа;

  • при превышении длины URI GET-запроса необходимо использовать POST-запрос. Параметры в POST-запросах размещаются в теле запроса. Content-Type: application/x-www-form-urlencoded;

  • кодировка символов: UTF-8 (рекомендовано).

Пример запроса#

{
   http::/rapporto.ru:9002/ivr?msisdn=79031234567@text=привет@caller_id=79999999999
}

Параметры запроса#

Параметры применимы для GET и POST запросов.

Из параметров mp3_url (или mp3_id) и text обязательным является только один.

Параметр order обязателен, если заданы оба параметра mp3_url и text.

Параметр

Описание

msisdn

Номер телефона абонента.

mp3_url
HTTP ссылка на mp3-файл.
Максимальный размер файла .mp3: 2 МБайт.
Файл кэшируется системой по URL.

Процесс кэширования mp3-файлов по HTTP-ссылке:

  1. Если запрос с указанным URL поступает впервые, файл скачивается и помещается в кэш.

  2. При повторном запросе с тем же URL выполняется проверка времени хранения файла в кэше (настраиваемый параметр, по умолчанию — 10 минут).

Если файл хранится в кэше менее определенного периода, файл берется из кэша.
Если срок хранения превышает указанный период:

  1. Файл загружается с указанного URL.

  2. Сравнивается контрольная сумма загруженного файла с контрольной суммой файла в кэше.

При несовпадении кэш обновляется.

mp3_id

Идентификатор mp3-файла, ранее загруженный пользователем в веб-интерфейсе системы. Только один из параметров — mp3_url или mp3_id может быть указан в запросе.

text

Зачитываемый текст.

voice_type
Если задан text, то этот параметр определяет на каком языке и каким голосом (женским или мужским) этот текст будет зачитан.
Возможные значения:

  • russian_male;

  • russian_female;

  • english_male;

  • english_female.

По умолчанию: russian_female.

order
Порядок проигрывания звукового файла и зачитывания текста.
Возможные значения:

  • file_first — сначала файл;

  • text_first — сначала текст.

По умолчанию: text_first.

caller_id
Номер, от имени которого производится звонок.
Партнёр должен указывать в запросе этот параметр только в случае, если необходимо отправлять голосовые сообщения с разных номеров.
Организация работы с разными номерами требует дополнительной настройки платформы и предварительного согласования.
Если все звонки Партнера производятся с единого номера:

  • указывать этот параметр не требуется;

  • номер настраивается на платформе.

retry_count

Количество попыток дозвона. По умолчанию: 1.

retry_interval

Период в минутах между попытками дозвона. По умолчанию: 1 минута. Параметры отправки абоненту SMS-уведомлений (количество и названия параметров могут отличаться в зависимости от требований сценария):

  • sms_dtmf0 — текст сообщения для события «абонент нажал клавишу 0»;

  • …

  • sms_dtmf9 — текст сообщения для события «абонент нажал клавишу 9».

sms_dtmf_asterisk

Текст сообщения для события «абонент нажал клавишу *».

sms_dtmf_numbersign

Текст сообщения для события «абонент нажал клавишу #».

sms_dtmf_any

Текст сообщения для события «абонент нажал любую клавишу».

sms_dtmf_none

Текст сообщения для события «звонок успешен, абонент не нажал никакую клавишу».

sms_call_failed

Текст сообщения для события «дозвониться не удалось».

start_time
Время начала отправки голосовых сообщений, формат HH24:MM.
Необязательный параметр. Имеет больший приоритет, чем аналогичная настройка по умолчанию.

end_time
Время окончания отправки голосовых сообщений, формат HH24:MM.
Необязательный параметр. Имеет больший приоритет, чем аналогичная настройка по умолчанию.

Важно

Из параметров mp3_url (или mp3_id) и text требуется указать только один. Параметр order становится обязательным, если указаны оба параметра mp3_url и text.

Ответ на запрос#

На запрос Партнера Платформа возвращает ответ в формате XML.

Пример ответа при успешной отправке запроса#

На успешный запрос Сервис-провайдер возвращает Партнёру:

  • result=true — значение «true» означает, что запрос был обработан успешно;

  • id — числовой идентификатор нового сообщения, поставленного в очередь на обработку.

<?xml version="1.0" encoding="utf-8"?>
<response>
  <result>true</result>
  <id>197</id>
</response>

Ответ на запрос в случае ошибки#

При передаче ошибочного запроса в ответе возвращаться короткое текстовое сообщение об ошибке:

  • result=false — значение «false» означает, что запрос не был обработан успешно;

  • error — сообщение об ошибке, указывающее на конкретную проблему с запросом. В данном случае ошибка связана с некорректным значением параметра msisdn.

Примечание

Описание ошибок приведено ниже.

<?xml version="1.0" encoding="utf-8"?>
<response>
  <result>false</result>
  <error>Incorrect msisdn parameter</error>
</response>

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

В таблице приведено описание ошибок (содержимое элемента error в ответе на запрос).
Вместо квадратных скобок будут отображены значения соответствующих параметров запроса, либо настроек системы.

Код ошибки

Описание

Incorrect msisdn parameter [parameter value]!

Номер телефона, на который производится звонок, некорректен (не соответствует настроенному профилю номерной емкости) или отсутствует.

Conflicting parameters mp3_url and mp3_id!

В запросе были заданы оба параметра mp3_url и mp3_id, что является недопустимым.

One of parameters mp3_url or mp3_id or text is required!

Не был задан ни один из параметров mp3_url, mp3_id или text.

Mp3 file id=[id value] not found!

Не найден .mp3 файл с заданным id.

Invalid parameter mp3_id value!

Некорректное значение параметра mp3_id (указанное значение не является целым положительным числом).

Invalid voice_type parameter [voice_type value]!

Некорректно задан параметр voice_type. Возможные значения: russian_male, russian_female, english_male, english_female.

Invalid order parameter [order value]!

Некорректно задан параметр order, возможные значения: file_first, text_first.

Param caller_id is mandatory

Не задан параметр caller_id, который является обязательным.

Param retry_count [retry_count value] is greater than its max value [max value]

Параметр retry_count больше своего максимально допустимого значения.

Param retry_count is absent or invalid

Параметр retry_count отсутствует или некорректен (указанное значение не является целым положительным числом).

Param retry_interval [retry_interval value] is greater than its max value [max value]

Параметр retry_interval больше своего максимального значения.

Param retry_interval is absent or invalid

Параметр retry_interval отсутствует или некорректен (указанное значение не является целым положительным числом).

Internal error

Внутренняя ошибка, обратитесь в Службу технической поддержки.