Документация Сибирь.Диалог 1.2.14
Описание функциональных характеристик программы для ЭВМ, информация, необходимая для установки, информация, необходимая для эксплуатации, и описание процессов, обеспечивающих поддержание жизненного цикла программного обеспечения. Документы размещены в открытом доступе, регистрация не требуется.
Подготовлено правообладателем - ООО «ФИИ», ИНН 5402076457. Редакция от .
Описание функциональных характеристик
Программа для ЭВМ «Сибирь.Диалог» (Siberia Dialog), версия 1.2.14. Правообладатель - ООО «ФИИ».
1. Назначение
Программа представляет собой платформу автоматизированного диалога с клиентами организаций: робот исходящего телефонного обзвона, прием входящих звонков и чат-бот для текстовых каналов. Применяется для массового информирования и обслуживания абонентов в жилищно-коммунальном хозяйстве, энергосбыте, медицинских и иных организациях с массовой клиентской базой. Разворачивается в инфраструктуре эксплуатанта.
2. Функциональные характеристики
2.1. Диалог по сценарию. Сценарии описываются в декларативной форме, конечным автоматом состояний, отдельно от кода. Корректность сценария проверяется до запуска. В реплики подставляются персональные значения.
2.2. Исходящий обзвон. Заказчики, кампании, загрузка контактов из файлов CSV и XLSX, запуск и остановка кампании, дозвон через телефонную подсистему (протокол SIP, управление по программному интерфейсу ARI), голосовой диалог с распознаванием и синтезом речи.
2.3. Планирование касаний. Сегменты получателей, последовательность касаний по каналам с интервалами, выбор времени дозвона по накопленной статистике ответов, сравнительные испытания вариантов сценария и текста с отчетом о результате.
2.4. Прием входящих звонков. Входящая линия принимает вызов, ведет диалог по сценарию и при необходимости передает разговор оператору с сохранением контекста.
2.5. Распознавание намерений и извлечение сведений из реплик собеседника. Речевые технологии подключаются через единый интерфейс провайдера и взаимозаменяемы. Поддерживается распознавание речи в контуре эксплуатанта, без передачи звука во внешние службы.
2.6. Текстовые каналы. Чат-боты систем мгновенных сообщений (Telegram, MAX, VK) с проверкой секретов вебхуков, веб-виджет с подписанными сеансами, отправка коротких сообщений через провайдера SMS.
2.7. Контур согласий, отказов и маркировки. Учет согласий по целям обработки, реестр отказов от взаимодействия с загрузкой из внешних источников, маркировка рекламных сообщений, отраслевые нормы и профили, лимиты лицензии, журнал решений политики и проверка каждого решения стражем перед отправкой.
2.8. Ограничения коммуникации. Допустимые окна времени с учетом часового пояса абонента, предельное число попыток, учет отказов от взаимодействия.
2.9. Речевая аналитика записей разговоров. Подготовка звука, выделение речевых участков, нарезка на реплики, расчет показателей, отбор разговоров по признакам, управление сроками хранения записей.
2.10. Справочный помощник по базе знаний организации. Поиск по загруженным документам и формирование ответа с указанием источников.
2.11. Обработка входящих обращений и документов. Прием обращений абонентов, разбор приложенных документов, извлечение из них значений и подстановка в сценарий, распознавание показаний приборов учета с фотографий табло.
2.12. Отчетность. Отчеты по кампаниям в табличном виде (XLSX), паспорт попытки информирования с фиксацией времени, канала и исхода, применимый для подтверждения уведомления по постановлению Правительства Российской Федерации N 354, отчет о потерях по причинам недозвона, сводный отчет для руководителя, расчет себестоимости попытки, отчет по сравнительным испытаниям.
2.13. Программный интерфейс управления (REST). Полный цикл операций, автоматическая документация, разграничение доступа по ключам: административный ключ и отдельные ключи заказчиков, многоарендная работа с изоляцией данных заказчиков.
3. Сведения об экземпляре
| Версия | 1.2.14 |
|---|---|
| Состав исходного текста | 161 записи в архиве, из них 159 файлов исходного текста на языке Python, суммарный объем 22 274 строка |
| Архив экземпляра | siberia-dialog-1.2.14.zip, 438 730 байта |
| Контрольная сумма архива (SHA-256) | ece57063f11f27e4e87fc50a68fc302d1f9fe7a28250d7894f411a1955a721ef |
| Снимок исходного текста | коммит 85fd5b0 системы управления версиями |
| Язык программирования | Python версии не ниже 3.12 |
| Хранение данных | PostgreSQL с расширением pgvector, очереди и кэш в Redis |
| Телефонная подсистема | Asterisk (SIP, RTP), управление через ARI |
4. Среда функционирования
Операционные системы семейства Linux, включая отечественные. Работоспособность сборки проверена на ОС Альт Сервер p11. Интерпретатор Python версии не ниже 3.12. Программа работает несколькими процессами: сервер программного интерфейса, обработчик кампаний и голосовой обработчик. Они запускаются командами из раздела эксплуатации непосредственно или, по выбору эксплуатанта, теми же командами средствами контейнеризации. СУБД, хранилище Redis и телефонная подсистема устанавливаются эксплуатантом.
5. Открытые компоненты в составе программы
В программе используются компоненты с открытым исходным текстом на условиях их лицензий, допускающих включение в состав программы и ее коммерческое распространение. Сведения о лицензиях получены из метаданных пакетов в репозитории PyPI по составу файла описания проекта, входящего в заявляемый экземпляр. Компоненты, применяемые только при разработке и в поставку не входящие, в перечень не включены.
| Компонент | Лицензия | Назначение |
|---|---|---|
| pydantic | MIT | проверка и разбор структур данных |
| pydantic-settings | MIT | чтение настроек из окружения |
| pyyaml | MIT License | чтение сценариев диалога |
| httpx | BSD License | запросы к внешним службам |
| fastapi | MIT | программный интерфейс управления |
| uvicorn | BSD-3-Clause | сервер приложений |
| sqlalchemy | MIT | работа с базой данных |
| asyncpg | Apache-2.0 | драйвер PostgreSQL |
| alembic | MIT | миграции схемы базы |
| redis | MIT | клиент очереди и кэша |
| arq | MIT License | фоновые обработчики |
| openpyxl | MIT License | чтение и запись таблиц XLSX |
| python-multipart | Apache-2.0 | загрузка файлов контактов |
| websockets | BSD-3-Clause | голосовой канал и виджет |
| cryptography | Apache-2.0 OR BSD-3-Clause | подписи и проверка лицензии |
| cachetools | MIT | кэширование справочных данных |
| prometheus-fastapi-instrumentator | ISC | метрики работы |
| tzdata | Apache-2.0 | часовые пояса абонентов |
| snowballstemmer | BSD-3-Clause | поиск по базе знаний |
| pillow | MIT-CMU | обработка изображений документов и фотографий табло |
| pypdfium2 | BSD-3-Clause, Apache-2.0, dependency licenses | разбор PDF при извлечении данных из документов |
| numpy | BSD-3-Clause AND 0BSD AND MIT AND Zlib AND CC0-1.0 | расчеты речевой аналитики |
| jsonschema | MIT | проверка манифеста выпуска |
| pipecat-ai | BSD-2-Clause | голосовой конвейер |
| aiogram | MIT | канал Telegram |
| vkbottle | MIT License | канал VK |
| pypdf | BSD-3-Clause | разбор документов базы знаний |
| onnxruntime | MIT License | локальный расчет эмбеддингов |
| pgvector | MIT | векторный тип в базе |
Внешние системные службы, необходимые для работы (телефонная подсистема Asterisk, средство обработки звука ffmpeg, СУБД PostgreSQL, хранилище Redis), в состав экземпляра не входят, правообладателем не распространяются и устанавливаются эксплуатантом самостоятельно. Программа взаимодействует с ними по сетевым протоколам как отдельными процессами, их исходный текст в программу не компонуется и не изменяется.
«11» сентября 2026 г.
Информация, необходимая для установки
Экземпляр поставляется архивом по лицензионному договору вместе с контрольной суммой SHA-256.
1. Проверка экземпляра
Экземпляр поставляется архивом siberia-dialog-1.2.14.zip размером 438 730 байта. До установки сверить контрольную сумму:
Ожидаемое значение: ece57063f11f27e4e87fc50a68fc302d1f9fe7a28250d7894f411a1955a721ef.
2. Требования к окружению
Операционная система семейства Linux, работоспособность проверена на ОС Альт Сервер p11 и Astra Linux 1.8. Интерпретатор Python версии не ниже 3.12. СУБД PostgreSQL с расширением pgvector, хранилище Redis. Для голосового контура телефонная подсистема Asterisk и пакеты ffmpeg и ffprobe (в ОС Альт ffprobe устанавливается отдельным пакетом). Средства контейнеризации не обязательны.
3. Установка без телефонии для проверки работоспособности
Распаковать архив:
Создать пустой файл README.md. Файл описания проекта pyproject.toml называет его в поле readme, а в архив включены только файлы исходного текста и файл описания проекта. Без README.md средство сборки прерывает установку ошибкой «OSError: Readme file does not exist: README.md».
Установить программу в отдельное окружение Python и активировать его:
Задать три обязательных значения и запустить сервер программного интерфейса. Значения ниже проверочные, для эксплуатации задаются свои. Для проверки без СУБД указана база SQLite, таблицы в ней программа создает сама:
В журнале появляется строка «Application startup complete.». Проверка из другого окна:
Проверка сценария и диалог в консоли. Сценарии диалогов в поставку не входят, их готовит эксплуатант и размещает в каталоге scenarios. Для проверки установки достаточно минимального сценария из двух состояний, его создают так:
Команда validate отвечает строкой «OK scenarios/demo_info.yaml: 2 состояний», команда chat ведет диалог в консоли, ответ вводится с клавиатуры, пример вывода приведен в разделе эксплуатации, п. 6.5.
4. Установка полного набора служб
Задать переменные окружения или записать их в файл .env в рабочем каталоге. Обязательны ARI_PASSWORD, SECRET_KEY и API_ADMIN_KEY. Подключение к СУБД и Redis задается строками DATABASE_URL и REDIS_URL, пароли входят в их состав. Прочие настройки перечислены в разделе эксплуатации, п. 6.2.
Применить миграции схемы базы данных. Файла alembic.ini в архиве нет, его создают в каталоге распаковки:
Последняя команда отвечает «0012 (head)». Затем запустить службы, каждую отдельным процессом (подробно в разделе эксплуатации, п. 6.3):
Голосовому обработчику нужна телефонная подсистема Asterisk с интерфейсом ARI. Те же команды можно выполнять средствами контейнеризации, это не обязательно.
5. Лицензия
Файл лицензии license.json передается лицензиату вместе с экземпляром и размещается в каталоге, указанном настройкой. Файл содержит наименование лицензиата, ИНН, срок действия и предельные значения: число одновременных голосовых линий и число чат-каналов. Подпись файла проверяется программой локально. Обращения к внешним службам активации не выполняются. Без файла лицензии, а также по истечении срока программа продолжает работать с демонстрационными ограничениями: две голосовые линии и один чат-канал. Статус лицензии виден в сведениях о программе.
Информация, необходимая для эксплуатации
Руководство администратора: загрузка, запуск, выполнение и завершение программы, команды управления и ответы программы на них.
Относится к экземпляру siberia-dialog-1.2.14.zip. Примеры ответов получены запуском этого экземпляра 28 сентября 2026 года с базой SQLite, без телефонной подсистемы, Redis и PostgreSQL. Где запуск не выполнялся, это сказано в тексте. Ответы и сообщения программы приведены дословно, с ее собственной орфографией и знаками.
6. Эксплуатация
6.1. Состав программы
Программа устанавливается как пакет Python siberia_dialog и работает несколькими процессами. Все процессы читают одни и те же настройки из переменных окружения и из файла .env в текущем каталоге процесса.
| Процесс | Команда запуска | Назначение |
|---|---|---|
| Сервер программного интерфейса | uvicorn siberia_dialog.api.app:app | Управление заказчиками, кампаниями, согласиями и отказами, базой знаний, документами, отчетами. Прием вебхуков чат-каналов |
| Обработчик кампаний | arq siberia_dialog.campaigns.worker.WorkerSettings | Набор номеров каждые 10 секунд, шаги лестницы касаний, импорт баз, удаление данных по срокам хранения, разбор записей речевой аналитикой |
| Голосовой обработчик | python -m siberia_dialog.voice.server | Прием событий Asterisk ARI и аудиопотока AudioSocket, голосовой диалог |
| Адаптер Telegram | python -m siberia_dialog.channels.telegram | Бот Telegram опросом сервера Telegram, если вебхук не используется |
| Командная строка | python -m siberia_dialog.cli | Проверка и отладка сценариев, прогрев кэша синтеза речи, перешифрование секретов, паспорт сценария, самопроверка |
| Проверка лицензии | python -m siberia_dialog.cli_license | Проверка подписи файла лицензии |
| Проверка живости | python -m siberia_dialog.healthcheck worker|voice | Код 0, если обработчик кампаний или голосовой обработчик жив |
Внешние службы в состав экземпляра не входят и устанавливаются эксплуатантом: СУБД PostgreSQL, хранилище Redis, телефонная подсистема Asterisk с интерфейсом ARI, пакеты ffmpeg и ffprobe для речевой аналитики, программа tesseract для распознавания документов. Сценарии диалогов, правила речевой аналитики, шаблоны документов, модели распознавания и файл лицензии размещает эксплуатант в каталогах, заданных настройками.
6.2. Загрузка
Программа загружается по разделу установки: проверка контрольной суммы, распаковка, создание файла README.md, установка пакета, настройка окружения, миграции (пп. 1, 3, 4). Ответ программы установки, если шаг с README.md пропущен (проверено 28.09.2026):
Дополнения, указываемые в квадратных скобках при установке: voice для голосового обработчика, chat для адаптеров Telegram и VK, rag для векторного поиска по базе знаний, dev для средств разработки.
Обязательные переменные окружения. Без них не запускается ни один процесс программы:
| Переменная | Требование | Назначение |
|---|---|---|
ARI_PASSWORD | Не короче 12 знаков | Пароль пользователя ARI в Asterisk |
SECRET_KEY | Не короче 32 знаков | Шифрование токенов заказчиков, подпись сеансов веб-виджета |
API_ADMIN_KEY | Не короче 24 знаков | Ключ администратора для заголовка X-API-Key |
Ответ программы, если они не заданы (код возврата 1):
Основные необязательные переменные и значения по умолчанию:
| Переменная | По умолчанию | Назначение |
|---|---|---|
DATABASE_URL | postgresql+asyncpg://dialog:dialog@localhost:5432/dialog | Строка подключения к СУБД, пароль СУБД задается в ее составе |
REDIS_URL | redis://localhost:6379/0 | Очередь обработчика кампаний, пароль Redis задается в составе строки |
ARI_URL, ARI_USER, ARI_APP | http://localhost:8088/ari, dialog, siberia_dialog | Подключение к Asterisk |
AUDIOSOCKET_HOST, AUDIOSOCKET_PORT | 0.0.0.0, 9092 | Прием AudioSocket голосовым обработчиком |
STT_PROVIDER, TTS_PROVIDER | yandex, yandex | Распознавание (yandex, salute, vosk) и синтез (yandex, salute) речи |
YANDEX_API_KEY, SALUTE_CLIENT_ID, SALUTE_CLIENT_SECRET | Пусто | Реквизиты речевых служб |
GATEWAY_URL, GATEWAY_API_KEY | Пусто | Языковая модель. Пусто означает работу на правилах и словарях |
LICENSE_PATH | license.json | Файл лицензии |
SCENARIOS_DIR | ./scenarios | Каталог сценариев |
RECORDINGS_DIR, DATA_DIR, TTS_CACHE_DIR | ./recordings, ./data, ./tts_cache | Записи разговоров, данные, кэш синтеза |
ANALYTICS_RULES_DIR, DOCUMENT_TEMPLATES_DIR | ./analytics_rules, ./document_templates | Правила речевой аналитики, шаблоны документов |
ENABLE_DOCS | true | Страница описания программного интерфейса /docs |
MAX_UPLOAD_MB | 20 | Предельный размер загружаемого файла |
RATE_LIMIT_ADMIN_PER_MIN, RATE_LIMIT_OCR_PER_MIN, RATE_LIMIT_WEBHOOK_PER_MIN, RATE_LIMIT_WEBHOOK_IP_PER_MIN | 600, 30, 60, 600 | Лимиты запросов в минуту |
RATE_LIMIT_BACKEND, SESSION_BACKEND | memory, memory | Хранение окон лимитов и сеансов чатов: memory или redis |
TRUSTED_PROXIES | Пусто | Прокси, чьему заголовку X-Forwarded-For программа доверяет |
SINGLE_TENANT | true | Один заказчик на инсталляцию |
TRUNK_CHANNELS | 0 | Емкость SIP-транка, 0 означает, что общий предел не применяется |
CALL_WATCHDOG_SEC | 90 | Через сколько секунд после начала вызова проверять, жив ли канал |
OPTOUT_REGISTRY_REQUIRED, OPTOUT_REGISTRY_MAX_AGE_DAYS | true, 30 | Обязательность и срок свежести сверки с реестром отказов оператора |
LIMIT_PER_DAY, LIMIT_PER_WEEK, LIMIT_PER_MONTH | 1, 2, 8 | Частотные ограничения попыток |
WINDOW_WEEKDAY, WINDOW_WEEKEND | 08:00-22:00, 09:00-20:00 | Допустимые окна вызовов |
PUBLIC_BASE_URL | Пусто | Внешний адрес программы, нужен для подписки вебхука MAX |
EXECUTOR_NAME, EXECUTOR_ADDRESS, SYSTEM_LOCATION | ООО «Финансовый искусственный интеллект», пусто, пусто | Реквизиты в акте уничтожения персональных данных |
ANALYTICS_RETENTION_DAYS | 30 | Срок хранения записей пакета аналитики после передачи отчета |
Схема базы данных. При строке подключения к SQLite сервер программного интерфейса создает таблицы сам при запуске. Для PostgreSQL схема создается миграциями Alembic из каталога src/siberia_dialog/db/migrations, последняя ревизия 0012. Адрес базы миграции берут из DATABASE_URL. Файла alembic.ini в архиве нет, он создается при установке (раздел установки, п. 4). Миграции проверены на SQLite, на PostgreSQL не проверялись:
6.3. Запуск
Порядок: СУБД и Redis, миграции, сервер программного интерфейса, обработчик кампаний, голосовой обработчик. Адрес и порт сервера выбирает эксплуатант, 8000 в примерах условный. Команды выполняются в окружении, активированном после установки командой . .venv/bin/activate.
Сервер программного интерфейса.
При запуске программа проверяет базу часовых поясов (без нее запуск прерывается), языковые пакеты tesseract (при их отсутствии пишет предупреждение и продолжает работу) и для SQLite создает таблицы. Признак успешного запуска в журнале (в прогоне tesseract не был установлен, отсюда предупреждение):
Проверка работоспособности:
Поле license.status принимает значения valid, expired, invalid и demo. Без файла лицензии, с недействительной подписью и по истечении срока действуют демонстрационные ограничения: две голосовые линии, один чат-канал, пять страниц документа на запрос.
Обработчик кампаний.
Расписание: набор номеров каждые 10 секунд, шаги лестницы касаний каждую минуту, импорт баз в 03:00, удаление данных по срокам хранения в 04:00, повторная постановка застрявших пакетов аналитики каждые 5 минут. Без ffmpeg обработчик пишет предупреждение «речевая аналитика недоступна» и продолжает обзвон. Запуск с Redis в прогоне не выполнялся. Без Redis обработчик делает пять попыток подключения и завершается с кодом 1:
Проверка живости (обработчик обновляет отметку в Redis раз в 30 секунд). Код 0 означает, что обработчик жив, код 1 означает, что нет, причина печатается в поток ошибок:
Голосовой обработчик.
Признак запуска в журнале:
Эта строка и проверка живости подтверждают только прием AudioSocket. Подключение к Asterisk программа в журнал не пишет: при недоступном ARI она повторяет подключение каждые 2 секунды без сообщений. В прогоне Asterisk не было, а проверка живости ответила кодом 0:
Если порт AudioSocket занять не удалось, процесс не завершается, а пишет ошибку «AudioSocket ... не поднялся» и повторяет попытку через 30 секунд. Работа с Asterisk и голосовой диалог в прогоне не проверялись.
Адаптер Telegram опросом. Запускается командой python -m siberia_dialog.channels.telegram при заданном TELEGRAM_BOT_TOKEN. В прогоне не запускался.
6.4. Выполнение: программный интерфейс
6.4.1. Общие правила. Запросы управления сопровождаются заголовком X-API-Key. Ключ не проверяется у адресов /health, /about, /docs, /openapi.json, /metrics и у вебхуков /webhooks/..., которые проверяют секреты каналов. Ключ администратора задается в API_ADMIN_KEY, ключ заказчика выдается запросом POST /customers/{customer_id}/api-key и хранится в базе только в виде хэша. Заказчик видит и меняет только свои данные. Описание программного интерфейса в формате OpenAPI отдается по адресу /openapi.json, интерактивная страница по адресу /docs, метрики по адресу /metrics.
Ответ об ошибке содержит поле detail. Ошибки проверки входных данных приходят с кодом 422 списком:
| Код | detail | Причина |
|---|---|---|
| 401 | X-API-Key required | Нет заголовка ключа |
| 401 | invalid API key | Ключ не совпадает ни с ключом администратора, ни с ключом заказчика |
| 403 | admin role required | Операция только для администратора |
| 403 | access to another customer denied | Ключ заказчика обращается к чужому заказчику |
| 403 | access to another customer's campaign denied | Ключ заказчика обращается к чужой кампании |
| 404 | Not Found | Объекта нет. Для несуществующей кампании 404 получает и администратор |
| 413 | file too large (> 20 MB) | Файл больше MAX_UPLOAD_MB |
| 400 | empty file, unsupported file type, damaged ZIP container | Пустой файл, формат не принимается этой операцией, поврежденный архив |
| 429 | rate limit exceeded | Превышен лимит запросов, заголовок Retry-After: 60. Окно считается на ключ (для документов отдельное), для вебхуков на заказчика и адрес и отдельно на адрес |
| 502 | upstream service error | Внешняя служба ответила ошибкой |
Тип загружаемого файла определяется по содержимому, а не по расширению. Каждый запрос POST, PUT, PATCH, DELETE вне /webhooks/ записывается в журнал аудита с ролью, адресом и кодом ответа.
6.4.2. Порядок работы с кампанией.
| Шаг | Запрос | Ответ программы в прогоне |
|---|---|---|
| 1. Создать заказчика (администратор) | POST /customers | 200: {"id":"2d017d916c8a403c8d5f110281501855"} |
| 2. Выдать ключ заказчика | POST /customers/{customer_id}/api-key | 200: {"api_key":"sd_..."} |
| 3. Для голосовой кампании заполнить маркировку вызовов | PATCH /customers/{customer_id}/settings с call_labeling | 200: {"settings":{"chat_scenario":"demo_info","call_labeling":{"org_name":"УК Пример","category":"info"},"channels":{"max":{"secret":"***"}}}} |
| 4. Загрузить выгрузку реестра отказов оператора (администратор) | POST /compliance/optout-registry/import | 200: {"rows":2,"invalid":1,"added":2,"source":"operator","provider":"Novofon","exported_at":"2026-09-20T00:00:00+00:00","digest":"d35014feef7287081d59bf17e3775c9e231119aeca4b9a178db6c5ba06dd33c1"} |
| 5. Создать кампанию, файл сценария лежит в SCENARIOS_DIR | POST /campaigns | 200: {"id":"77fd896bbd964b9cbc10f6323c39b4f8","legal_basis":"service"} |
| 6. Загрузить контакты CSV или XLSX | POST /campaigns/{campaign_id}/contacts | 200: {"loaded":1,"errors":["строка 3: некорректный телефон «12345»"],"errors_total":1} |
| 7. Запустить | POST /campaigns/{campaign_id}/start | 200: {"id":"77fd896bbd964b9cbc10f6323c39b4f8","status":"running"} |
| 8. Следить за ходом | GET /campaigns/{campaign_id} | 200: {"id":"77fd896bbd964b9cbc10f6323c39b4f8","name":"Чат","status":"running","scenario_id":"demo_info","channel":"telegram","legal_basis":"service","contacts":{"pending":1}} |
| 9. Приостановить, возобновить повторным start | POST /campaigns/{campaign_id}/pause | 200: {"id":"77fd896bbd964b9cbc10f6323c39b4f8","status":"paused"} |
| 10. Получить отчеты и акты | GET /reports/campaigns/{campaign_id}, /xlsx, /csv, /losses, /ab, /executive, GET /reports/attempts/{attempt_id}/proof | 200: {"campaign":"Чат","status":"running","contacts":1,"attempts":0,"reached":0,"reach_rate":0.0,"promised":0,"promised_sum_rub":0,"claims_paid":0,"dnc":0,"outcomes":{},"contacts_by_outcome":{},"talk_minutes":0.0,"cost_total_rub":null,"cost_measured_attempts":0,"cost_per_reached_rub":null,"by_status":{"p ... |
Статусы кампании: draft после создания, running, paused, done. Голосовая кампания переходит в done сама, когда у нее не остается контактов в статусах pending, scheduled, calling. Статусы контакта: pending, calling, scheduled (назначен повтор), done, failed, dnc, skipped.
6.4.3. Отказы запуска кампании. Все с кодом 409, причина в поле detail:
| detail | Причина | Что делать |
|---|---|---|
реклама автодозвоном и автоматической рассылкой запрещена ... | Основание advertising у кампании с автоматическим набором | Сменить основание или канал |
реестр отказов оператора не загружен: ..., выгрузка реестра отказов от ... устарела ... | Нет свежей выгрузки реестра отказов (кроме входящей линии voice_in) | Загрузить выгрузку, шаг 4 |
{"detail":"речь не настроена, кампания не запускается: TTS yandex: не задан YANDEX_API_KEY; STT yandex: не задан YANDEX_API_KEY"} | Для voice и voice_in не заданы реквизиты синтеза или распознавания речи. Ответ получен в прогоне | Задать YANDEX_API_KEY или реквизиты SaluteSpeech |
сценарий ... не найден и другие ошибки настройки сравнения или сегментов | Нет файла сценария варианта или он другой отрасли | Исправить настройку кампании или положить файл сценария |
маркировка вызовов не заявлена: заполните settings.call_labeling (org_name, category) ... | Для voice не заполнена маркировка вызовов | Шаг 3 |
неизвестная категория маркировки ..., кампания заявлена рекламной ... | Неверная категория или ее расхождение с основанием | Исправить call_labeling.category |
6.4.4. Перечень операций. Всего 73 операции. Доступ: А администратор, З заказчик в пределах своих данных. Коды 401 и 429 возможны у всех операций с ключом и в таблице не повторяются. Все 73 операции вызваны в прогоне 28.09.2026, у 67 получен успешный ответ, у 6 только ответ об ошибке с указанной причиной. Коды ошибок в таблицах взяты из исходного текста программы, примеры ответов из прогона.
Служебные адреса
| Метод | Путь | Назначение | Формат запроса | Пример ответа | Коды ошибок |
|---|---|---|---|---|---|
| GET | /health | Проверка работоспособности. Ключ не нужен | Нет | 200: {"status":"ok"} | Нет |
| GET | /health/providers | Счетчики обращений к внешним службам с момента запуска процесса. Доступ: А | Нет | 200: {"providers":{}} | 401, 403 |
| GET | /about | Сведения о программе, правообладателе, лицензии и использовании лимитов. Ключ не нужен | Нет | 200: {"product":"Siberia.Dialog","version":"1.2.14","rightsholder":{"name":"ООО «Финансовый искусственный интеллект» (Siberia AI)","inn":"5402076457","kpp":"547301001","ogrn":"1235400001870","address":"630090, г. Новосибирск, ул. Демак ... | Нет |
Заказчики
| Метод | Путь | Назначение | Формат запроса | Пример ответа | Коды ошибок |
|---|---|---|---|---|---|
| POST | /customers | Создать заказчика. Доступ: А | JSON: name 1-255 знаков, обязательно, inn (проверяется контрольная сумма), phone до 32 знаков, vertical zhkh, energy, clinic или generic, tz часовой пояс IANA (по умолчанию Europe/Moscow), in_gov_list, settings | 200: {"id":"2d017d916c8a403c8d5f110281501855"} | 422 (неизвестный часовой пояс, неверный ИНН) |
| GET | /customers | Перечень заказчиков. Доступ: А | Нет | 200: [{"id":"2d017d916c8a403c8d5f110281501855","name":"УК Пример","vertical":"zhkh","tz":"Asia/Novosibirsk"},{"id":"53a12e3a29434f57b5e0e8b175995205","name":"УК Вторая","vertical":"zhkh","tz":"Europe/Moscow"}] | 403 для ключа заказчика |
| GET | /customers/{customer_id} | Карточка заказчика, секреты показаны маской. Доступ: А, З | Нет | 200: {"id":"2d017d916c8a403c8d5f110281501855","name":"УК Пример","inn":"5402076457","phone":null,"vertical":"zhkh","tz":"Asia/Novosibirsk","in_gov_list":false,"settings":{},"has_api_key":false} | 403, 404 |
| PATCH | /customers/{customer_id}/settings | Дополнить настройки заказчика. Ключи верхнего уровня объединяются с прежними, вложенный объект (например channels) заменяется целиком. Доступ: А | JSON: channels.telegram|max|vk|sms|voice, call_labeling (org_name, category: info, service, survey, ads, collection), chat_scenario | 200: {"settings":{"chat_scenario":"demo_info","call_labeling":{"org_name":"УК Пример","category":"info"},"channels":{"max":{"secret":"***"}}}} | 404, 409 (превышен лимит чат-каналов лицензии) |
| POST | /customers/{customer_id}/api-key | Выпустить новый ключ заказчика. Показывается один раз, прежний перестает действовать. Доступ: А | Нет | 200: {"api_key":"sd_..."} | 404 |
| POST | /customers/{customer_id}/base | Загрузить базу абонентов и приборов учета. Доступ: А, З | Форма, поле file: XLSX с колонками Лицевой счет, ФИО, Тип, Улица, Дом, Корпус, Квартира, Телефон, Задолженность, Услуга, Заводской номер, Дата поверки, Предыдущее показание | 200: {"accounts":1,"meters":1} | 400 (неверная база или тип файла), 404, 413, 500 (нет прав на каталог данных, причина в тексте ответа) |
| GET | /customers/{customer_id}/media/{ref} | Фото, присланное абонентом. Доступ: А, З | Нет | Успешный ответ в прогоне не получен: фото не присылались. Ответ: 404: {"detail":"изображение не найдено"} | 404 |
| GET | /customers/{customer_id}/readings.xlsx | Реестр принятых показаний. Доступ: А, З | Нет | 200: книга XLSX 5 031 байт | 404 (база не загружена) |
| POST | /customers/{customer_id}/close | Закрыть пилот: выгрузка данных оператору, удаление и обезличивание данных жителей, акт. Повторный вызов возвращает тот же акт. Доступ: А | JSON: signed_by 3-255 знаков, signed_title 2-255 знаков, transfer_act до 255 знаков | 200: {"act":{"customer_id":"53a12e3a29434f57b5e0e8b175995205","closed_at":"2026-09-28T08:57:19+00:00","by":"admin:admin","export":"53a12e3a29434f57b5e0e8b175995205-20260928085719.zip","export_entries":["consents.csv","dnc.csv","subject ... | 404, 422 |
| POST | /customers/{customer_id}/close/transfer-confirmed | Отметить, что оператор получил выгрузку. Копия выгрузки удаляется, отметка вносится в акт. Доступ: А | Нет | 200: {"act":{"customer_id":"53a12e3a29434f57b5e0e8b175995205","closed_at":"2026-09-28T08:57:19+00:00","by":"admin:admin","export":"53a12e3a29434f57b5e0e8b175995205-20260928085719.zip","export_entries":["consents.csv","dnc.csv","subject ... | 404, 409 |
Отказы и согласия заказчика (доступ: А, З)
| Метод | Путь | Назначение | Формат запроса | Пример ответа | Коды ошибок |
|---|---|---|---|---|---|
| GET | /customers/{customer_id}/dnc | Перечень отказов от взаимодействия | Нет | 200: [{"phone":"79131234567","source":"operator","created_at":"2026-09-28T08:57:03"}] | 403 |
| POST | /customers/{customer_id}/dnc | Добавить отказ | JSON: phone до 32 знаков, source call, operator, import, gosuslugi, contract, lk, sms или paper, evidence до 1000 знаков | 200: {"status":"added","keys":["79131234567"]} | 400 (bad phone), 404 |
| DELETE | /customers/{customer_id}/dnc/{phone} | Снять отказ по всем связанным идентификаторам | Нет | 200: {"removed":1} | 400 |
| POST | /customers/{customer_id}/dnc/import | Массовый импорт отказов | Форма, поле file: CSV или XLSX с колонкой телефона | 200: {"imported":2} | 400, 404, 413, 500 (CSV из одной колонки, см. п. 6.7) |
| POST | /customers/{customer_id}/identity-links | Связать телефон с идентификатором абонента в канале. Отказ распространяется на обе стороны | JSON: phone, channel_identity вида канал:идентификатор | 200: {"created":true,"identity_links":1} | 400, 404, 422 |
| POST | /customers/{customer_id}/consents | Записать согласие | JSON: phone, purpose pdn, service или advertising (по умолчанию service), source, evidence | 200: {"status":"added","purpose":"service"} | 400, 404 |
| GET | /customers/{customer_id}/consents | Перечень согласий с датами записи и отзыва | Нет | 200: [{"phone":"79139876543","purpose":"service","source":"contract","created_at":"2026-09-28T08:57:04","revoked_at":null}] | 403 |
| GET | /customers/{customer_id}/consents/{phone} | Действующие цели согласия абонента | Нет | 200: {"has_consent":true,"purposes":["service"],"advertising":false} | 400 |
| DELETE | /customers/{customer_id}/consents/{phone} | Отозвать согласие. Без параметра отзываются все цели, запись сохраняется | Параметр purpose (необязателен) | 200: {"revoked":["service"]} | 400 |
Реестр отказов оператора (доступ: А)
| Метод | Путь | Назначение | Формат запроса | Пример ответа | Коды ошибок |
|---|---|---|---|---|---|
| GET | /compliance/optout-registry | Состояние сверки с реестром отказов оператора | Нет | 200: {"required":true,"max_age_days":30,"fresh":true,"problem":null,"last_import":{"source":"operator","provider":"Novofon","exported_at":"2026-09-20T00:00:00","imported_at":"2026-09-28T08:57:04","age_days":8,"rows":2,"invalid":1,"adde ... | 403 |
| GET | /compliance/operator/lines | SIP-линии и виртуальные номера у оператора связи (Data API Новофон) | Нет | Успешный ответ в прогоне не получен: ключ оператора не задавался. Ответ: 409: {"detail":"не задан NOVOFON_API_KEY: ключ Data API оператора связи"} | 409 (нет NOVOFON_API_KEY), 502 (оператор не ответил) |
| POST | /compliance/optout-registry/import | Загрузить выгрузку реестра отказов. Повторная загрузка того же файла дает added: 0 | Форма: file CSV, XLSX или TXT, source operator, gosuslugi или rkn, provider до 128 знаков, exported_at дата ГГГГ-ММ-ДД | 200: {"rows":2,"invalid":1,"added":2,"source":"operator","provider":"Novofon","exported_at":"2026-09-20T00:00:00+00:00","digest":"d35014feef7287081d59bf17e3775c9e231119aeca4b9a178db6c5ba06dd33c1"} | 400, 413, 422 |
База знаний (доступ: А, З)
| Метод | Путь | Назначение | Формат запроса | Пример ответа | Коды ошибок |
|---|---|---|---|---|---|
| POST | /customers/{customer_id}/knowledge/collections | Создать коллекцию | JSON: name 1-255 знаков, description до 2000 знаков | 201: {"id":"a164b9a044fb40559278badd6f092e72","name":"Регламенты","version":1} | 404, 422 |
| GET | /customers/{customer_id}/knowledge/collections | Перечень коллекций | Нет | 200: [{"id":"a164b9a044fb40559278badd6f092e72","name":"Регламенты","description":null,"version":1,"documents":0,"chunks":0,"created_at":"2026-09-28T08:57:04"}] | 403 |
| DELETE | /customers/{customer_id}/knowledge/collections/{collection_id} | Удалить коллекцию с документами | Нет | 204, тело пустое | 404 |
| GET | /customers/{customer_id}/knowledge/{collection_id}/documents | Перечень документов коллекции | Нет | 200: [{"id":"b6eaee7f4a2a4edf9b6d4e94b78b3d0a","title":"kb.txt","filename":"kb.txt","kind":"txt","pages":null,"chunks":1,"size_bytes":80,"sha256":"ee887318c33f140be45504ecf9c3562bd4fb5de5a7058d1321203941e51e0007","status":"ready","uplo ... | 404 |
| POST | /customers/{customer_id}/knowledge/{collection_id}/documents | Загрузить и проиндексировать документ | Форма, поле file: PDF, DOCX, HTML, MD или TXT, параметр title | 201: {"id":"b6eaee7f4a2a4edf9b6d4e94b78b3d0a","title":"kb.txt","kind":"txt","pages":null,"chunks":1,"collection_version":2} | 400 (документ не разобран), 404, 413 |
| DELETE | /customers/{customer_id}/knowledge/{collection_id}/documents/{document_id} | Удалить документ | Нет | 204, тело пустое | 404 |
| GET | /customers/{customer_id}/knowledge/{collection_id}/documents/{document_id}/source | Исходный файл документа | Нет | 200: Оплата квитанции до 10 числа каждого месяца. | 404 |
| POST | /customers/{customer_id}/knowledge/{collection_id}/query | Ответ на вопрос по коллекции с источниками. Если ответа нет, так и сообщается | JSON: question 1-2000 знаков, top_k 1-20 | 200: {"answer":"Оплата квитанции до 10 числа каждого месяца.\n— kb.txt, фрагмент 1","found":true,"generated":false,"sources":[{"document_id":"b6eaee7f4a2a4edf9b6d4e94b78b3d0a","document_title":"kb.txt","citation":"фрагмент 1","page":nu ... | 404 (коллекция не найдена) |
Кампании
| Метод | Путь | Назначение | Формат запроса | Пример ответа | Коды ошибок |
|---|---|---|---|---|---|
| POST | /campaigns | Создать кампанию. Доступ: любой ключ, заказчик только для себя | JSON: customer_id, name, scenario_id (файл channel voice, telegram, max, vk или voice_in, legal_basis, concurrency 1-200, max_attempts 1-10, defaults | 200: {"id":"77fd896bbd964b9cbc10f6323c39b4f8","legal_basis":"service"} | 400 (сценарий не найден), 403, 404, 422 |
| POST | /campaigns/{campaign_id}/contacts | Загрузить контакты. Доступ: А, З своей кампании | Форма, поле file: CSV или XLSX, колонка телефона phone, телефон, тел или номер | 200: {"loaded":1,"errors":["строка 3: некорректный телефон «12345»"],"errors_total":1} | 400 (тип файла, больше 500 000 строк), 404, 413, 500 (CSV из одной колонки) |
| POST | /campaigns/{campaign_id}/start | Запустить или возобновить кампанию. Доступ: А, З своей кампании | Нет | 200: {"id":"77fd896bbd964b9cbc10f6323c39b4f8","status":"running"} | 404, 409 (причина в тексте, см. п. 6.4.3) |
| POST | /campaigns/{campaign_id}/pause | Приостановить кампанию. Доступ: А, З своей кампании | Нет | 200: {"id":"77fd896bbd964b9cbc10f6323c39b4f8","status":"paused"} | 404 |
| GET | /campaigns/{campaign_id} | Состояние кампании и число контактов по статусам. Доступ: А, З своей кампании | Нет | 200: {"id":"77fd896bbd964b9cbc10f6323c39b4f8","name":"Чат","status":"running","scenario_id":"demo_info","channel":"telegram","legal_basis":"service","contacts":{"pending":1}} | 403, 404 |
| GET | /campaigns | Перечень кампаний, заказчику только свои. Доступ: любой ключ | Нет | 200: [{"id":"3ae88749b2b24703aa85fab22f058d01","name":"Голос","status":"draft","scenario_id":"demo_info"},{"id":"77fd896bbd964b9cbc10f6323c39b4f8","name":"Чат","status":"running","scenario_id":"demo_info"}] | 401 |
Отчеты
| Метод | Путь | Назначение | Формат запроса | Пример ответа | Коды ошибок |
|---|---|---|---|---|---|
| GET | /reports/campaigns/{campaign_id} | Сводка кампании. Доступ: А, З своей кампании | Нет | 200: {"campaign":"Чат","status":"running","contacts":1,"attempts":0,"reached":0,"reach_rate":0.0,"promised":0,"promised_sum_rub":0,"claims_paid":0,"dnc":0,"outcomes":{},"contacts_by_outcome":{},"talk_minutes":0.0,"cost_total_rub":null, ... | 403, 404 |
| GET | /reports/campaigns/{campaign_id}/xlsx | Сводка файлом. Доступ: А, З своей кампании | Параметр format: xlsx (по умолчанию) или csv | 200: книга XLSX 6 056 байт | 400 (неизвестный формат), 403, 404 |
| GET | /reports/campaigns/{campaign_id}/csv | Детализация кампании CSV (разделитель точка с запятой, UTF-8 с BOM). Доступ: А, З своей кампании | Нет | 200: файл CSV 253 байт | 403, 404 |
| GET | /reports/campaigns/{campaign_id}/losses | Воронка и причины потерь. Доступ: А, З своей кампании | Нет | 200: {"campaign":"Чат","status":"running","funnel":{"contacts":1,"reached":0,"identity_confirmed":0,"informed":0,"result":0},"success":0,"in_progress":1,"in_progress_by_code":{"awaiting_attempts":1},"callbacks_scheduled":0,"lost":0,"lo ... | 403, 404 |
| GET | /reports/campaigns/{campaign_id}/ab | Итог сравнения редакций сценария. Доступ: А, З своей кампании | Нет | 200: {"campaign":"Чат","ab":false,"note":"сравнение не настроено: кампания идёт одним сценарием"} | 403, 404 |
| GET | /reports/campaigns/{campaign_id}/losses.xlsx | Потери файлом. Доступ: А, З своей кампании | Нет | 200: книга XLSX 6 371 байт | 403, 404 |
| GET | /reports/campaigns/{campaign_id}/executive | Отчет руководителю, одна печатная страница. Доступ: А, З своей кампании | Нет | 200: страница HTML 3 728 байт | 403, 404 |
| GET | /reports/attempts/{attempt_id}/proof | Акт по попытке: по звонку о направлении уведомления, по чату о приеме обращения. Доступ: любой ключ, заказчик только свои | Нет | 200: АКТ О ПРИЁМЕ ОБРАЩЕНИЯ В ЧАТЕ Исполнитель: УК Пример Канал: web Абонент: web:cc2dd2deb34548f2a84ca6091a304fcb (веб — id сессии; мессенджер — id пользователя); лицевой счёт: не назван Обращение начато: 28.09.2026 15:57 (Asia/Novosi ... | 403, 404 |
| GET | /reports/customers/{customer_id}/weekly | Письмо недели клиенту. Доступ: А, З | Параметры until (дата), days 1-92, по умолчанию 7 | 200: страница HTML 4 667 байт | 404, 422 |
| GET | /reports/customers/{customer_id}/appeals.xlsx | Журнал обращений за период. Доступ: А, З | Параметры until, days 1-92 | 200: книга XLSX 7 798 байт | 404, 422 |
| GET | /reports/customers/{customer_id}/flow | Поток обращений в чате за период. Доступ: А, З | Параметры until, days 1-92 (по умолчанию 14), work_from 0-23, work_to 1-24 | 200: страница HTML 8 984 байт | 404, 422 |
| GET | /reports/customers/{customer_id}/flow.xlsx | Поток обращений файлом. Доступ: А, З | Те же параметры | 200: книга XLSX 8 109 байт | 404, 422 |
Речевая аналитика (доступ: любой ключ, заказчик только свое)
| Метод | Путь | Назначение | Формат запроса | Пример ответа | Коды ошибок |
|---|---|---|---|---|---|
| POST | /analytics | Поставить пакет записей на разбор | Форма: customer_id, name обязательны, rules_id (по умолчанию default), source upload или campaign, campaign_id, attempt_ids через запятую, channels_role, language, retention_days 1-365, file ZIP, CSV или XLSX | 200: {"id":"238d5a83cd20449f9ffd42e72213a627","status":"queued","queued":false,"note":"очередь недоступна: пакет принят и будет разобран позже"} | 400 (нет файла, нет правил, неверный срок), 403, 404, 413, 503 (нет ffmpeg) |
| GET | /analytics/batches | Перечень пакетов | Параметры customer_id, limit до 200, offset | 200: {"items":[{"id":"6b631e86bb194c3cadd9364a47dc5722","name":"Пакет","source":"upload","rules_id":"default","status":"queued","total":0,"done":0,"failed":0,"error":null,"created_at":"2026-09-28T08:57:18"},{"id":"238d5a83cd20449f9ffd4 ... | 401 |
| GET | /analytics/calls | Перечень записей | Параметры customer_id, batch_id, q, flagged, date_from, date_to (ГГГГ-ММ-ДД), limit, offset | 200: {"total":0,"query":null,"items":[]} | 400 (неверная дата) |
| GET | /analytics/calls/{call_id} | Запись с расшифровкой | Параметр q | Успешный ответ в прогоне не получен: разбор записей выполняет обработчик кампаний, в прогоне он не работал. Ответ: 404: {"detail":"Not Found"} | 403, 404 |
| GET | /analytics/batches/{batch_id} | Сводка пакета, срок хранения и дата удаления | Нет | 200: {"batch":"Пакет","status":"queued","rules":"default","calls":0,"done":0,"failed":0,"minutes":0.0,"recognised_seconds":0,"single_channel_calls":0,"avg_score":null,"avg_silence_ratio":null,"avg_script_compliance":null,"flags":{},"st ... | 403, 404 |
| DELETE | /analytics/batches/{batch_id} | Удалить записи и расшифровки пакета по акту, не дожидаясь срока. Повтор возвращает тот же акт | Нет | 200: {"deleted":true,"act":{"batch_id":"238d5a83cd20449f9ffd42e72213a627","customer_id":"2d017d916c8a403c8d5f110281501855","deleted_at":"2026-09-28T08:57:18+00:00","by":"customer:2d017d916c8a403c8d5f110281501855","calls_purged":0,"segm ... | 403, 404 |
| GET | /analytics/report.xlsx | Отчет по пакету | Параметр batch_id | 200: книга XLSX 6 673 байт | 403, 404 |
Обработка документов (доступ: любой ключ, модуль лицензируется отдельно)
| Метод | Путь | Назначение | Формат запроса | Пример ответа | Коды ошибок |
|---|---|---|---|---|---|
| POST | /documents/recognize | Распознать текст документа (PDF, JPEG, PNG, TIFF, WebP) | Форма: file, customer_id, lang, pages (вида 1, 1-3, 1,4-6), psm 0-13, store | Успешный ответ в прогоне не получен: программа tesseract не установлена. Ответ: 503: {"detail":"распознавание недоступно: tesseract не найден: tesseract"} | 400, 403 (модуль не в лицензии), 413, 422, 503, 504 |
| POST | /documents/parse | Извлечь реквизиты по шаблону из файла или по ссылке ref | Форма: file или ref, customer_id, template_id, lang | Успешный ответ в прогоне не получен: программа tesseract не установлена, шаблонов нет. Ответ: 503: {"detail":"распознавание недоступно: tesseract не найден: tesseract"} | 400, 403, 404, 413, 422, 503, 504 |
| GET | /documents/templates | Перечень шаблонов документов | Параметр id | 200: [] | 403, 404 |
Вебхуки и веб-виджет (ключ не нужен, проверяются секреты каналов)
| Метод | Путь | Назначение | Формат запроса | Пример ответа | Коды ошибок |
|---|---|---|---|---|---|
| POST | /webhooks/max | Обновления MAX | Заголовок X-Max-Bot-Api-Secret, тело обновления MAX | 200: {"ok":"true"} | 401 |
| POST | /webhooks/max/{customer_id} | Обновления MAX для заказчика | То же | 200: {"ok":"true"} | 401, 404 |
| POST | /webhooks/telegram | Обновления Telegram | Заголовок X-Telegram-Bot-Api-Secret-Token | Успешный ответ по этому адресу не получен: секрет по умолчанию TELEGRAM_WEBHOOK_SECRET не задавался. Ответ: 401: {"detail":"invalid webhook secret"} | 401 |
| POST | /webhooks/telegram/{customer_id} | Обновления Telegram для заказчика | То же | 200: {"ok":"true"} | 401, 404 |
| POST | /webhooks/vk | События Callback API VK, ответ текстом | JSON события с group_id и secret | 200: ok | 401, 403 |
| POST | /webhooks/vk/{customer_id} | События VK для заказчика. На событие confirmation возвращается код подтверждения | То же | 200: abc123 | 401, 403, 404 |
| POST | /webhooks/web/session | Выдать сеанс веб-виджета | Нет | 200: {"session_id":"555aa13e3be64065b6de6be536d6ed82","token":"8bec64f09b579f9d4d18f4f3ac639f5dc95373401790f092a035c8e0cdcb7e69"} | Нет |
| POST | /webhooks/web/{customer_id}/session | Выдать сеанс веб-виджета заказчика | Нет | 200: {"session_id":"8cbaed2a27b84e7d849c23dc7d18651e","token":"cf6ccd3392cb62f2791249391b34d3d97947c0f44cc6ac7cf7643e101832c19a"} | 404 |
| POST | /webhooks/web | Сообщение веб-виджета | JSON: session_id, token (64 знака), text до 4000 знаков, photo | 200: {"text":"Здравствуйте,. Это тестовое сообщение. Вам удобно говорить?","buttons":["Да","Нет"],"done":false} | 400, 403 (invalid session token), 404 |
| POST | /webhooks/web/{customer_id} | Сообщение веб-виджета заказчика | То же | 200: {"text":"Спасибо, до свидания.\n\nЗдравствуйте,. Это тестовое сообщение. Вам удобно говорить?","buttons":["Да","Нет"],"done":true} | 400, 403, 404 |
| GET | /webhooks/web/widget | Страница веб-виджета | Нет | 200: страница HTML 1 836 байт | Нет |
| GET | /webhooks/web/{customer_id}/widget | Страница веб-виджета заказчика | Нет | 200: страница HTML 1 836 байт | 404 |
6.5. Выполнение: командная строка
Вызов python -m siberia_dialog.cli <команда>. Без команды программа печатает подсказку и завершается с кодом 2:
| Команда | Аргументы | Что делает | Ответ программы | Код возврата |
|---|---|---|---|---|
validate | Файлы сценариев | Проверить сценарии | OK scenarios/demo_info.yaml: 2 состояний, 1 фикс. фраз, basis=service или ERR nope.yaml: [Errno 2] No such file or directory: 'nope.yaml' | 0 если все OK, иначе 1 |
chat | Файл сценария, слоты ключ=значение | Диалог по сценарию в терминале. Пустая строка означает молчание, одна цифра нажатие клавиши. Выход по Ctrl+D или Ctrl+C | Реплики робота и кнопки, в конце — конец, исход: informed | 0 |
warmup | Файл сценария | Синтезировать неизменяемые реплики в кэш TTS_CACHE_DIR, обращается к службе синтеза | httpx.LocalProtocolError: Illegal header value b'Api-Key ' | 0, при ошибке 1 |
analytics-rules | Файлы правил | Проверить правила речевой аналитики | OK analytics_rules/default.yaml: 0 обязательных, 0 групп стоп-слов или ERR ... | 0 если все OK, иначе 1 |
rotate-secrets | Нет | Перешифровать настройки заказчиков действующим SECRET_KEY, прежний ключ берется из SECRET_KEY_PREVIOUS | перешифровано заказчиков: 0; теперь SECRET_KEY_PREVIOUS можно убрать | 0 |
passport | Файл сценария, -o файл.md | Каркас паспорта сценария для сдачи-приемки | паспорт: passport.md или текст Markdown | 0 |
smoke | --круг чат|голос, --посев база|реестр | Самопроверка по звеньям от заказчика до реестра показаний на SQLite, без сети. Требует DATABASE_URL на SQLite и сценариев zhkh_debt и zhkh_readings (круг чат) или zhkh_readings_voice (круг голос) в SCENARIOS_DIR, в архив они не входят | Без SQLite: ОТКАЗ: смоук-тест стирает схему базы, а DATABASE_URL ведёт не на SQLite .... Без сценариев в прогоне: 🔴 первое красное звено: 3 — кампания создаётся: 400 {"detail":"scenario zhkh_debt not found"} | 0 все звенья прошли, 2 красное звено или отказ |
cli_license verify <файл> | Файл лицензии | Проверить подпись и срок лицензии | JSON лицензии с полем status, в прогоне для неподписанного файла "status": "invalid" | 0 только при valid, иначе 1 |
cli_license issue | --licensee, --inn, --until, --lines, --channels | Выпустить лицензию закрытым ключом правообладателя. Эксплуатанту не нужна | Подписанный JSON лицензии | 0 |
healthcheck worker | Переменная REDIS_URL | Проверить живость обработчика кампаний | Пусто при успехе, иначе причина в поток ошибок | 0 жив, 1 нет |
healthcheck voice | Переменная AUDIOSOCKET_PORT | Проверить прием AudioSocket голосовым обработчиком | Пусто при успехе, иначе причина, например ConnectionRefusedError(...) | 0 жив, 1 нет |
Команды cli_license и healthcheck вызываются как python -m siberia_dialog.cli_license и python -m siberia_dialog.healthcheck. Пример диалога (тестовый сценарий эксплуатанта, ответ абонента подан через канал ввода, поэтому само слово «да» в выводе не отображается):
6.6. Завершение
Новые вызовы набирает только обработчик кампаний и только по голосовым кампаниям в статусе running. Шаги лестницы касаний выполняются только у кампаний в статусе running. Перед плановой остановкой приостановить кампании (POST /campaigns/{campaign_id}/pause), дождаться, пока в ответе GET /campaigns/{campaign_id} не останется контактов calling, затем остановить голосовой обработчик, обработчик кампаний и сервер программного интерфейса.
Процессы программы завершаются по сигналу SIGINT (Ctrl+C) или SIGTERM, в том числе когда сигнал посылает средство, которым запущены службы. Сервер программного интерфейса при остановке закрывает подключение к очереди и общий HTTP-клиент чат-каналов. Журнал корректной остановки (прогон 28.09.2026, остановка вызвана тем же обработчиком, что у сигнала SIGTERM):
Обработчик кампаний при остановке закрывает HTTP-клиент чат-каналов. Пакеты аналитики в статусе queued после запуска ставятся в очередь повторно каждые 5 минут. Поведение задачи, выполняющейся в момент остановки, определяется библиотекой очереди arq и в прогоне не проверялось.
Голосовой обработчик собственного обработчика сигналов не имеет. Разговоры, идущие в момент остановки, прерываются, их контакты остаются в статусе calling. После запуска обработчик кампаний не раньше чем через CALL_WATCHDOG_SEC (90 секунд) от начала вызова спрашивает Asterisk, существует ли канал. Если канала нет, попытка записывается с исходом no_answer, и контакт вне лестницы касаний получает повтор не раньше чем через 120 минут, пока число попыток меньше max_attempts. Если Asterisk не ответил, решение откладывается до следующего прохода. Перед записью попытки программа проверяет, не записана ли она уже по тому же каналу Asterisk. Этот путь в прогоне не проверялся, он описан по исходному тексту.
Команды командной строки завершаются сами с кодами из п. 6.5, команда chat по окончании сценария или по Ctrl+D, Ctrl+C.
6.7. Сообщения программы и действия администратора
| Сообщение | Где | Что делать |
|---|---|---|
база часовых поясов недоступна: zoneinfo не видит ни одной зоны. ... | Запуск сервера, запуск прерывается | Установить пакет tzdata |
нет языковых пакетов распознавания: ..., распознавание документов недоступно: ... | Запуск сервера, предупреждение | Установить tesseract и пакеты rus, eng или задать TESSERACT_CMD |
языковая модель включена, обращения уходят на ... | Запуск сервера, предупреждение | Убедиться, что адрес ведет к российской службе или к модели в контуре |
rate limit backend error: ... | Сервер | Redis недоступен при RATE_LIMIT_BACKEND=redis, лимит не применяется. Восстановить Redis |
audit write failed: ... | Сервер | Запись журнала аудита не удалась. Проверить базу данных |
очередь недоступна, задача ... отложена: ... | Сервер | Redis недоступен, пакет будет поставлен в очередь повторно. Восстановить Redis |
речевая аналитика недоступна: ... | Запуск обработчика кампаний | Установить ffmpeg и ffprobe |
свободных линий нет (предел: ...) — тик не набирает | Обработчик кампаний | Дождаться освобождения линий или расширить лицензию, проверить TRUNK_CHANNELS |
campaign ...: обзвон остановлен — ... | Обработчик кампаний | Устранить названную причину (маркировка, реестр отказов), набор возобновится сам |
сторож: не спросили Asterisk о канале ... | Обработчик кампаний | Проверить доступность Asterisk ARI |
AudioSocket ... не поднялся (...) | Голосовой обработчик | Исправить AUDIOSOCKET_HOST или освободить порт, процесс повторит попытку через 30 секунд |
входящий на ...: линия не настроена (voice_in-кампаний: N) — отбой | Голосовой обработчик | Создать и запустить кампанию voice_in с номером в defaults.did |
ARI: обработчик события ... упал: ... | Голосовой обработчик | Сбой одного события, прием продолжается. Разобрать по трассе в журнале |
Известные ограничения версии 1.2.14, выявленные в прогоне 28.09.2026:
- Файл CSV из одной колонки без разделителя в операциях POST /customers/{customer_id}/dnc/import и POST /campaigns/{campaign_id}/contacts дает ответ 500 Internal Server Error, в журнале _csv.Error: Could not determine delimiter. Обход: добавить вторую колонку или загрузить XLSX.
- Запрос POST /analytics без файла при source=upload получает ответ 400, но запись о пакете к этому моменту уже создана и остается в статусе queued.
7. Резервное копирование и обновление
Резервному копированию подлежат база данных, каталог записей разговоров и файл лицензии. Обновление выполняется заменой экземпляра на архив новой версии с последующим применением миграций схемы базы данных. Принудительное обновление программой не инициируется.
«28» сентября 2026 г.
Процессы, обеспечивающие поддержание жизненного цикла
Устранение неисправностей, совершенствование программы и сведения о персонале, необходимом для обеспечения такой поддержки.
1. Общие сведения
1.1. Документ описывает процессы поддержания жизненного цикла программы «Сибирь.Диалог» (Siberia Dialog): устранение неисправностей, совершенствование, персонал сопровождения.
1.2. Правообладатель и разработчик программы: Общество с ограниченной ответственностью «Финансовый искусственный интеллект». Исходный текст ведется в системе управления версиями, размещенной на территории Российской Федерации. Каждый выпуск фиксируется номером версии, снимком исходного текста и контрольной суммой архива экземпляра.
2. Устранение неисправностей
2.1. Обращения принимаются по адресам info@siberia-ai.ru и license@siberia-ai.ru. Обращение регистрируется, неисправность воспроизводится на тестовом стенде, исправление проходит автоматизированный набор проверок и выпускается исправительной версией с новой контрольной суммой.
2.2. Неисправности, влияющие на выполнение обязательных ограничений коммуникации, на учет согласий и отказов или на паспорта попыток информирования, устраняются в приоритетном порядке.
3. Совершенствование
3.1. Развитие ведется модулями: диалоговое ядро, обзвон и планирование касаний, входящая линия, текстовые каналы, контур согласий и отказов, речевая аналитика, справочный помощник, отчетные формы. Изменения проходят проверку совместимости сценариев и программного интерфейса. Новые возможности выпускаются очередными версиями, изменения фиксируются в перечне изменений.
3.2. Изменения схемы базы данных выпускаются миграциями, применяемыми при обновлении экземпляра. Откат к предыдущей версии предусмотрен обратными миграциями.
4. Персонал
4.1. Сопровождение обеспечивает разработчик программы. Численность персонала соответствует объему программы (161 записи в архиве, из них 159 файлов исходного текста на языке Python, суммарный объем 22 274 строка) и текущему числу эксплуатантов. При росте числа эксплуатантов предусмотрено выделение ролей разработчика и инженера технической поддержки.
4.2. Требования к персоналу: владение языком Python и средствами администрирования Linux, знание предметной области автоматизации коммуникаций и требований к взаимодействию с абонентами.
5. Данные эксплуатанта
5.1. Данные эксплуатанта (записи разговоров, отчеты, база знаний, сведения об абонентах) размещаются в его инфраструктуре и правообладателю не передаются. Сроки хранения записей управляются встроенными средствами.
«11» сентября 2026 г.
Контакты технической поддержки - в разделе «Компания и поддержка» на главной странице.