Voice API
Голосовое SMS — услуга, позволяющая запустить автоматизированный обзвон абонентов с предзаписанной аудиозаписью. Такая рассылка поможет рассказать клиентам об акции, напомнить про мероприятие или сообщить о статусе заказа без помощи менеджера.
Перед отправкой рассылки с помощью метода Create создайте ресурс голосового SMS — настроенный шаблон, к которому можно привязать аудиофайл, предварительно загруженный в аудиобиблиотеку приложения, и установить логику перевода на оператора, если абоненту нужна консультация. В результате вы получите идентификатор этого ресурса — используйте его для звонка на номера ваших абонентов в рамках метода MakeVoiceMessage.
Voice API — программный интерфейс, позволяющий управлять ресурсами голосовых SMS и отправлять голосовые рассылки абонентам. используйте следующие методы:
-
Create — создаёт ресурс голосового SMS в приложении;
-
GetList — получает список всех голосовых SMS приложения;
-
GetInfo — получает информацию о ресурсе голосового SMS;
-
Delete — удаляет ресурс голосового SMS приложения;
-
MakeVoiceMessage — отправляет голосовое SMS абоненту;
-
GetInfo — получает информацию об отправленном голосовом SMS.
Решения, где используется Voice API
Метод Create
Голосовое SMS — услуга, позволяющая запустить автоматизированный обзвон абонентов с предзаписанной аудиозаписью. Такая рассылка поможет рассказать клиентам об акции, напомнить про мероприятие или сообщить о статусе заказа без помощи менеджера. Перед отправкой рассылки создайте ресурс голосового SMS — настроенный шаблон, к которому можно привязать аудиофайл, предварительно загруженный в аудиобиблиотеку приложения, и установить логику перевода на оператора, если абоненту нужна консультация. В результате вы получите идентификатор этого ресурса — используйте его для звонка на номера ваших абонентов с помощью метода MakeVoiceMessage
Примените метод Create для создания ресурса голосового SMS. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.
Точка подключения:
POST: https://api.exolve.ru/voice-message/v1/Create
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.
Параметр | Тип | Описание |
---|---|---|
name | string | название голосового сообщения (SMS) |
media_id | uint64 | идентификатор аудиофайла, загруженного в аудиобиблиотеку этого приложение — его услышит принимающий абонент после поднятия трубки |
redirect_info | RedirectInfo | настройка переадресации вызова |
RedirectInfo
Параметр | Тип | Описание |
---|---|---|
digit | uint32 | клавиша, на которую принимающему абоненту нужно нажать, чтобы соединиться с оператором: от 0 до 9 (по умолчанию: 0) |
redirect_number | string | номер для переадресации в формате 79999999999 (9—14 цифр) |
После проигрывания аудиосообщения у принимающего абонента есть 30 секунд, чтобы нажать на нужную клавишу в тональном режиме. Иначе звонок автоматически завершается
Выходные параметры
Параметр | Тип | Описание |
---|---|---|
id | string | идентификатор ресурса голосового SMS |
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
400 | Bad Request | failed to parse token | неправильно указан токен (API-ключ приложения) |
401 | Unauthorized | error getting JWT Token claims | ошибка при парсинге JWT claims (части API-ключа, отвечающие за информацию о пользователе/приложении) |
403 | Forbidden | error":“Customer is not in correct status” | ошибка возникает, если не удается создать услугу голосового SMS из-за статуса аккаунта пользователя (не активирован/заблокирован) |
404 | Not Found | error getting media resource | не найден аудиофайл, id которого используется для создания услуги голосового SMS |
Примеры
Входные параметры:
{
"name": "Тестовая голосовая SMS",
"media_id": "1967",
"redirect_info": {
"digit":5,
"redirect_number": "79295800000"
}
}
Выходные параметры:
{
"id": "cal55094238-bc5f-4b2d-8a95-5a20d7cbb5bc"
}
Метод GetList
Примените этот метод для получения списка всех голосовых сообщений. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.
Точка подключения:
POST: https://api.exolve.ru/voice-message/v1/GetList
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Пустой JSON
Выходные параметры
Параметр | Тип | Описание |
---|---|---|
voice_message_list | array VoiceMessageList | информация об услугах голосового сообщения |
VoiceMessageList
Параметр | Тип | Описание |
---|---|---|
id | string | уникальный идентификатор услуги голосового сообщения |
name | string | название услуги голосового сообщения |
created_at | string | дата создания услуги голосового сообщения в формате RFC-3339 / ISO-8601 |
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
400 | Bad Request | failed to parse token | неправильно указан токен (API-ключ приложения) |
401 | Unauthorized | error getting JWT Token claims | ошибка при парсинге JWT claims (части API-ключа, отвечающие за информацию о пользователе/приложении) |
500 | Internal Server Error | error getting customer status | ошибка подключения к аккаунту пользователя |
Примеры
Входные параметры:
{}
Выходные параметры:
{
"voice_message_list": [
{
"id": "14b8d7b3-5468-418f-8592-b1d2127ad36b",
"name": "test",
"created_at": "2022-12-15T10:23:54.912Z"
},
{
"id": "40d781c9-a559-4175-82be-96d5fd4b1ca7",
"name": "test1",
"created_at": "2022-12-15T10:29:53.157Z"
}
]
}
Метод GetInfo
Примените этот метод для получения информации о голосовом сообщении. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.
Точка подключения:
POST: https://api.exolve.ru/voice-message/v1/GetInfo
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.
Параметр | Тип | Описание |
---|---|---|
id | string | уникальный идентификатор услуги голосового сообщения (SMS) |
Выходные параметры
Параметр | Тип | Описание |
---|---|---|
id | string | уникальный идентификатор услуги голосового сообщения |
name | sting | название услуги голосового сообщения |
digit | uint32 | цифра, на которую надо нажать, чтобы прошла переадресация |
redirect_number | string | номер для переадресации (9 - 14 символов) |
media_id | uint64 | уникальный идентификатор аудиофайла, который услышат клиенты, когда поднимут трубку |
created_at | string | дата создания услуги голосового сообщения в формате RFC-3339 / ISO-8601 |
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
400 | Bad Request | failed to parse token | неправильно указан токен (API-ключ приложения) |
401 | Unauthorized | error getting JWT Token claims | ошибка при парсинге JWT claims (части API-ключа, отвечающие за информацию о пользователе/приложении) |
500 | Internal Server Error | error getting customer status | ошибка подключения к аккаунту пользователя |
403 | Forbidden | error":“Customer is not in correct status” | ошибка возникает, если не удается создать услугу голосового SMS из-за статуса аккаунта пользователя (не активирован/заблокирован) |
404 | Not Found | Scenario not found | ID приложения запроса не соответствует ID в API-ключе |
Примеры
Входные параметры:
{
"id": "14b8d7b3-5468-418f-8592-b1d2127ad36b"
}
Выходные параметры:
{
"id": "14b8d7b3-5468-418f-8592-b1d2127ad36b",
"name": "test",
"digit": 5,
"redirect_number": "79269999999",
"media_id": 1979,
"created_at": "2022-12-22T11:19:36.567Z"
}
Метод Delete
Примените этот метод для удаления голосового сообщения (SMS). Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.
Точка подключения:
POST: https://api.exolve.ru/voice-message/v1/Delete
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.
Параметр | Тип | Описание |
---|---|---|
id | string | уникальный идентификатор услуги голосового сообщения (SMS) |
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
400 | Bad Request | failed to parse token | неправильно указан токен (API-ключ приложения) |
401 | Unauthorized | error getting JWT Token claims | ошибка при парсинге JWT claims (части API-ключа, отвечающие за информацию о пользователе/приложении) |
500 | Internal Server Error | error getting customer status | ошибка подключения к аккаунту пользователя |
403 | Forbidden | error":“Customer is not in correct status” | ошибка возникает, если не удается создать услугу голосового SMS из-за статуса аккаунта пользователя (не активирован/заблокирован) |
404 | Not Found | error getting application | приложение не найдено |
Выходные параметры
Пустой JSON
Примеры
Входные параметры:
{
"id": "14b8d7b3-5468-418f-8592-b1d2127ad36b"
}
Выходные параметры:
{}
Метод MakeVoiceMessage
Примените метод MakeVoiceMessage для запуска автоматизированного обзвона с предзаписанным аудиосообщением или синтезированной в режиме онлайн речью (TTS — text-to-speech)
Точка подключения: Выполните POST запрос с входными параметрами к точке подключения:
POST: https://api.exolve.ru/call/v1/MakeVoiceMessage
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.
ВАЖНО! Можно указать только один из параметров:
service_id
— если хотите проиграть принимающим абонентам предзаписанное аудио и уже создали для него ресурс голосового SMS в Личном кабинете или с помощью API-метода Createtts
— если хотите синтезировать речь по заданным параметрам в режиме онлайн
Параметр | Тип | Описание |
---|---|---|
source | string | номер, с которого осуществится обзвон |
destination | string | номер принимающего абонента |
service_id | string | идентификатор ресурса голосового сообщения (для предзаписанного аудио) |
tts | TTS | параметры синтеза речи для аудиосообщения абоненту |
TTS
Параметр | Тип | Описание |
---|---|---|
text | string | текст синтезируемой речи (от 1 до 1000 символов, кодировка не учитывается) |
voice | Voice | голос для озвучивания текста |
lang | Lang | язык синтезируемой речи |
volume | int32 | нормализация громкости (от -145 до 0, где -145 — наименьшее усиление, 0 — наибольшее усиление громкости; по умолчанию -19) |
speed | float | скорость синтезируемой речи (от 0.1 до 3.0, где 0.1 — самая медленная, 3.0 — самая быстрая; по умолчанию 1.0) |
emotion | Emotion | эмоция для озвучивания текста |
SynthesisSettings
ВАЖНО! Каждый голос поддерживает определённые параметры языка и эмоции. При формировании API-запроса важно, чтобы выбранный голос был доступен с указанным языком и эмоцией
Параметр | Тип | Голос (Voice) | Пол | Эмоция (Emotion) | Язык (Lang) |
---|---|---|---|---|---|
1 | enum | Алёна (по умолчанию) | Ж | 1 — нейтральная (по умолчанию), 2 — добрая | 1 — русский |
2 | enum | Ермил | М | 1 — нейтральная (по умолчанию), 2 — радостная | 1 — русский |
3 | enum | Джейн | Ж | 1 — нейтральная (по умолчанию), 2 — радостная, 3 — раздраженная | 1 — русский |
4 | enum | Омаж | Ж | 1 — нейтральная (по умолчанию), 3 — раздраженная | 1 — русский |
5 | enum | Захар | М | 1 — нейтральная (по умолчанию), 2 — радостная | 1 — русский |
8 | enum | Даша | Ж | 1 — нейтральная (по умолчанию), 2 — радостная, 4 — дружелюбная | 1 — русский |
9 | enum | Юлия | Ж | 1 — нейтральная (по умолчанию), 5 — строгая | 1 — русский |
10 | enum | Лера | Ж | 1 — нейтральная (по умолчанию), 4 — дружелюбная | 1 — русский |
11 | enum | Марина | Ж | 1 — нейтральная (по умолчанию), 4 — дружелюбная, 6 — шёпот | 1 — русский |
12 | enum | Александр | М | 1 — нейтральная (по умолчанию), 2 — радостная | 1 — русский |
13 | enum | Кирилл | М | 1 — нейтральная (по умолчанию), 2 — радостная, 5 — строгая | 1 — русский |
14 | enum | Антон | М | 1 — нейтральная (по умолчанию), 2 — радостная | 1 — русский |
15 | enum | Маша | Ж | 2 — радостная (по умолчанию), 4 — дружелюбная, 5 — строгая | 1 — русский |
Выходные параметры
Параметр | Тип | Описание |
---|---|---|
call_id | string | уникальный идентификатор отправленного голосового сообщения |
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
400 | Bad Request | the client can only call to his own confirmed number | попытка отправки голосового SMS на не подтвержденный номер во время пробного периода аккаунта |
400 | Bad Request | Validation error. Please enter valid parameter values. | не правильно указаны параметры запроса |
401 | Unauthorized | malformed token | не указан / не правильно указан API-ключ приложения |
Примеры
Входные параметры
Звонок с предзаписанным аудиофайлом
{
"source": "74959999999",
"destination": "79999999999",
"service_id": "app24226e5c-ce2b-4aa9-aac8-317f8dd42714"
}
Звонок с синтезированием речи в режиме онлайн
{
"source": "74959999999",
"destination": "79999999999",
"tts": {
"text": "МТС Exolve — конструктор омниканальных диалогов для бизнеса",
"voice": 1,
"lang": 1,
"volume": -19,
"speed": 1.1,
"emotion": 2
}
}
Выходные параметры:
{
"call_id": "cal55094238-bc5f-4b2d-8a95-5a20d7cbb5bc"
}
Метод GetInfo
Примените этот метод для получения статистики об отправленном голосовом сообщении (SMS). Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.
Точка подключения:
POST: https://api.exolve.ru/call/v1/GetInfo
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.
Параметр | Тип | Описание |
---|---|---|
call_id | string | уникальный идентификатор вызова голосового сообщения (call_id из метода MakeVoiceMessage) |
Выходные параметры
Параметр | Тип | |
---|---|---|
call_id | string | уникальный идентификатор вызова голосового сообщения |
created | string | время создания вызова голосового сообщения |
updated | string | время обновления вызова |
started | string | время начала вызова |
ended | string | время окончания вызова |
duration | int32 | продолжительность вызова в секундах |
timeout | int32 | ожидание ответа вызываемого абонента |
status | string Status | статус вызова |
direction | string | направление вызова |
source | string | номер вызывающего абонента |
destination | string | номер вызываемого абонента |
Status
Параметр | Тип | Описание |
---|---|---|
queued | вызов в очереди | |
initiated | вызов инициирован | |
ringing | вызов поступил на номер | |
answered | поступил ответ на вызов | |
play_audio_start | на вызов ответили и началось проигрывание аудиосообщения | |
play_audio_stop | на вызов ответили и проигрывание аудио сообщения окончено | |
talk | разговорная фаза вызова | |
completed | вызов завершён | |
no_answer | вызов завершён без ответа | |
canceled | вызов отменён вызывающим абонентом | |
busy | вызываемый абонент занят | |
rejected | вызов отклонён вызываемым абонентом | |
failed | вызов не может быть совершён из за недостаточности баланса или неверных настроек вызова | |
modified | вызов модифицирован API-функцией |
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
400 | Bad Request | Validation error. Please enter valid parameter values | неправильный параметр в запросе (call_id) |
401 | Unauthorized | malformed token | не указан / не правильно указан API-ключ приложения |
404 | Not Found | Not Found | отсутствует медиа файлы, привязанные к услуге голосового сообщения |
Примеры
Входные параметры:
{
"call_id": "caldf32f642-6313-4dae-94db-98502ad3249c"
}
Выходные параметры:
{
"call_id": "caldf32f642-6313-4dae-94db-98502ad3249c",
"created": "Wed, 29 Mar 2023 10:32:45 +0000",
"updated": "Wed, 29 Mar 2023 10:33:07 +0000",
"started": "Wed, 29 Mar 2023 10:32:58 +0000",
"ended": "Wed, 29 Mar 2023 10:33:07 +0000",
"duration": 9,
"timeout": 60,
"status": "completed",
"direction": "outbound",
"source": "79990557296",
"destination": "79995556789"
}