Действия

CLS. Руководство пользователя: различия между версиями

Материал из Флора AI

(Новая страница: «===== '''Общее описание''' ===== Сервис предназначен для преобразования текста в речь. Входными данными для сервиса является текст, результатом работы будет аудиофайл. ====='''Термины и определения'''===== Text-to-speech server (TTS) – сервис синтеза речи. Модель (голос) – мод...»)
 
Нет описания правки
 
(не показано 65 промежуточных версий этого же участника)
Строка 1: Строка 1:
===== '''Общее описание''' =====
===== '''Общее описание''' =====
Сервис предназначен для преобразования текста в речь. Входными данными для сервиса является текст, результатом работы будет аудиофайл.
Сервис массового обзвона и уведомлений, поддерживающий множественные каналы связи и гибкую настройку


======  '''Основные возможности:''' ======
* Выбор канала связи
** голосовые звонки - интеграция с '''FreeSWITCH''' для исходящих звонков
** telegram | VK - интеграция с '''SES''' для последующей отправки уведомления в мессенджер
* Управление списками обзвона
** CRUD операции - создание, чтение, изменение, удаление списков
** Импорт/Экспорт - загрузка и выгрузка контактов из CSV
** Автозагрузка - динамическое расширение списков через скрипт
** Планировщик - cron-подобное расписание запуска обзвонов
* Конфигурация и лимиты
** Глобальные настройки - централизованное управление конфигурацией
** Временные интервалы - точное управление временем работы
** Праздники - учет выходных дней при обзвонах
** Лимиты обзвона - контроль нагрузки и таймаутов
* Мониторинг и отчетность
** Реальное время - отслеживание статуса обзвонов
** Логирование - детальные логи всех звонков / уведомлений
** API - полный программный доступ ко всем функциям


====='''Термины и определения'''=====
===== '''Термины и определения''' =====
Text-to-speech server (TTS) – сервис синтеза речи.
CLS (Call List Service) - сервис массового обзвона и уведомлений с поддержкой множественных каналов связи.


Модель (голос) – модель нейронной сети, отвечающая за синтез спектрограммы из текста. От модели зависит, каким голосом будет синтезирован текст.
Swagger UI – интерактивная веб-консоль с кратким описанием методов API и возможностью выполнять запросы к сервису CLS в реальном времени.
 
Вокодер – модель нейронной сети, отвечающая за синтез аудиоданных из спектрограммы.
 
Swagger UI – интерактивная веб-консоль с кратким описанием методов API и возможностью выполнять запросы к сервису TTS в реальном времени


Список обзвона (Call List) - набор контактов с метаданными для выполнения массовой рассылки или обзвона.


ListCaller - основной класс, управляющий выполнением кампании по конкретному списку.


Instance - активный экземпляр ListCaller, выполняющий обзвон.


===== '''Описание методов API''' =====
===== '''Описание методов API''' =====
Запросы осуществляются по протоколу HTTP 1.1 на адрес сервера с доступным сервисом TTS. По умолчанию используется порт 6186/tcp.
Запросы осуществляются по протоколу HTTP 1.1 на адрес сервера с доступным сервисом CLS. По умолчанию используется порт 6188/tcp.


Авторизация запросов не требуется. HTTP-запросы должны содержать заголовок <code>"accept: application/json"</code>
Авторизация запросов не требуется. HTTP-запросы должны содержать заголовок <code>"accept: application/json"</code>


Ответ сервиса представляет собой JSON или текстовый документ в кодировке UTF-8, или двоичный файл.
Содержимое документа зависит от результата выполнения запроса. При наличии ошибки в качестве ответа вернется переменная error=1 и описание в переменной message. Для удобства проверки методов по ссылке http://АДРЕС:6188 будет отображен интерфейс Swagger со всеми методами с возможностью их проверки.
 
Содержимое документа зависит от результата выполнения запроса. При наличии ошибки в качестве ответа вернется переменная error=1 и описание в переменной message. Для удобства проверки методов по ссылке http://АДРЕС:6186 будет отображен интерфейс Swagger со всеми методами с возможностью их проверки.


