Callback API
Callback API — программный интерфейс, который позволяет пользователям управлять ресурсами обратных звонков в Личном кабинете и совершать эти звонки.
Callback API Exolve предлагает пользователям следующие методы для управления ресурсами обратных звонков и их совершения:
-
Create - создает ресурс обратного звонка в приложении Личного кабинета;
-
GetList - получает информацию обо всех ресурсах обратных звонков в приложении Личного кабинета;
-
GetInfo - получает информацию о конкретном ресурсе обратного звонка в приложении Личного кабинета;
-
Delete - удаляет ресурс обратного звонка в приложении Личного кабинета;
-
Update - изменяет имя и описание ресурса обратного звонка в приложении Личного кабинета;
-
MakeCallBack - совершает обратный звонок.
Решения, где используется Callback API
Метод Create
Примените этот метод для создания услуги обратного звонка в приложении. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.
Точка подключения:
POST: https://api.exolve.ru/callback/v1/Create
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.
Параметр | Тип | Описание |
---|---|---|
callback_name | string | наименование ресурса обратного звонка |
description | string | описание ресурса обратного звонка |
Выходные параметры
Параметр | Тип | Описание |
---|---|---|
callback_resource_id | string | уникальный идентификатор ресурса обратного звонка |
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
401 | Unauthorized | malformed token | не указан / не правильно указан API-ключ приложения |
403 | Forbidden | customer not active | нет доступа к услуге обратного звонка из-за статуса аккаунта пользователя (не активирован/заблокирован) |
400 | Bad Request | proto: (line 3:20): invalid value for string type: 1 | невалидный запрос |
504 | Gateway Timeout | нет ответа от внутренних систем Exolve |
Примеры
Входные параметры:
{
"callback_name": "Наименование",
"description": "Описание"
}
Выходные параметры:
{
"callback_resource_id": "1657"
}
Метод GetList
Примените этот метод для получения информации обо всех услугах обратного звонка в приложении. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.
Точка подключения:
POST: https://api.exolve.ru/callback/v1/GetList
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Пустой JSON
Выходные параметры
Параметр | Тип | Описание |
---|---|---|
callback_resource_id | string | уникальный идентификатор ресурса обратного звонка |
callback_name | string | наименование ресурса обратного звонка |
description | string | описание ресурса обратного звонка |
created_at | string | дата создания ресурса обратного звонка в формате RFC-3339 / ISO-8601 |
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
401 | Unauthorized | malformed token | не указан / не правильно указан API-ключ приложения |
403 | Forbidden | customer status blocked | нет доступа к услуге обратного звонка из-за статуса аккаунта пользователя (не активирован/заблокирован) |
400 | Bad Request | proto: (line 3:20): invalid value for string type: 1 | невалидный запрос |
504 | Gateway Timeout | нет ответа от внутренних систем Exolve |
Примеры
Входные параметры:
{}
Выходные параметры:
{
"callbacks": [
{
"callback_resource_id": "138825",
"callback_name": "Test",
"description": "Test",
"created_at": "2023-03-10T11:14:07.990035Z"
},
{
"callback_resource_id": "138872",
"callback_name": "Наименование",
"description": "Описание",
"created_at": "2023-03-12T12:20:08.971486Z"
}
]
}
Метод GetInfo
Примените этот метод для получения информации об услуге обратного звонка в приложении. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.
Точка подключения:
POST: https://api.exolve.ru/callback/v1/GetInfo
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.
Параметр | Тип | Описание |
---|---|---|
callback_resource_id | uint64 | уникальный идентификатор ресурса обратного звонка |
Выходные параметры
Параметр | Тип | Описание |
---|---|---|
callback_resource_id | string | уникальный идентификатор ресурса обратного звонка |
callback_name | string | наименование ресурса обратного звонка |
description | string | описание ресурса обратного звонка |
created_at | string | дата создания ресурса обратного звонка в формате RFC-3339 / ISO-8601 |
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
401 | Unauthorized | malformed token | не указан / не правильно указан API-ключ приложения |
403 | Forbidden | customer not active | нет доступа к услуге обратного звонка из-за статуса аккаунта пользователя (не активирован/заблокирован) |
400 | Bad Request | proto: (line 3:20): invalid value for string type: 1 | невалидный запрос |
504 | Gateway Timeout | нет ответа от внутренних систем Exolve |
Примеры
Входные параметры:
{
"callback_resource_id": 138873
}
Выходные параметры:
{
"callback": {
"callback_resource_id": "138873",
"callback_name": "Наименование",
"description": "Описание",
"created_at": "2023-03-12T12:20:41.112301Z"
}
}
Метод Delete
Примените этот метод для удаления услуги обратного звонка в приложении. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.
Точка подключения:
POST: https://api.exolve.ru/callback/v1/Delete
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.
Параметр | Тип | Описание |
---|---|---|
callback_resource_id | uint64 | уникальный идентификатор ресурса обратного звонка |
Выходные параметры
Пустой JSON с 200 OK статусом.
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
401 | Unauthorized | malformed token | не указан / не правильно указан API-ключ приложения |
403 | Forbidden | customer status suspend | нет доступа к услуге обратного звонка из-за статуса аккаунта пользователя (не активирован/заблокирован) |
400 | Bad Request | proto: (line 3:20): invalid value for string type: 1 | невалидный запрос |
504 | Gateway Timeout | нет ответа от внутренних систем Exolve |
Примеры
Входные параметры:
{
"callback_resource_id": 1657
}
Метод Update
Примените этот метод для изменения услуги обратного звонка в приложении. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.
Точка подключения:
POST: https://api.exolve.ru/callback/v1/Update
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.
Параметр | Тип | Описание |
---|---|---|
callback_resource_id | uint64 | уникальный идентификатор ресурса обратного звонка |
callback_name | string | наименование ресурса обратного звонка |
description | string | описание ресурса обратного звонка |
Выходные параметры
Пустой JSON с 200 OK статусом
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
401 | Unauthorized | malformed token | не указан / не правильно указан API-ключ приложения |
403 | Forbidden | customer status blocked | нет доступа к услуге обратного звонка из-за статуса аккаунта пользователя (не активирован/заблокирован) |
400 | Bad Request | error setting callback fields | невалидный запрос |
504 | Gateway Timeout | нет ответа от внутренних систем Exolve |
Примеры
Входные параметры:
{
"callback_resource_id": 1212,
"callback_name": "Новое наименование",
"description": "Новое описание"
}
Выходные параметры:
{}
Метод MakeCallBack
Примените этот метод для совершения обратного звонка: платформа позвонит абонентам (например, оператору и клиенту), затем объединит их для разговора. Обоим абонентам можно перед соединением проиграть аудиосообщение — предварительно записанное или синтезированное в режиме онлайн в рамках этого же звонка.
Точка подключения: Выполните POST-запрос с входными параметрами к точке подключения:
POST: https://api.exolve.ru/call/v1/MakeCallback
Авторизация
Передайте следующие Заголовки HTTP для успешной авторизации.
Имя | Тип | Описание |
---|---|---|
Authorization | string | API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0 , где e***s0 замените на API-ключ вашего приложения |
Входные параметры
Передайте следующие параметры в теле запроса в JSON формате. Параметры, отмеченные жирным шрифтом, являются обязательными.
Параметр | Тип | Описание |
---|---|---|
request_description | string | идентификатор запроса со стороны клиента |
number_code | uint64 | номер для создания обратного звонка |
callback_resource_id | uint64 | уникальный идентификатор ресурса обратного звонка. Чтобы получить идентификатор, создайте ресурс обратного звонка в приложении |
duration | uint32 | максимальная длительность соединенного вызова двух абонентов в секундах: от 300 до 3600 (по умолчанию: 1800) |
line_1 | Line_x | настройки первого плеча |
line_2 | Line_x | настройки второго плеча |
Line_x
Параметр | Тип | Описание |
---|---|---|
destinations | Destination | Список абонентов плеча Х (до 10 на каждом) |
ring_logic | enum | Принцип обзвона. Значение 1 для последовательного обзвона, значение 2 для параллельного. Значение 1 по умолчанию |
display_number | string | отображаемый номер звонящего/принимающего вызов абонента |
audio | Audio | аудиосообщение для абонента плеча Х |
Destination
Параметр | Тип | Описание |
---|---|---|
number | string | номер или SIP-URI абонента |
timeout | uint32 | максимальное время дозвона до абонента от инициации вызова в секундах: от 10 до 600 (по умолчанию: 30) |
Audio
ВАЖНО! Для одного плеча можно указать только один из параметров:
media_resource_id
— проиграть принимающим абонентам предзаписанное аудиоtts
— (Text-to-Speech) — синтезировать речь по заданным параметрам в режиме онлайн
Параметр | Тип | Описание |
---|---|---|
media_resource_id | uint64 | уникальный идентификатор медиаресурса для аудиосообщения абоненту плеча Х |
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 | уникальный идентификатор совершенного обратного звонка |
request_id | string | идентификатор запроса со стороны клиента |
Возможные ошибки
Код | Статус | Пример сообщения | Описание |
---|---|---|---|
401 | Unauthorized | malformed token | не указан / не правильно указан API-ключ приложения |
403 | Forbidden | customer not active | нет доступа к услуге обратного звонка из-за статуса аккаунта пользователя (не активирован/заблокирован) |
400 | Bad Request | invalid MakeCallbackRequest.Line_1: embedded message failed validation | невалидный запрос |
504 | Gateway Timeout | нет ответа от внутренних систем Exolve |
Примеры
Входные параметры:
{
"request_description": "internal_id_148",
"number_code": 74999999999,
"callback_resource_id": 1221,
"line_1": {
"destinations": [
{
"number": "78129999999"
},
{
"number": "74959999999"
}
],
"ring_logic": 1,
"audio": {
"tts": {
"text": "МТС Exolve — конструктор омниканальных диалогов для бизнеса",
"voice": 1,
"lang": 1,
"volume": -19,
"speed": 1.1,
"emotion": 2
}
}
},
"line_2": {
"destinations": [
{
"number": "79599999999"
},
{
"number": "79999999999"
}
],
"ring_logic": 1,
"audio": {
"media_resource_id": 685
}
}
}
Выходные параметры:
{
"call_id": "1890033117915127808",
"request_description": "Идентификатор"
}