Документация Сибирь.Диалог 1.2.14

Описание функциональных характеристик программы для ЭВМ, информация, необходимая для установки, информация, необходимая для эксплуатации, и описание процессов, обеспечивающих поддержание жизненного цикла программного обеспечения. Документы размещены в открытом доступе, регистрация не требуется.

Подготовлено правообладателем - ООО «ФИИ», ИНН 5402076457. Редакция от 28 сентября 2026 года.

159файлов, 22 274 строки 1.2.14версия экземпляра

Функциональные характеристики Установка Эксплуатация Жизненный цикл

Описание функциональных характеристик

Программа для ЭВМ «Сибирь.Диалог» (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 байта. До установки сверить контрольную сумму:

sha256sum siberia-dialog-1.2.14.zip

Ожидаемое значение: ece57063f11f27e4e87fc50a68fc302d1f9fe7a28250d7894f411a1955a721ef.

2. Требования к окружению

Операционная система семейства Linux, работоспособность проверена на ОС Альт Сервер p11 и Astra Linux 1.8. Интерпретатор Python версии не ниже 3.12. СУБД PostgreSQL с расширением pgvector, хранилище Redis. Для голосового контура телефонная подсистема Asterisk и пакеты ffmpeg и ffprobe (в ОС Альт ffprobe устанавливается отдельным пакетом). Средства контейнеризации не обязательны.

3. Установка без телефонии для проверки работоспособности

Распаковать архив:

unzip siberia-dialog-1.2.14.zip -d dialog && cd dialog

Создать пустой файл README.md. Файл описания проекта pyproject.toml называет его в поле readme, а в архив включены только файлы исходного текста и файл описания проекта. Без README.md средство сборки прерывает установку ошибкой «OSError: Readme file does not exist: README.md».

touch README.md

Установить программу в отдельное окружение Python и активировать его:

uv venv --python 3.12 && uv pip install -e ".[dev,chat]" . .venv/bin/activate

Задать три обязательных значения и запустить сервер программного интерфейса. Значения ниже проверочные, для эксплуатации задаются свои. Для проверки без СУБД указана база SQLite, таблицы в ней программа создает сама:

export ARI_PASSWORD='check-ari-pass-12' export SECRET_KEY='check-secret-key-0123456789abcdef' export API_ADMIN_KEY='check-admin-key-0123456789' export DATABASE_URL='sqlite+aiosqlite:///./dialog.db' uvicorn siberia_dialog.api.app:app --port 8000

В журнале появляется строка «Application startup complete.». Проверка из другого окна:

curl -s http://127.0.0.1:8000/health {"status":"ok"}

Проверка сценария и диалог в консоли. Сценарии диалогов в поставку не входят, их готовит эксплуатант и размещает в каталоге scenarios. Для проверки установки достаточно минимального сценария из двух состояний, его создают так:

mkdir -p scenarios cat > scenarios/demo_info.yaml <<'EOF' id: demo_info vertical: generic legal_basis: service start: hello slots: [full_name] states: hello: say: "Здравствуйте, {full_name}. Это тестовое сообщение. Вам удобно говорить?" expect: intents: [yes, no] on: yes: bye no: bye _silence: bye _unknown: bye bye: say: "Спасибо, до свидания." end: informed intents: yes: ["да", "удобно"] no: ["нет", "неудобно"] EOF python -m siberia_dialog.cli validate scenarios/demo_info.yaml python -m siberia_dialog.cli chat scenarios/demo_info.yaml full_name="Иван Петрович"

Команда 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.

export DATABASE_URL='postgresql+asyncpg://dialog:<пароль>@localhost:5432/dialog' export REDIS_URL='redis://:<пароль>@localhost:6379/0'

Применить миграции схемы базы данных. Файла alembic.ini в архиве нет, его создают в каталоге распаковки:

cat > alembic.ini <<'EOF' [alembic] script_location = %(here)s/src/siberia_dialog/db/migrations [loggers] keys = root [handlers] keys = console [formatters] keys = generic [logger_root] level = INFO handlers = console [handler_console] class = StreamHandler args = (sys.stderr,) formatter = generic [formatter_generic] format = %(levelname)s %(message)s EOF alembic -c alembic.ini upgrade head alembic -c alembic.ini current

Последняя команда отвечает «0012 (head)». Затем запустить службы, каждую отдельным процессом (подробно в разделе эксплуатации, п. 6.3):

uvicorn siberia_dialog.api.app:app --host 0.0.0.0 --port 8000 arq siberia_dialog.campaigns.worker.WorkerSettings python -m siberia_dialog.voice.server

Голосовому обработчику нужна телефонная подсистема 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):