{| class="wikitable" style="width: 110%"
{| class="wikitable" style="width: 110%"
|+''Описание методов API''
|+''Описание методов API''
! style="color:blue;width: 15%" |'''GET/tts/'''
! colspan="3" |'''<u>Управление обзвонами</u>'''
! colspan="2" style="width: 85%" |<small>Вывод списка моделей (голосов синтеза).</small>
|-
|-
| colspan="2" style="width: 50%" |<small>Входные параметры отсутствуют</small>
! style="color:green;width: 15%" |'''POST /calls/call'''
| style="width: 50%" |<small><code>{ models: [model1,...,modelN] }</code></small>
! colspan="2" style="width: 85%" |<small>Прямой звонок с номера на номер</small>
|-
|-
! style="color:blue;width: 15%" |'''GET/tts/dictionary/export'''
| colspan="2" style="width: 50%" |<small><code>{</code></small>
! colspan="2" style="width: 85%" |<small>Выгрузка пользовательского словаря ударений.</small>
    <small><code>"source": "8000",</code></small>
 
    <small><code>"destination": "6000",</code></small>
 
    <small><code>"limits": {</code></small>
 
        <small><code>"no_answer_timeout": 10,</code></small>
 
        <small><code>"dial_tries": 1,</code></small>
 
        <small><code>"max_channels": 2,</code></small>
 
        <small><code>"redial_timeout": 600,</code></small>
 
        <small><code>"watchdog": 240</code></small>
 
    <small><code>},</code></small>
 
    <small><code>"metadata": {}</code></small>
 
<small><code>}</code></small>
| style="width: 50%" |<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>
 
    <small><code>  "message": "сообщение о статусе результата"</code></small>
 
<small><code>}</code></small>
|-
|-
| colspan="2" style="width: 50%" |<small>Входные параметры отсутствуют</small>
! style="color:green;width: 15%" |'''POST /calls/start'''
| style="width: 50%" |<small>простой текст - строки с словом и его интерперетацией с ударением</small>
! colspan="2" style="width: 85%" |<nowiki>Старт списка обзвона | оповещения</nowiki>
|-
|-
! style="color:blue;width: 15%" |'''GET/tts/dictionary/get'''
| colspan="2" style="width: 50%" |
! colspan="2" style="width: 85%" |<small>Выгрузка пользовательского словаря ударений в виде json.</small>
* <small>'''id''' - id списка</small>
|-
| style="width: 50%" |<small><code>{</code></small>
| colspan="2" style="width: 50%" |<small>Входные параметры отсутствуют</small>
    <small><code>  "error": 0,</code></small>
| style="width: 50%" |<small><code>[</code></small> <small><code>[   "слово",   "замена слова с удар+ением"],</code></small>


<small><code>[   "слово2",   "замена слова2 с удар+ением"],</code></small>
    <small><code>  "message": "сообщение о статусе результата"</code></small>


<small><code>...</code></small>
<small><code>}</code></small>
 
<small><code>]</code></small>
|-
|-
! style="color:green;width: 15%" |'''POST/tts/dictionary/import'''
! style="color:green;width: 15%" |'''POST /calls/stop'''
! colspan="2" style="width: 85%" |<small>Загрузка пользовательского словаря ударений. Текущий словарь будет переписан.</small>
! colspan="2" style="width: 85%" |<nowiki>Остановка списка обзвона | оповещения</nowiki>
|-
|-
| colspan="2" style="width: 50%" |
| colspan="2" style="width: 50%" |
* <small>'''csv''' — файл строк со словом и его интерпретацией с ударением.</small>
* <small>'''id''' - id списка</small>
| style="width: 50%" |<small><code>{</code></small>
| style="width: 50%" |<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>
    <small><code>  "message": "сообщение о статусе результата"</code></small>
<small><code>}</code></small>
|-
! colspan="3" |'''<u><nowiki>Управление списками обзвона | оповещения</nowiki></u>'''
|-
! style="color:green;width: 15%" |'''POST /lists/add'''
! colspan="2" style="width: 85%" |<nowiki>Добавление нового списка для обзвона | оповещения</nowiki>
|-
| colspan="2" style="width: 50%" |<small><code>{</code></small>
<small><code>  "name": "Test Call List",</code> - имя списка</small>
<small><code>  "source": "8000",</code> - источник вызова | оповещения</small>
<small><code>  "limits": {</code> - лимиты для вызова (опционально)</small>
<small><code>    "no_answer_timeout": 10,</code></small>
<small><code>    "dial_tries": 1,</code></small>
<small><code>    "max_channels": 2,</code></small>
<small><code>    "redial_timeout": 600,</code></small>
<small><code>    "watchdog": 240</code></small>
<small><code>  },</code></small>
<small><code>  "dialed": 0,</code></small>
<small><code>  "timeintervals": [</code></small>
<small><code>    "default"</code> - id временного интервала</small>
<small><code>  ],</code></small>
<small><code>  "channel": "voice",</code> - используемый канал</small>
<small><code>  "channel_parameters": {</code> - используется для каналов telegram и vk</small>
<small><code>    "robot_id": "",</code></small>
<small><code>    "endpoint": ""</code></small>
<small><code>  },</code></small>
<small><code>  "script_before_dial": "",</code> - скрипт для выполнения перед каждым вызовом | оповещением</small>
<small><code>  "script": "",</code> - скрипт дозагрузки элементов для обзвона</small>
<small><code>  "autoload": false,</code> - автоматическая дозагрузка элементов для обзвона при старте списка</small>
<small><code>  "scheduler": [</code> - планировщик выполнения обзвона | оповещения</small>
<small><code>    "35 14 * * *"</code> - cron-расписание запуска обзвона</small>
<small><code>  ],</code></small>
<small><code>  "items": [</code></small>


<small><code>  "error": 0,</code></small>
<small><code>    {</code></small>


<small><code>  "message": "сообщение о статусе результата"</code></small>
<small><code>      "destinations": [</code> - телефоны | user_id для каналов отличных от voice</small>
 
<small><code>        "6000"</code></small>
 
<small><code>      ],</code></small>
 
<small><code>      "metadata": {}</code> - дополнительная произвольная информация</small>
 
<small><code>    }</code></small>
 
<small><code>  ]</code></small>


<small><code>}</code></small>
<small><code>}</code></small>
| style="width: 50%" |<code><small>{
  <code>"error": 0,</small></code>
  <code><small>"message": "success",</small></code>
  <code><small>"id": "123e4567-e89b-12d3-a456-426614174000"</small></code>
<code><small>}</small></code>
|-
|-
! style="color:green;width: 15%" |'''POST/tts/dictionary/put'''
! style="color:red;width: 15%" |'''DELETE /lists/delete/{id}'''
! colspan="2" style="width: 85%" |<small>Загрузка пользовательского словаря ударений в виде json. Текущий словарь будет переписан.</small>
! colspan="2" style="width: 85%" |<nowiki>Удаление существующего списка для обзвона | оповещения</nowiki>
|-
|-
| colspan="2" style="width: 50%" |
| colspan="2" style="width: 50%" |
* <small>'''json''' — строка следующего вида:</small>
* <small>'''id''' - id списка</small>
|<code><small>{</small></code>
    <small><code>  "error": 0,</code></small>


<small><code>[</code></small>
    <small><code>  "message": "сообщение о статусе результата"</code></small>


<small><code>[   "слово",   "замена слова с удар+ением" ],</code></small>
<code><small>}</small></code>
|-
! style="color:blue;width: 15%" |'''GET /lists/export/{id}'''
! colspan="2" style="width: 85%" |<nowiki>Экспорт списка для обзвона | оповещения в CSV файл</nowiki>
|-
| colspan="2" style="width: 50%" |
* <small>'''id''' - id списка</small>
|<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>
 
    <small><code>  "message": "сообщение о статусе результата"</code></small>
 
<small><code>}</code></small>
|-
! style="color:green;width: 15%" |'''POST /lists/import/{id}'''
! colspan="2" style="width: 85%" |<nowiki>Экспорт списка для обзвона | оповещения из CSV файла</nowiki>
|-
| colspan="2" |
* <small>'''csv''' - csv файл с элементами списка</small>


