Описание плагина: «Telegram Chat Integration»

Этот плагин интегрирует вашу систему управления заказами СПРУТОН СТУДИО с Telegram-ботом. Вы можете напрямую общаться с клиентами через Telegram, получать уведомления о статусах, отслеживать новые сообщения и автоматически привязывать переписку к заказам и клиентам.

Возможности плагина:

1. Интеграция с Telegram API

• Настройка бота по токену
• Автоматическая установка вебхука
• Использование секретного токена для безопасности

// Пример:
$bot_token = 'YOUR_TELEGRAM_BOT_TOKEN';
$webhook_url = 'https://ваш-сайт.com/api/telegram_chat.php';
$secret_token = 'UNIQUE_SECRET_TOKEN';

2. Чат с клиентом в интерфейсе СПРУТОН СТУДИО

• Поле AJAX-запрос в карточке заказа
• Отправка и получение сообщений без перезагрузки страницы
• Поддержка истории (сохраняется в базе)
• Удобное поле ввода на 3 строки
• Кнопка «Отправить» под формой

const api_url = '/api/telegram_chat.php';
$.ajax({
    url: api_url,
    type: 'POST',
    data: JSON.stringify({ key: 'API_KEY', action: 'send_message', chat_id: 123456789, text: 'Привет!' }),
    dataType: 'json'
});

3. Получение и сохранение входящих сообщений

• Все сообщения от клиента сохраняются в таблицу app_telegram_chat_history
• Можно просматривать историю внутри СПРУТОН СТУДИО
• Сообщения помечаются как прочитанные при открытии формы заказа

4. Поддержка медиафайлов из Telegram

• Фото, документы, видео, аудио — всё сохраняется локально
• Путь: /uploads/telegram/chat_123456789_photo.jpg
• Поддерживаются:
  • photo
  • document
  • video
  • audio
• Вывод медиа в интерфейсе чата СПРУТОН СТУДИО

✅ Медиа можно просматривать прямо в модальном окне Sprut.on
➡️ Не используем глобальное модальное окно (как Fancybox)

5. Счётчик непрочитанных сообщений

• Новое поле в списке заказов показывает количество новых сообщений
• Работает через is_read в БД
• Обновляется динамически
• Стилизовано через CSS

if ($unread_count > 0) {
    echo "<span class=\"label label-danger\">{$unread_count} новых</span>";
}

6. Автоматическое определение Chat ID

• По order_id или client_id
• Чат привязывается к конкретному заказу
• Можно отправлять сообщение клиенту из СПРУТОН СТУДИО → оно попадает ему в Telegram

7. Уведомления о новых сообщениях менеджерам

• При закрытой форме заказа — менеджер получает уведомление о новом сообщении
• Через Telegram-бота (можно расширить до email или встроенного уведомления в СПРУТОН СТУДИО)

8. Возможность автоответчика

• Если клиент пишет напрямую боту, а не по существующему заказу
• Бот может предложить:
  • Посмотреть каталог
  • Связаться с менеджером
  • Получить информацию о доставке

9. API для внешних систем

• /api/telegram_chat.php — единая точка для всех действий
• Доступны методы:
  • get_chat_id — получить chat_id по заказу
  • get_history — получить историю чата
  • send_message — отправить сообщение

fetch('/api/telegram_chat.php', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        key: 'API_KEY',
        action: 'send_message',
        chat_id: 123456789,
        text: 'Здравствуйте!'
    })
})

10. Поддержка Fancybox / увеличение фото

• Все фото, присланные клиентом, можно увеличивать в модальном окне
• Поддерживается старая версия Fancybox
• Без конфликтов с уже открытым окном Sprut.on

11. Настройки через интерфейс Sprut.on

• Выбор сущностей: заказы и клиенты
• Привязка полей: chat_id, имя, телефон и т.д.
• Генерация API ключа
• Настройка вебхука одним кликом
• Тестирование бота (отправка тестового сообщения)

12. CSRF-защита

• Все AJAX-запросы защищены
• Токен генерируется при первом запуске
• Проверяется перед выполнением любого действия

if (!defined('DIR_FS_CATALOG')) die();
session_start();
if (!isset($_SESSION['telegram_csrf_token'])) {
    $_SESSION['telegram_csrf_token'] = bin2hex(random_bytes(32));
}

✅ Что можно сделать с этим плагином:

