Действия

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

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

Нет описания правки
Нет описания правки
Строка 44: Строка 44:
{| class="wikitable" style="width: 110%"
{| class="wikitable" style="width: 110%"
|+''Описание методов API''
|+''Описание методов API''
! colspan="3" |Управление обзвонами
! colspan="3" |'''<u>Управление обзвонами</u>'''
|-
|-
! style="color:green;width: 15%" |'''POST /calls/call'''
! style="color:green;width: 15%" |'''POST /calls/call'''
Строка 102: Строка 102:
<small><code>}</code></small>
<small><code>}</code></small>
|-
|-
! colspan="3" |<nowiki>Управление списками обзвона | оповещения</nowiki>
! colspan="3" |'''<u><nowiki>Управление списками обзвона | оповещения</nowiki></u>'''
|-
|-
! style="color:green;width: 15%" |'''POST /lists/add'''
! style="color:green;width: 15%" |'''POST /lists/add'''
Строка 270: Строка 270:
<small><code>}</small></code>
<small><code>}</small></code>
|-
|-
! colspan="3" |<nowiki>Управление инстанциями обзвона | оповещения</nowiki>
! colspan="3" |'''<u><nowiki>Управление инстанциями обзвона | оповещения</nowiki></u>'''
|-
|-
! style="color:green;width: 15%" |'''POST /instances/add/{list_id}'''
! style="color:green;width: 15%" |'''POST /instances/add/{list_id}'''
Строка 345: Строка 345:
<small><code>}</code></small>
<small><code>}</code></small>
|-
|-
! colspan="3" |Управление временными интервалами
! colspan="3" |'''<u>Управление временными интервалами</u>'''
|-
|-
!'''POST /timeintervals/add'''
! style="color:green;width: 15%" '''POST /timeintervals/add'''
! colspan="2" |Создание временного интервала
! colspan="2" |Создание временного интервала
|-
|-
Строка 458: Строка 458:
<small><code>}</code></small>
<small><code>}</code></small>
|-
|-
! colspan="3" |Управление конфигурациями
! colspan="3" |'''<u>Управление конфигурациями</u>'''
|-
|-
!'''GET /configs/get/{id}'''
!'''GET /configs/get/{id}'''
Строка 529: Строка 529:
<small><code>}</code></small>
<small><code>}</code></small>
|-
|-
! colspan="3" |Логирование
! colspan="3" |'''<u>Логирование</u>'''
|-
|-
!'''GET /logs/logs'''
!'''GET /logs/logs'''
Строка 578: Строка 578:
<small><code>}</code></small>
<small><code>}</code></small>
|-
|-
! colspan="3" |Лицензия
! colspan="3" |'''<u>Лицензия</u>'''
|-
|-
!'''GET /license/check'''
!'''GET /license/check'''

Версия от 11:57, 19 августа 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": []

}

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": "сообщение о статусе результата"

}

Управление временными интервалами
style="color:green;width: 15%" 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=3016