<small><code>[ "слово2",   "замена слова2 с удар+ением" ],</code></small>
* <small>'''id''' - id списка</small>
|<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>


<small><code>...</code></small>
    <small><code>  "message": "сообщение о статусе результата"</code></small>


<small><code>]</code></small>
<small><code>}</code></small>
|-
! style="color:blue;width: 15%" |'''GET /lists/list'''
! colspan="2" style="width: 85%" |<nowiki>Получения всех списков для обзвона | оповещения из БД</nowiki>
|-
| colspan="2" style="width: 50%" |<small>No parameters</small>
| style="width: 50%" |<code><small>{</small></code>
    <code><small>"error": 0,</small></code>
    <code><small>"lists": []</small></code>
<code><small>}</small></code>
|-
! style="color:blue;width: 15%" |'''GET /lists/{id}'''
! colspan="2" |<nowiki>Получение конкретного списка для обзвона | оповещения из БД</nowiki>
|-
| colspan="2" |
* <small>'''id''' - id списка</small>
|<code><small>{</small></code>
    <code><small>"error": 0,</small></code>
    <code><small>"list": {}</small></code>
<code><small>}</small></code>
|-
! style="color:green;width: 15%" |'''POST /lists/load/{id}'''
! colspan="2" style="width: 85%" |<nowiki>Дозагрузка в существующую инстанцию списка обзвона | оповещения элементов из скрипта</nowiki>
|-
| colspan="2" style="width: 50%" |
* <small>id - id списка</small>
| style="width: 50%" |<small><code>{</code></small>
| style="width: 50%" |<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>


<small><code>  "error": 0,</code></small>
    <small><code>  "message": "сообщение о статусе результата"</code></small>
 
<small><code>  "message": "сообщение о статусе результата"</code></small>


<small><code>}</code></small>
<small><code>}</code></small>
|-
|-
! style="color:green;width: 15%" |'''POST/tts/normalize'''
! style="color:orange;width: 15%" |'''PUT /lists/modify/{id}'''
! colspan="2" style="width: 85%" |<small>Нормализация текста — перевод цифр в слова и расстановка ударений (ударения только в нормализованной части фразы), например «в понедельник 10.10.2025» -> «в понедельник дес+ятого октябр+я две т+ысячи дв+адцать п+ятого г+ода».</small>
! colspan="2" style="width: 85%" |<nowiki>Изменение существующего списка для обзвона | оповещения</nowiki>
|-
|-
| colspan="2" style="width: 50%" |
| colspan="2" style="width: 50%" |
* <small>'''text''' — фраза для нормализации.</small>
* <small>'''payload''' как в '''POST /lists/add'''</small>
* <small>'''id''' - id списка</small>
| style="width: 50%" |<small><code>{</code></small>
| style="width: 50%" |<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>


<small><code>  "error": 0,</code></small>
    <small><code>  "message": "сообщение о статусе результата"</code></small>


<small><code>  "message": "success",</code></small>
<small><code>}</code></small>
|-
! style="color:blue;width: 15%" |'''GET /lists/status/{id}'''
! colspan="2" |<nowiki>Получение статуса существующего списка для обзвона | оповещения</nowiki>
|-
| colspan="2" |
* <small>id - id списка</small>
|<small><code>{</code></small>
    <small><code>"error": 0,{</code></small>
    <small><code>"status": {</code></small>
        <small><code>"total_items": 0,</code></small>
        <small><code>"processed_items": 0,</code></small>
        <small><code>"completed": false,{</code></small>
        <small><code>"reason": "",</code></small>
        <small><code>"running": false</code></small>
    <small><code>}</code></small>
<small><code>}</small></code>
|-
! colspan="3" |'''<u><nowiki>Управление инстанциями обзвона | оповещения</nowiki></u>'''
|-
! style="color:green;width: 15%" |'''POST /instances/add/{list_id}'''
! colspan="2" |<nowiki>Создание инстанции обзвона | оповещения на основе списка, без запуска обзвона | оповещения</nowiki>
|-
| colspan="2" |
* <small>'''id''' - id списка</small>
|<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>


<small><code>  "text": "нормализованный текст"</code></small>
    <small><code>  "message": "сообщение о статусе результата"</code></small>


<small><code>}</code></small>
<small><code>}</code></small>
|-
|-
! style="color:green;width: 15%" |'''POST/tts/revoice/{revoicer}'''
! style="color:blue;width: 15%" |'''GET /instances/get/{instance_id}'''
! colspan="2" style="width: 85%" |<small>Модификация или искажение голоса</small>
! colspan="2" |Получить детальную информацию о конкретной инстанции
|-
| colspan="2" |
* <small>'''id''' - id списка | инстанции (одно и тоже)</small>
|<code><small>{</small></code>
    <code><small>"id": "86c08271-8415-4ba5-bcf1-e1115a602bd8",</small></code>
    <code><small>"name": "Test Call List",</small></code>
    <code><small>"source": "8000",</small></code>
    <code><small>"limits": {</small></code>
        <code><small>"no_answer_timeout": 5,</small></code>
        <code><small>"dial_tries": 1,</small></code>
        <code><small>"max_channels": 2,</small></code>
        <code><small>"redial_timeout": 200,</small></code>
        <code><small>"watchdog": 60</small></code>
    <code><small>},</small></code>
    <code><small>"timeintervals": ["default"],</small></code>
    <code><small>"holidays": ["2025-09-14"],</small></code>
    <code><small>"channel": "voice",</small></code>
    <code><small>"running": true,</small></code>
    <code><small>"progress": {</small></code>
        <code><small>"total_items": 1,</small></code>
        <code><small>"processed_items": 1,</small></code>
        <code><small>"completed": false,</small></code>
        <code><small>"reason": ""</small></code>
    <code><small>},</small></code>
    <code><small>"job_info": {</small></code>
        <code><small>"has_job": true,</small></code>
        <code><small>"job_id": "86c08271-8415-4ba5-bcf1-e1115a602bd8",</small></code>
        <code><small>"next_run": "2025-12-24 20:00:00+03:00"</small></code>
    <code><small>},</small></code>
    <code><small>"created": "2025-08-18T14:57:17.762777",</small></code>
    <code><small>"items": [</small></code>
        <code><small>{</small></code>
            <code><small>"destinations": ["6000"],</small></code>
            <code><small>"metadata": {}</small></code>
        <code><small>}</small></code>
    <code><small>]</small></code>
<code><small>}</small></code>
|-
! style="color:blue;width: 15%" |'''GET /instances/list'''
! colspan="2" |Получение списка инстанций
|-
| colspan="2" |<small>No parameters</small>
|<code><small>{</small></code>
    <code><small>"total": 0,</small></code>
    <code><small>"instances": []</small></code>
<code><small>}</small></code>
|-
! style="color:red;width: 15%" |'''DELETE /instances/remove/{instance_id}'''
! colspan="2" |<nowiki>Удаление инстанции обзвона | оповещения</nowiki>
|-
| colspan="2" |
* <small>'''id'''<nowiki> - id списка | инстанции (одно и тоже)</nowiki></small>
|<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>
 
    <small><code>  "message": "сообщение о статусе результата"</code></small>
 