OSError: Readme file does not exist: README.md

Дополнения, указываемые в квадратных скобках при установке: voice для голосового обработчика, chat для адаптеров Telegram и VK, rag для векторного поиска по базе знаний, dev для средств разработки.

Обязательные переменные окружения. Без них не запускается ни один процесс программы:

Переменная	Требование	Назначение
`ARI_PASSWORD`	Не короче 12 знаков	Пароль пользователя ARI в Asterisk
`SECRET_KEY`	Не короче 32 знаков	Шифрование токенов заказчиков, подпись сеансов веб-виджета
`API_ADMIN_KEY`	Не короче 24 знаков	Ключ администратора для заголовка X-API-Key

Ответ программы, если они не заданы (код возврата 1):

pydantic_core._pydantic_core.ValidationError: 3 validation errors for Settings ari_password Field required [type=missing, input_value={}, input_type=dict] secret_key Field required [type=missing, input_value={}, input_type=dict] api_admin_key Field required [type=missing, input_value={}, input_type=dict]

Основные необязательные переменные и значения по умолчанию:

Переменная	По умолчанию	Назначение
`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	Каталог сценариев <scenario_id>.yaml
`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 не проверялись:

$ alembic -c alembic.ini upgrade head $ alembic -c alembic.ini current 0012 (head)

6.3. Запуск

Порядок: СУБД и Redis, миграции, сервер программного интерфейса, обработчик кампаний, голосовой обработчик. Адрес и порт сервера выбирает эксплуатант, 8000 в примерах условный. Команды выполняются в окружении, активированном после установки командой . .venv/bin/activate.

Сервер программного интерфейса.

uvicorn siberia_dialog.api.app:app --host 0.0.0.0 --port 8000

При запуске программа проверяет базу часовых поясов (без нее запуск прерывается), языковые пакеты tesseract (при их отсутствии пишет предупреждение и продолжает работу) и для SQLite создает таблицы. Признак успешного запуска в журнале (в прогоне tesseract не был установлен, отсюда предупреждение):

INFO: Started server process [17348] INFO: Waiting for application startup. распознавание документов недоступно: tesseract не запускается: [WinError 2] The system cannot find the file specified INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:18770 (Press CTRL+C to quit)

Проверка работоспособности:

$ curl -s http://127.0.0.1:8000/health {"status":"ok"} $ curl -s http://127.0.0.1:8000/about {"product":"Siberia.Dialog","version":"1.2.14","rightsholder":{"name":"ООО «Финансовый искусственный интеллект» (Siberia AI)","inn":"5402076457","kpp":"547301001","ogrn":"1235400001870","address":"630090, г. Новосибирск, ул. Демакова, д. 23/5","site":"https://siberia-ai.ru","support":"support@siberia-ai.ru, +7 (383) 288-82-82"},"license":{"licensee":"демонстрационный режим","inn":"","valid_until":"","limits":{"voice_lines":2,"chat_channels":1,"documents":5},"status":"demo"},"third_party":"см. LICENSE-THIRD-PARTY.md в составе дистрибутива","registry_class":"05.09 Средства управления диалоговыми роботами","usage":{"voice_lines_in_use":0,"voice_lines_limit":2,"chat_channels_in_use":[],"chat_channels_limit":1}}

Поле license.status принимает значения valid, expired, invalid и demo. Без файла лицензии, с недействительной подписью и по истечении срока действуют демонстрационные ограничения: две голосовые линии, один чат-канал, пять страниц документа на запрос.

Обработчик кампаний.