Функционал	Возможности
📬 Отправка сообщений клиенту	Из формы редактирования заказа
📥 Приём сообщений от клиента	Автоматически через вебхук
🖼 Получение фото, документов	Сохранение локально + вывод в чат
🔔 Уведомления менеджеру	При наличии новых сообщений
🧾 Счётчик непрочитанных	Показывается в списке заказов
💬 Автоответчик	Для новых клиентов без заказа
⚙️ Настройка через интерфейс	Выбор сущностей, полей, вебхук
🛠 API для внешних систем	/api/telegram_chat.php
📁 Логирование истории	app_telegram_chat_history
🔐 Защита запросов	CSRF, API ключ, secret_token

📌 Какие поля нужно добавить в СПРУТОН СТУДИО:

Сущность	Поле	Описание
Заказ	field_XXX	Chat ID клиента (берётся из Telegram)
Клиент	field_XXX	Chat ID (привязка к Telegram)
Клиент	field_XXX	Скидка / рейтинг (опционально)
Заказ	field_XXX	Адрес, сумма, статус и т.д.

📄 Что нужно указать в настройках:

Настройка	Описание
🤖 Bot Token	Токен Telegram-бота
🔐 API Key	Защищённый ключ для доступа к API
🔗 Webhook URL	Например:https://ваш-сайт.com/api/telegram_chat.php
🔒 Webhook Secret Token	Генерируется автоматически
📦 Order Entity	Сущность, где находятся заказы
👤 Client Entity	Сущность, где находятся клиенты
🧾 Status Field	Поле статуса заказа
💰 Amount Field	Поле суммы заказа
🕒 Date Field	Поле даты
📍 Address Field	Поле адреса доставки
📞 Chat ID Field	Поле в сущности клиента для хранения chat_id

🧪 Как использовать:

Откройте форму заказа → вы увидите чат с клиентом
Создайте Telegram-бота через @BotFather
Скопируйте токен в настройки плагина
Выберите сущности Клиент и Заказ
Привяжите поля , которые будут использоваться в сообщениях
Нажмите «Настроить вебхук»

🤖 Telegram чат для СПРУТОН СТУДИО

Описание:
Этот плагин позволяет интегрировать ваш сайт СПРУТОН СТУДИО с Telegram-ботом.
Теперь вы можете:

• Писать клиентам через Telegram
• Получать ответы от клиентов в СПРУТОН СТУДИО
• Просматривать историю чата в карточке заказа
• Присылать и получать фото, документы, видео
• Показывать счётчики непрочитанных сообщений
• Настроить всё через удобный интерфейс

🔧 Возможности

• ✅ Интеграция с Telegram API
• ✅ Отправка сообщений клиенту
• ✅ Приём сообщений через вебхук
• ✅ Чат в карточке заказа
• ✅ Поддержка медиа: фото, документы, видео
• ✅ Счётчик непрочитанных сообщений
• ✅ CSRF-токены и API-ключи для защиты
• ✅ Возможность автоответчика
• ✅ Логирование истории в базе данных
• ✅ Настройка через интерфейс СПРУТОН СТУДИО

🧩 Как работает?

• Клиент пишет боту в Telegram
• Сообщение записывается в СПРУТОН СТУДИО
• В карточке заказа вы видите его
• Можете ответить клиенту через форму в СПРУТОН СТУДИО
• Все данные хранятся в базе и синхронизированы

📁 Требования

• Spruton Studio v3.x+
• PHP 7.4+ с поддержкой cURL
• MySQLi
• Доступ к серверу для работы с вебхуками
• Папка /uploads/telegram/ с правами 777

📌 Версии и совместимость

• Совместим с СПРУТОН СТУДИО
• Работает через AJAX, не требует iframe
• Поддерживает Telegram API v6.0+
• Все настройки в интерфейсе СПРУТОН СТУДИО

📦 Как установить

1. Скопируйте папку telegram_chat в /plugins/
2. Перейдите в раздел настроек плагина
3. Введите токен бота
4. Выберите сущности: заказы и клиенты
5. Нажмите «Настроить вебхук»
6. Добавьте AJAX-поле в карточку заказа

📲 Как использовать

• Откройте заказ → внизу будет чат
• Напишите клиенту → он получит сообщение в Telegram
• Клиент ответит → вы получите его сообщение в СПРУТОН СТУДИО
• Все сообщения сохраняются в истории
• Медиа-файлы скачиваются и отображаются в чате

🧠 Технические детали

• Все данные шифруются через mysqli_real_escape_string()
• История хранится в app_telegram_chat_history
• Используется Fancybox для просмотра фото
• API-запросы проверяются через key и secret_token
• Поддержка csrf_token для защиты от XSS-атак

💬 Техподдержка

Если у вас возникнут вопросы, напишите нам: 📧 support@octobyte.ru