<small><code>}</code></small>
|-
|-
| colspan="2" style="width: 50%" |
! colspan="3" |'''<u>Управление временными интервалами</u>'''
* <small>'''wav''' — аудиофайл для обработки.</small>
|-
* <small>'''revoicer''' — модель модификации голоса.</small>
! style="color:green;width: 15%" |'''POST /timeintervals/add'''
| style="width: 50%" |<small>wav файл с модифицированным (искаженным) голосом.</small>
! colspan="2" |Создание временного интервала
|-
| colspan="2" |
<small><code>{</code></small>
 
    <small><code>"id": "02f2d1ce-bb0b-4856-904b-2db13250bb90",</code></small>
 
    <small><code>"name": "Новый интервал 2",</code></small>
 
    <small><code>"days": "all",</code></small>
 
    <small><code>"weekdays": [1],</code></small>
 
    <small><code>"months": [1],</code></small>
 
    <small><code>"dates": [1],</code></small>
 
    <small><code>"intervals": [[0,1440],]</code></small>
 
<small><code>}</code></small>
|<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>
 
    <small><code>  "message": "сообщение о статусе результата"</code></small>
 
<small><code>}</code></small>
|-
! style="color:red;width: 15%" |'''DELETE /timeintervals/delete/{id}'''
! colspan="2" |Удаление существующего интервала времени
|-
| colspan="2" |
* <small>'''id''' - id интервала времени</small>
|<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>
 
    <small><code>  "message": "сообщение о статусе результата"</code></small>
 
