Просмотр кода страницы 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-запросы должны содержать заголовок <code>"accept: application/json"</code>

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

{| class="wikitable" style="width: 110%"
|+''Описание методов API''
! colspan="3" |Управление обзвонами
|-
! style="color:green;width: 15%" |'''POST /calls/call'''
! colspan="2" style="width: 85%" |<small>Прямой звонок с номера на номер</small>
|-
| colspan="2" style="width: 50%" |<small><code>{</code></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>
|-
! style="color:green;width: 15%" |'''POST /calls/start'''
! colspan="2" style="width: 85%" |<nowiki>Старт списка обзвона | оповещения</nowiki>
|-
| colspan="2" style="width: 50%" |
* <small>'''id''' - id списка</small>
| style="width: 50%" |<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 /calls/stop'''
! colspan="2" style="width: 85%" |<nowiki>Остановка списка обзвона | оповещения</nowiki>
|-
| colspan="2" style="width: 50%" |
* <small>'''id''' - id списка</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" |<nowiki>Управление списками обзвона | оповещения</nowiki>
|-
! 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>    {</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>
| 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:red;width: 15%" |'''DELETE /lists/delete/{id}'''
! colspan="2" style="width: 85%" |<nowiki>Удаление существующего списка для обзвона | оповещения</nowiki>
|-
| colspan="2" style="width: 50%" |
* <small>'''id''' - id списка</small>
|<code><small>{</small></code>
    <small><code>  "error": 0,</code></small>

    <small><code>  "message": "сообщение о статусе результата"</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>'''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 /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: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>
    <small><code>  "error": 0,</code></small>

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

<small><code>}</code></small>
|-
! style="color:orange;width: 15%" |'''PUT /lists/modify/{id}'''
! colspan="2" style="width: 85%" |<nowiki>Изменение существующего списка для обзвона | оповещения</nowiki>
|-
| colspan="2" style="width: 50%" |
* <small>'''payload''' как в '''POST /lists/add'''</small>
* <small>'''id''' - id списка</small>
| style="width: 50%" |<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 /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" |<nowiki>Управление инстанциями обзвона | оповещения</nowiki>
|-
! 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>  "message": "сообщение о статусе результата"</code></small>

<small><code>}</code></small>
|-
! style="color:blue;width: 15%" |'''GET /instances/get/{instance_id}'''
! colspan="2" |Получить детальную информацию о конкретной инстанции
|-
| colspan="2" |
* <small>'''id''' - id списка | инстанции (одно и тоже)</small>
|<code><small>{</small></code>
    "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": {}
        }
    ]
<code><small>}</small></code>
|-
! style="color:blue;width: 15%" |'''GET /instances/list'''
! colspan="2" |Получение списка инстанций
|-
| colspan="2" |<small>No parameters</small>
|
|-
! 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="3" |Управление временными интервалами
|}