CLS. Руководство пользователя

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

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

Основные возможности:

• Выбор канала связи
  • голосовые звонки - интеграция с 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": "сообщение о статусе результата" }
GET/cls/calls/list/tasks	Получение задач для списка
list_id - идентификатор списка limit - лимит задач для вывода		{  "error": 0,   "tasks": [] }
GET/cls/calls/queues/status	Получение статуса всех очередей
No parameters		{  "error": 0,   "queues": {     "main_queue_size": 0,     "log_queue_size": 0,     "active_tasks_count": 0,     "total_workers": 3,     "log_workers": 3,     "total_tasks_history": 0   } }
POST /calls/start	Старт списка обзвона | оповещения
id - id списка dataset - набор данных		{   "error": 0,   "message": "сообщение о статусе результата" }
POST /calls/stop	Остановка списка обзвона | оповещения
id - id списка dataset - набор данных		{   "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 }