<small><code>}</code></small>
|-
|-
! style="color:blue;width: 15%" |'''GET/tts/revoicers'''
! style="color:blue;width: 15%" |'''GET /timeintervals/get/{id}'''
! colspan="2" style="width: 85%" |<small>Перечень моделей модификации или искажения голоса. Модели поставляются только в составе дистрибутива. Модель distortion — искажение голоса, делает голос неузнаваемым и речь неразборчивой.</small>
! colspan="2" |Получение конкретного временного интервала
|-
|-
| colspan="2" style="width: 50%" |<small>Входные параметры отсутствуют</small>
| colspan="2" |
| style="width: 50%" |<small>[  "distortion" ]</small>
* <small>'''id''' - id интервала времени</small>
|
<small><code>{</code></small>
    <small><code>"error": 0,</code></small>
 
    <small><code>"timeinterval": {</code></small>
 
        <small><code>"id": "default",</code></small>
 
        <small><code>"name": "default",</code></small>
 
        <small><code>"days": "all",</code></small>
 
        <small><code>"weekdays": [</code></small>
 
            <small><code>1</code></small>
 
        <small><code>],</code></small>
 
        <small><code>"months": [</code></small>
 
            <small><code>1</code></small>
 
        <small><code>],</code></small>
 
        <small><code>"dates": [</code></small>
 
            <small><code>1</code></small>
 
        <small><code>],</code></small>
 
        <small><code>"intervals": [</code></small>
 
            <small><code>[0, 1440]</code></small>
 
        <small><code>]</code></small>
 
    <small><code>}</code></small>
 
<small><code>}</code></small>
|-
|-
! style="color:blue;width: 15%" |'''GET/tts/split'''
! style="color:blue;width: 15%" |'''GET /timeintervals/list'''
! colspan="2" style="width: 85%" |<small>Разбивка текста на фразы. Текст из нескольких предложений разбивает на отдельные фразы. Фразы отдаёт списком.</small>
! colspan="2" |Получение списка временных интервалов
|-
|-
| colspan="2" style="width: 50%" |
| colspan="2" |<small>No parameters</small>
* <small>'''text''' - текст для обработки</small>
|
| style="width: 50%" |<small>{  "error": 0,</small>
<small><code>{</code></small>
 
    <small><code>"error": 0,</code></small>


<small>  "message": "success",</small>
    <small><code>"timeintervals": []</code></small>


<small>  "phrases": [ "фраза 1", "фраза 2", ....  "фраза N"  ] }</small>
<small><code>}</code></small>
|-
|-
! style="color:green;width: 15%" |'''POST/tts/synthesize/{id}'''
! style="color:orange;width: 15%" |'''PUT /timeintervals/modify/{id}'''
! colspan="2" style="width: 85%" |<small>Синтез звукового файла из текста для фраз большого размера — тип запроса «POST» позволяет отправку больших текстов.</small><small><small>'''ВНИМАНИЕ''': аналогичный метод GET теперь отсутствует.</small>
! colspan="2" |Изменение существующего временного интервала
|-
| colspan="2" |
*<small>'''payload''' как в '''POST /timeintervals/add'''</small>
* <small>'''id''' - id списка</small>
|<small><code>{</code></small>
    <small><code>  "error": 0,</code></small>
 
    <small><code>  "message": "сообщение о статусе результата"</code></small>
 
<small><code>}</code></small>
|-
|-
| colspan="2" style="width: 50%" |
! colspan="3" |'''<u>Управление конфигурациями</u>'''
* <small>'''ID''' — имя модели</small>
* <small>'''text''' — текст синтезируемой фразы</small>
* <small>'''rate''' — скорость речи</small>
* <small>'''pitch''' — высота (тон)</small>
* <small>'''volume''' — громкость</small>
* <small>'''frequency''' — частота дискретизации (по умолчанию 22050 Гц)</small>
* <small>'''format''' - формат файла результата (wav, opus, ogg, mp3)</small>
* <small>'''link''' - если 1, то вернуть только ссылку на файл</small>
| style="width: 50%" |<small>файл с синтезированой фразой</small>
|-
|-
! style="color:blue;width: 15%" |'''GET/license/check'''
! style="color:blue;width: 15%" |'''GET /configs/get/{id}'''
! colspan="2" |<small>Проверка лицензии</small>
! colspan="2" |Получение конкретной конфигурации
|-
|-
| colspan="2" |<small>Входные параметры отсутствуют</small>
| colspan="2" |
|<small>Пример '''неограниченной''' лицензии:
* <small>'''id''' - id конфигурации</small>
|
<small><code>{</code></small>
 
    <small><code>"error": 0,</code></small>


</small><code><small>{</small></code>
    <small><code>"message": "success",</code></small>
 
    <small><code>"data": {</code></small>
 
        <small><code>"id": "limits",</code></small>
 
        <small><code>"params": {</code></small>
 
            <small><code>"watchdog": 60,</code></small>
 
            <small><code>"no_answer_timeout": 10,</code></small>
 
            <small><code>"dial_tries": 1,</code></small>
 
            <small><code>"max_channels": 2,</code></small>
 
            <small><code>"redial_timeout": 600</code></small>
 
        <small><code>}</code></small>
 
    <small><code>}</code></small>
 
<small><code>}</code></small>
|-
! style="color:blue;width: 15%" |'''GET /configs/list'''
! colspan="2" |Получения списка доступных конфигураций
|-
| colspan="2" |<small>No parameters</small>
|
<code><small>{</small></code>


     <code><small>"error": 0,</small></code>
     <code><small>"error": 0,</small></code>


     <code><small>"uuid": "362e51300b1029f9b45fb8d58b2a91bf",</small></code>  
     <code><small>"message": "success",</small></code>


     <code><small>"remaining_licenses": "infinity",</small></code>
     <code><small>"data": []</small></code>


     <code><small>"threshold": 0</small></code>
<code><small>}</small></code>
|-
! style="color:orange;width: 15%" |'''PUT /configs/modify/{id}'''
! colspan="2" |Изменение существующей конфигурации
|-
| colspan="2" |
<small><code>{</code></small>
 
     <small><code>  "id": "string",</code></small>
 
    <small><code>  "params": {}</code></small>
 
<small><code>}</code></small>
|
<small><code>{</code></small>
 
    <small><code>  "error": 0,</code></small>


<code><small>}</small></code>
    <small><code>  "message": "сообщение о статусе результата"</code></small>
 
<small><code>}</code></small>
|-
! colspan="3" |'''<u>Логирование</u>'''
|-
! style="color:blue;width: 15%" |'''GET /logs/logs'''
! colspan="2" |Получение логов с указанной даты
|-
| colspan="2" |
* <small>'''date''' - стартовая дата (формат: 2025-01-01)</small>
* '''<small>id -</small>''' <small>id списка для фильтрации (опционально)</small>
|
<small><code>{</code></small>
 
    <small><code>"error": 0,</code></small>
 
    <small><code>"message": "success",</code></small>
 
    <small><code>"logs": [</code></small>
 
        <small><code>[</code></small>
 
            <small><code>{</code></small>
 
                <small><code>"uuid": "uuid",</code></small>
 
                <small><code>"channel": "voice",</code></small>
 
                <small><code>"source": "8000",</code></small>
 
                <small><code>"destination": "8000",</code></small>
 
                <small><code>"message": "Call to 8000 ended",</code></small>
 
                <small><code>"duration": "44",</code></small>
 
                <small><code>"status": "CALL_ENDED",</code></small>
 
                <small><code>"hangup_cause": "NORMAL_TEMPORARY_FAILURE",</code></small>
 
                <small><code>"sip_hangup_init": "<nowiki>sip:200</nowiki>",</code></small>
 
                <small><code>"metadata": null</code></small>
 
            <small><code>}</code></small>


<small>Пример '''ограниченной''' лицензии:
        <small><code>]</code></small>


</small><code><small>{</small></code>
    <small><code>]</code></small>


    <code><small>"error": 0,</small></code>
<small><code>}</code></small>
|-
! colspan="3" |'''<u>Лицензия</u>'''
|-
! style="color:blue;width: 15%" |'''GET /license/check'''
! colspan="2" |Получение состояния лицензии
|-
| colspan="2" |<small>No parameters</small>
|
<small><code>{</code></small>
    <small><code>"error": 0,</code></small>


     <code><small>"uuid": "362e51300b1029f9b45fb8d58b2a91bf",</small></code>  
     <small><code>"uuid": "uuid",</code></small>


     <code><small>"remaining_licenses": 100,</small></code>
     <small><code>"remaining_licenses": "infinity",</code></small>


     <code><small>"threshold": 100</small></code>
     <small><code>"threshold": 0</code></small>


<code><small>}</small></code>
<small><code>}</code></small>
|}