arq siberia_dialog.campaigns.worker.WorkerSettings

Расписание: набор номеров каждые 10 секунд, шаги лестницы касаний каждую минуту, импорт баз в 03:00, удаление данных по срокам хранения в 04:00, повторная постановка застрявших пакетов аналитики каждые 5 минут. Без ffmpeg обработчик пишет предупреждение «речевая аналитика недоступна» и продолжает обзвон. Запуск с Redis в прогоне не выполнялся. Без Redis обработчик делает пять попыток подключения и завершается с кодом 1:

01:58:26: redis connection error 127.0.0.1:16379 TimeoutError Timeout connecting to server, 5 retries remaining... ... 01:58:34: redis connection error 127.0.0.1:16379 TimeoutError Timeout connecting to server, 1 retries remaining...

Проверка живости (обработчик обновляет отметку в Redis раз в 30 секунд). Код 0 означает, что обработчик жив, код 1 означает, что нет, причина печатается в поток ошибок:

$ REDIS_URL=redis://127.0.0.1:16379/0 python -m siberia_dialog.healthcheck worker проверка живости worker: ConnectionError('Error 10061 connecting to 127.0.0.1:16379. No connection could be made because the target machine actively refused it.')

Голосовой обработчик.

python -m siberia_dialog.voice.server

Признак запуска в журнале:

2026-09-28 01:58:01,494 voice INFO AudioSocket on 127.0.0.1:19092

Эта строка и проверка живости подтверждают только прием AudioSocket. Подключение к Asterisk программа в журнал не пишет: при недоступном ARI она повторяет подключение каждые 2 секунды без сообщений. В прогоне Asterisk не было, а проверка живости ответила кодом 0:

$ AUDIOSOCKET_PORT=19092 python -m siberia_dialog.healthcheck voice $ echo $? 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":[{"type":"less_than_equal","loc":["body","concurrency"],"msg":"Input should be less than or equal to 200","input":500,"ctx":{"le":200}}]}

Код	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` (файл `<scenario_id>.yaml` в каталоге сценариев), `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:

$ python -m siberia_dialog.cli usage: siberia-dialog [-h] {chat,validate,warmup,analytics-rules,rotate-secrets,passport,smoke} ... siberia-dialog: error: the following arguments are required: cmd

Команда	Аргументы	Что делает	Ответ программы	Код возврата
`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, обращается к службе синтеза	`<id>: N фраз, синтезировано новых: K`. При пустом YANDEX_API_KEY в прогоне: `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. Пример диалога (тестовый сценарий эксплуатанта, ответ абонента подан через канал ввода, поэтому само слово «да» в выводе не отображается):

$ printf 'да\n' | python -m siberia_dialog.cli chat scenarios/demo_info.yaml full_name="Иван Петрович" 🤖 Здравствуйте, Иван Петрович. Это тестовое сообщение. Вам удобно говорить? Да | Нет 👤 🤖 Спасибо, до свидания. — конец, исход: informed

6.6. Завершение

Новые вызовы набирает только обработчик кампаний и только по голосовым кампаниям в статусе running. Шаги лестницы касаний выполняются только у кампаний в статусе running. Перед плановой остановкой приостановить кампании (POST /campaigns/{campaign_id}/pause), дождаться, пока в ответе GET /campaigns/{campaign_id} не останется контактов calling, затем остановить голосовой обработчик, обработчик кампаний и сервер программного интерфейса.

Процессы программы завершаются по сигналу SIGINT (Ctrl+C) или SIGTERM, в том числе когда сигнал посылает средство, которым запущены службы. Сервер программного интерфейса при остановке закрывает подключение к очереди и общий HTTP-клиент чат-каналов. Журнал корректной остановки (прогон 28.09.2026, остановка вызвана тем же обработчиком, что у сигнала SIGTERM):

INFO: Shutting down INFO: Waiting for application shutdown. INFO: Application shutdown complete. INFO: Finished server process [6832]

Обработчик кампаний при остановке закрывает 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 г.

Контакты технической поддержки - в разделе «Компания и поддержка» на главной странице.