telegram-support-bot

KO | EN

gitlite — search

#typescript #machine-learning #linux #nodejs #windows #awesome #cli #kubernetes #awesome-list #vue #security #ios #openai #open-source

telegram-support-bot

(★ 18)

Простой Telegram-бот для поддержки пользователей.

telegram-support-bot Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Telegram Support Bot

> Этот проект представляет собой Telegram-бота для организации простейшей, но удобной системы поддержки.
> Бот принимает сообщения пользователей и пересылает их в чат поддержки.
> Операторы отвечают на сообщения прямо в общем чате, используя функцию Reply, а бот автоматически перенаправляет ответ пользователю.

*Это мой первый публичный репозиторий, поэтому не ругайте строго ✨*

---

---

## 🚀 Возможности

* **🔄 Двусторонняя связь:** Пересылка сообщений от пользователей в чат поддержки и обратно. Поддерживаются текст, фото, видео, аудио, документы и голосовые сообщения.
* **🔘 Интерактивное управление:** Закрытие/открытие тикетов и блокировка пользователей в один клик через инлайн-кнопки прямо под сообщениями.
* **💬 Шаблоны быстрых ответов:** Операторы могут отправлять заранее заготовленные ответы одной кнопкой — без необходимости печатать одно и то же каждый раз.
* **⭐ Оценка поддержки:** После закрытия тикета пользователь получает предложение оценить качество поддержки по шкале 1–5. Результаты сохраняются и видны в статистике.
* **📊 Статистика `/stats`:** Количество тикетов (всего, открытых, за сегодня, за неделю), заблокированных пользователей и средний рейтинг.
* **⚡ Защита от спама:** Rate limiting — не более 5 сообщений в минуту от одного пользователя (настраивается в `bot.py`).
* **🕒 Режим работы (Автоответчик):** Возможность задать рабочие часы поддержки. Если пользователь напишет в нерабочее время, бот автоматически предупредит его о задержке с ответом.
* **📁 Гибкая система топиков:**
  * **Режим "Отдельный топик для каждого"** — автоматическое создание персонального топика для каждого пользователя с визуальным отображением статуса (🟢 открыт / 🔴 закрыт).
  * **Режим "Общий топик"** — все тикеты собираются в одном топике (классический режим).
* **⚙️ Админ-панель:** Администраторы могут менять тексты приветствия, справки, настраивать автоответчик, переключать режим топиков и управлять шаблонами ответов прямо через бота.
* **💾 Асинхронная БД:** Используется `aiosqlite` — запросы к базе данных не блокируют event loop даже при высокой нагрузке.

## 📋 Требования

* Python 3.10+
* Токен Telegram бота
* ID чата (группы), где будут находиться операторы поддержки
* **Для режима "Общий топик"**: ID топика (`SUPPORT_TOPIC_ID`)
* **Для режима "Отдельный топик для каждого"**: Чат должен быть супергруппой с включенными темами, бот должен быть администратором с правами `Управление темами`
* ID администраторов (для доступа к настройкам)

## 🛠 Установка и запуск

### 1. Клонирование репозитория

```bash
git clone https://github.com/gniloeapple/telegram-support-bot.git
cd telegram-support-bot

cp .env.example .env
nano .env
```

**Пример заполнения `.env`:**

```ini
TELEGRAM_TOKEN=123456789:AAH...             # Токен от BotFather
SUPPORT_CHAT_ID=-1001234567890              # ID группы поддержки (начинается с -100)
SUPPORT_TOPIC_ID=12345                      # Опционально: ID топика (для режима "Общий топик")
ADMINS=123456789,987654321                  # ID администраторов через запятую (без пробелов)
```

**Где взять данные:**

* **TELEGRAM_TOKEN**: Напишите [@BotFather](https://t.me/BotFather), создайте бота и скопируйте выданный токен.
* **SUPPORT_CHAT_ID**: Создайте группу в Telegram, добавьте туда бота и назначьте его администратором. Перешлите любое сообщение из группы боту `@userinfobot`, чтобы узнать ID группы. Убедитесь, что ID начинается с `-100`.
* **SUPPORT_TOPIC_ID**: Нужен только для режима "Общий топик". Включите темы в группе и перешлите сообщение из нужной темы в `@userinfobot`, чтобы узнать `message_thread_id`.
* **ADMINS**: Ваш цифровой ID в Telegram.

### 2. Установка зависимостей

```bash
python -m venv venv
# Активация для Windows:
venv\Scripts\activate
# Активация для Linux/macOS:
source venv/bin/activate

pip install -r requirements.txt
```

### 3. Запуск бота

```bash
python bot.py
```

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

### Для пользователей

1. Запускают бота командой `/start`.
2. Пишут сообщение (поддерживаются текст, фото, видео, документы и голосовые сообщения).
3. Бот пересылает обращение в поддержку. Если сейчас нерабочее время (и оно настроено), пользователь получит соответствующее предупреждение.
4. После закрытия тикета оператором пользователь получает предложение оценить поддержку по шкале 1–5.

### Для операторов поддержки

1. **Ответ на сообщение:** Сделайте **Reply (Ответить)** на пересланное сообщение в группе. Бот доставит ответ в личные сообщения пользователя.
2. **Управление тикетом:** Под каждым сообщением есть инлайн-кнопки **«🔒 Закрыть тикет» / «🔓 Открыть тикет»** и **«❌ Заблокировать» / «✅ Разблокировать»**.
3. **Шаблоны ответов:** Кнопка **«💬 Шаблоны ответов»** под тикетом открывает список заготовленных ответов — выберите нужный, и он сразу уйдёт пользователю.
4. Команды в чате поддержки:
   * `/open_tickets` — список всех открытых обращений.
   * `/stats` — статистика: тикеты, рейтинг, заблокированные пользователи.

## 🤖 Меню администратора

Отправьте боту в личные сообщения команду `/admin` (доступно только пользователям из списка `ADMINS` в `.env`).

В меню доступно:

* **✏️ Изменить приветствие** — задать текст для `/start`.
* **📝 Изменить информацию** — задать текст для `/help`.
* **🕒 Режим работы** — включение/выключение автоответчика, установка расписания (например, `10:00-18:00`) и текста автоответа.
* **🔄 Режим: [Текущий режим]** — переключение логики топиков (отдельный для каждого / общий).
* **💬 Шаблоны ответов** — добавление и удаление шаблонов быстрых ответов для операторов.
* **❌ Закрыть** — удаляет сообщение с меню.

## 📞 Поддержка проекта

Если вы нашли баг или у вас есть идеи по улучшению — смело создавайте **Issue** или **Pull Request**!

---

⭐️ Если этот проект оказался полезным, поставьте звезду на GitHub!

telegram-support-bot

telegram-support-bot Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

telegram-support-bot

telegram-support-bot Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README