Текущая версия от 14:41, 25 августа 2025

Общее описание

Сервис массового обзвона и уведомлений, поддерживающий множественные каналы связи и гибкую настройку

Основные возможности:
  • Выбор канала связи
    • голосовые звонки - интеграция с FreeSWITCH для исходящих звонков
    • telegram | VK - интеграция с SES для последующей отправки уведомления в мессенджер
  • Управление списками обзвона
    • CRUD операции - создание, чтение, изменение, удаление списков
    • Импорт/Экспорт - загрузка и выгрузка контактов из CSV
    • Автозагрузка - динамическое расширение списков через скрипт
    • Планировщик - cron-подобное расписание запуска обзвонов
  • Конфигурация и лимиты
    • Глобальные настройки - централизованное управление конфигурацией
    • Временные интервалы - точное управление временем работы
    • Праздники - учет выходных дней при обзвонах
    • Лимиты обзвона - контроль нагрузки и таймаутов
  • Мониторинг и отчетность
    • Реальное время - отслеживание статуса обзвонов
    • Логирование - детальные логи всех звонков / уведомлений
    • API - полный программный доступ ко всем функциям
Термины и определения

CLS (Call List Service) - сервис массового обзвона и уведомлений с поддержкой множественных каналов связи.

Swagger UI – интерактивная веб-консоль с кратким описанием методов API и возможностью выполнять запросы к сервису CLS в реальном времени.

