Telegram-боты

Telegram-боты

Типы ботов, информационная лента, QR-ссылки, RBAC и изоляция личных чатов

Telegram-боты WASH PRO CRM работают через PyOrchestrator и сервис pyorch-bridge. Управление — в Dashboard → Автоматизация → Telegram (требуется роль Administrator).

Архитектура

Пользователь Telegram (личный чат)
        ↓
   Telegram API (long polling)
        ↓
PyOrchestrator runtime (main.py из botTemplate / infoBotTemplate)
        ↓
Dynamic API  —  CRM endpoints (JWT service или public)
Компонент Назначение
pyorch-bridge Создание ботов, secrets, синхронизация шаблона, restart, QR/ссылка
botTemplate.ts Управляющий и сервисный бот (шаблон v3.1)
infoBotTemplate.ts Информационный бот (шаблон v1.9)
Dynamic API RBAC, лента /api/crm/info-messages, авторизация /api/users/telegram/{id}/auth

Типы ботов

Тип Назначение Доступ
Управление Полный операторский бот: мониторинг, справочники, команды постов CRM RBAC по Telegram ID
Сервисный Мониторинг и команды постов без создания/удаления объектов CRM RBAC
Информационный Публичное меню: новости, цены, занятость, акции Без Telegram ID — любой пользователь в личном чате

При создании бота выберите тип — пресет команд подставится автоматически.

Личные чаты и изоляция (v1.1.11)

Все боты работают только в личных сообщениях:

  • каждый пользователь видит только свой диалог с ботом;
  • ответы, меню и рассылки не попадают в групповые чаты;
  • если бота добавили в группу — бот не отвечает там и отправляет подсказку в личку: откройте бота по QR/ссылке и нажмите /start.

QR-код и ссылка (t.me/...) в таблице ботов ведут пользователя в личный чат.

Информационный бот

Меню

Кнопка Содержание
📰 Новости Последние 10 опубликованных новостей
💰 Цены Режимы и цены по выбранной мойке
🅿️ Занятость Свободные/занятые посты (v2.2: свободен только режим program_9 — внесение оплаты)
🎁 Акции Последние 10 акций

Контент — раздел «Информация»

Dashboard → Автоматизация → Информация (/info-messages):

Поле Рекомендация
Статус «Опубликовано» — иначе бот не покажет запись. «По расписанию» с прошедшей датой в таблице отображается как Опубликовано (v1.1.12)
Дата публикации Необязательна — подставляется автоматически при публикации
Скрыть после Оставьте пустым, если новость не должна исчезать. Не ставьте дату ≤ даты публикации
URL изображения Прямая ссылка на jpg/png/webp до 10 МБ; бот скачивает файл и отправляет в Telegram

Авторассылка

  1. Пользователь пишет боту /start в личном чате (регистрация подписчика).
  2. При публикации новости в CRM бот рассылает её подписчикам (~30 с).
  3. Новости, опубликованные до первого /start пользователя, в автоматическую рассылку не попадают — их можно открыть кнопкой 📰 Новости.

Изображения (v1.9)

Бот скачивает картинку по imageUrl и отправляет одним сообщением (фото + подпись, без дубля текста). Если фото недоступно — приходит текст новости. Требования к URL:

  • доступен из интернета (контейнер pyorch-runtime);
  • прямая ссылка на файл;
  • размер до 10 МБ.

Управляющий и сервисный бот

Создание

  1. PYORCHESTRATOR_ENABLED=true в .env, затем ./scripts/start.sh
  2. Dashboard → Telegram → Создать бота
  3. Токен от @BotFather, тип, команды
  4. Запуск (▶)
docker compose -f docker-compose.yml -f docker-compose.pyorchestrator.yml up -d --build pyorch-bridge

Принудительное обновление шаблона у всех ботов: POST /api/telegram-bots/bots/refresh.

Авторизация сотрудников

  1. Telegram ID — @userinfobot
  2. Dashboard → Пользователи → поле Telegram user_id
  3. Группа RBAC (Viewer / Operator / Administrator)

Бот вызывает GET /api/users/telegram/{telegramUserId}/auth. Посторонним — только «Частный бот» с их ID.

Permission В боте
view Мониторинг, отчёты
create Создание моек и постов
update Команды постов
delete Удаление объектов

Массовые действия (v1.1.10)

На странице Telegram — чекбоксы строк: экспорт CSV, запуск, остановка, удаление выбранных ботов.

Надёжность

Механизм Описание
Lock по токену Один процесс polling на токен
Offset / state Нет дублей после рестарта
Только private Игнор групп и каналов
Шаблон syncBotCode при старте bridge и перед restart
Username Регистрация @username при старте бота + чтение токена из PyOrchestrator для QR

Устранение неполадок

Симптом Действие
«PyOrchestrator недоступен» PYORCHESTRATOR_ENABLED=true, health curl localhost/api/telegram-bots/health
«Нет новостей» / пустая лента Статус Опубликовано; очистите «Скрыть после»; перезапустите бота
«Новости (2)» без текста/фото Обновите pyorch-bridge, перезапустите бота (v1.9+); проверьте URL картинки
Нет автоматической рассылки Пользователь должен нажать /start в личке до или после публикации; подождите ~30 с
Ссылка на бота недоступна Перезапустите бота; при необходимости сохраните токен в настройках бота
Бот отвечает в группе Ожидаемо отключено — используйте личный чат по QR
«Частный бот» для сотрудника Пользователи → Telegram user_id, статус active
Бот молчит ./scripts/fix-pyorch.sh, логи docker logs wash-pyorch-runtime

Подробнее: Устранение неполадок.

API bridge (admin JWT)

Метод Путь Описание
GET /api/telegram-bots/health Доступность PyOrchestrator
GET /api/telegram-bots/bots Список ботов
POST /api/telegram-bots/bots Создать
PUT /api/telegram-bots/bots/:id Обновить
DELETE /api/telegram-bots/bots/:id Удалить
POST /api/telegram-bots/bots/:id/start Запуск
POST /api/telegram-bots/bots/:id/stop Остановка
POST /api/telegram-bots/bots/stop-all Остановить все боты (v1.1.15)
GET /api/telegram-bots/bots/:id/link QR и ссылка t.me/...
POST /api/telegram-bots/bots/refresh Синхронизация шаблона + restart

См. также: Встроенные сервисы, Dashboard, MCP, Безопасность.