Список обзвона (Call List) - набор контактов с метаданными для выполнения массовой рассылки или обзвона.

ListCaller - основной класс, управляющий выполнением кампании по конкретному списку.

Instance - активный экземпляр ListCaller, выполняющий обзвон.

Описание методов API

Запросы осуществляются по протоколу HTTP 1.1 на адрес сервера с доступным сервисом CLS. По умолчанию используется порт 6188/tcp.

Авторизация запросов не требуется. HTTP-запросы должны содержать заголовок "accept: application/json"

Содержимое документа зависит от результата выполнения запроса. При наличии ошибки в качестве ответа вернется переменная error=1 и описание в переменной message. Для удобства проверки методов по ссылке http://АДРЕС:6188 будет отображен интерфейс Swagger со всеми методами с возможностью их проверки.

Описание методов API
Управление обзвонами
POST /calls/call Прямой звонок с номера на номер
{ 
   "source": "8000",

   "destination": "6000",

   "limits": {

       "no_answer_timeout": 10,

       "dial_tries": 1,

       "max_channels": 2,

       "redial_timeout": 600,

       "watchdog": 240

   },

   "metadata": {}

}

{ 
     "error": 0,

     "message": "сообщение о статусе результата"

}

POST /calls/start Старт списка обзвона | оповещения
  • id - id списка
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

POST /calls/stop Остановка списка обзвона | оповещения
  • id - id списка
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

Управление списками обзвона | оповещения
POST /lists/add Добавление нового списка для обзвона | оповещения
{

  "name": "Test Call List", - имя списка

  "source": "8000", - источник вызова | оповещения

  "limits": { - лимиты для вызова (опционально)

    "no_answer_timeout": 10,

    "dial_tries": 1,

    "max_channels": 2,

    "redial_timeout": 600,

    "watchdog": 240

  },

  "dialed": 0,

  "timeintervals": [

    "default" - id временного интервала

  ],

  "channel": "voice", - используемый канал

  "channel_parameters": { - используется для каналов telegram и vk

    "robot_id": "",

    "endpoint": ""

  },

  "script_before_dial": "", - скрипт для выполнения перед каждым вызовом | оповещением

  "script": "", - скрипт дозагрузки элементов для обзвона

  "autoload": false, - автоматическая дозагрузка элементов для обзвона при старте списка

  "scheduler": [ - планировщик выполнения обзвона | оповещения

    "35 14 * * *" - cron-расписание запуска обзвона

  ],

  "items": [

    {

      "destinations": [ - телефоны | user_id для каналов отличных от voice

        "6000"

      ],

      "metadata": {} - дополнительная произвольная информация

    }

  ]

}

{ 
 "error": 0,

 "message": "success",

 "id": "123e4567-e89b-12d3-a456-426614174000"

}

DELETE /lists/delete/{id} Удаление существующего списка для обзвона | оповещения
  • id - id списка
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

GET /lists/export/{id} Экспорт списка для обзвона | оповещения в CSV файл
  • id - id списка
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

POST /lists/import/{id} Экспорт списка для обзвона | оповещения из CSV файла
  • csv - csv файл с элементами списка
  • id - id списка
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

GET /lists/list Получения всех списков для обзвона | оповещения из БД
No parameters { 
   "error": 0,
   "lists": []

}

GET /lists/{id} Получение конкретного списка для обзвона | оповещения из БД
  • id - id списка
 { 
   "error": 0,
   "list": {}

}

POST /lists/load/{id} Дозагрузка в существующую инстанцию списка обзвона | оповещения элементов из скрипта
  • id - id списка
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

PUT /lists/modify/{id} Изменение существующего списка для обзвона | оповещения
  • payload как в POST /lists/add
  • id - id списка
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

GET /lists/status/{id} Получение статуса существующего списка для обзвона | оповещения
  • id - id списка
 { 
   "error": 0,{
   "status": {
       "total_items": 0,
       "processed_items": 0,
       "completed": false,{
       "reason": "",
       "running": false
   }

}

Управление инстанциями обзвона | оповещения
POST /instances/add/{list_id} Создание инстанции обзвона | оповещения на основе списка, без запуска обзвона | оповещения
  • id - id списка
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

GET /instances/get/{instance_id} Получить детальную информацию о конкретной инстанции
  • id - id списка | инстанции (одно и тоже)
 { 
   "id": "86c08271-8415-4ba5-bcf1-e1115a602bd8",
   "name": "Test Call List",
   "source": "8000",
   "limits": {
       "no_answer_timeout": 5,
       "dial_tries": 1,
       "max_channels": 2,
       "redial_timeout": 200,
       "watchdog": 60
   },
   "timeintervals": ["default"],
   "holidays": ["2025-09-14"],
   "channel": "voice",
   "running": true,
   "progress": {
       "total_items": 1,
       "processed_items": 1,
       "completed": false,
       "reason": ""
   },
   "job_info": {
       "has_job": true,
       "job_id": "86c08271-8415-4ba5-bcf1-e1115a602bd8",
       "next_run": "2025-12-24 20:00:00+03:00"
   },
   "created": "2025-08-18T14:57:17.762777",
   "items": [
       {
           "destinations": ["6000"],
           "metadata": {}
       }
   ]

}

GET /instances/list Получение списка инстанций
No parameters { 
   "total": 0,
   "instances": []

}

DELETE /instances/remove/{instance_id} Удаление инстанции обзвона | оповещения
  • id - id списка | инстанции (одно и тоже)
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

Управление временными интервалами
POST /timeintervals/add Создание временного интервала

{ 

   "id": "02f2d1ce-bb0b-4856-904b-2db13250bb90",

   "name": "Новый интервал 2",

   "days": "all",

   "weekdays": [1],

   "months": [1],

   "dates": [1],

   "intervals": [[0,1440],]

}

{ 
     "error": 0,

     "message": "сообщение о статусе результата"

}

DELETE /timeintervals/delete/{id} Удаление существующего интервала времени
  • id - id интервала времени
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

GET /timeintervals/get/{id} Получение конкретного временного интервала
  • id - id интервала времени

{ 

   "error": 0,

   "timeinterval": {

       "id": "default",

       "name": "default",

       "days": "all",

       "weekdays": [

           1

       ],

       "months": [

           1

       ],

       "dates": [

           1

       ],

       "intervals": [

           [0, 1440]

       ]

   }

}

GET /timeintervals/list Получение списка временных интервалов
No parameters

{ 

   "error": 0,

   "timeintervals": []

}

PUT /timeintervals/modify/{id} Изменение существующего временного интервала
  • payload как в POST /timeintervals/add
  • id - id списка
 { 
     "error": 0,

     "message": "сообщение о статусе результата"

}

Управление конфигурациями
GET /configs/get/{id} Получение конкретной конфигурации
  • id - id конфигурации

{ 

   "error": 0,

   "message": "success",

   "data": {

       "id": "limits",

       "params": {

           "watchdog": 60,

           "no_answer_timeout": 10,

           "dial_tries": 1,

           "max_channels": 2,

           "redial_timeout": 600

       }

   }

}

GET /configs/list Получения списка доступных конфигураций
No parameters

{ 

   "error": 0,

   "message": "success",

   "data": []

}

PUT /configs/modify/{id} Изменение существующей конфигурации

{ 

     "id": "string",

     "params": {}

}

{ 

     "error": 0,

     "message": "сообщение о статусе результата"

}

Логирование
GET /logs/logs Получение логов с указанной даты
  • date - стартовая дата (формат: 2025-01-01)
  • id - id списка для фильтрации (опционально)

{ 

   "error": 0,

   "message": "success",

   "logs": [

       [

           {

               "uuid": "uuid",

               "channel": "voice",

               "source": "8000",

               "destination": "8000",

               "message": "Call to 8000 ended",

               "duration": "44",

               "status": "CALL_ENDED",

               "hangup_cause": "NORMAL_TEMPORARY_FAILURE",

               "sip_hangup_init": "sip:200",

               "metadata": null

           }

       ]

   ]

}

Лицензия
GET /license/check Получение состояния лицензии
No parameters

{ 

   "error": 0,

   "uuid": "uuid",

   "remaining_licenses": "infinity",

   "threshold": 0

}

Источник — https://wiki.connect2ai.net/index.php?title=CLS._Руководство_пользователя&oldid=3036