Telegram support workflow bot — every private message becomes a ticket in a group topic.
Anti-spam, Redis state, SLA alerts, auto-close, and shop admin API hooks.

Why · Features · Architecture · Quick start · Config · Commands · Monitoring

---

✨ Why

Commerce bots sell. Support bots keep the customers. This one bridges both.

DMs get buried, spam floods operators, conversation state disappears, and nobody tracks SLA. SMM Support Bot turns private messages into managed forum topics.

Pain	What the bot does
Support buried in DMs	Creates / reuses a topic per user
Spam floods operators	Anti-spam + throttling + rate limits
Lost ticket state	Redis-backed tickets, topic maps, limits
Missed replies	Background SLA jobs and escalation
Shop lives separately	Optional admin API hooks (SHOP_ADMIN_KEY)
Is the bot even up?	Healthcheck scripts and endpoint

Fits Telegram shops, internal helpdesks, and store-bot + support-bot pairs.

---

🧩 Features

🎫 Topics Dedicated forum topic per customer. Repeat messages land in the same thread.	🔁 DM ↔ group bridge Two-way relay: the user writes the bot, the operator answers in the topic.
🛡 Anti-spam Throttling, limits and filters so the support group stays usable.	📦 Redis state Tickets, topic map and runtime limits live in Redis, not process memory.
⏰ SLA automation Alert on silence, offer to close, auto-close idle tickets and send a CSAT survey.	🖼 Media Albums and attachments via album middleware — no more split media groups.
🩺 Health healthcheck.py / healthcheck.sh for uptime probes and cron.	🏪 Shop API Hooks into the commerce bot admin API so order context sits next to the ticket.
🌐 EN / RU Commands and UI in English and Russian. Language is switchable.	📡 Observability Structured logs, a Grafana dashboard in-repo, and a monitoring guide.

---

🏗 Architecture

flowchart LR
  U["User<br/>Telegram DM"] --> B["Support Bot"]
  B --> M["Anti-spam<br/>Throttling"]
  M --> H["Handlers<br/>private / group"]
  H --> R[("Redis<br/>tickets · topics · limits")]
  H --> S["SLA jobs<br/>alert · autoclose · CSAT"]
  H --> A["Shop Admin API"]
  H --> G["Support group<br/>forum topics"]

Loading

⚡ Quick start

git clone https://github.com/awhite0030/smm-support-bot.git
cd smm-support-bot
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python -m app

cp .env.example .env
docker compose up --build

1. Create a bot with @BotFather and copy BOT_TOKEN.
2. Create a supergroup with topics and add the bot as admin.
3. Set BOT_GROUP_ID (negative, like -100…) and BOT_DEV_ID.
4. Set BOT_EMOJI_ID for topic icons.

⚙ Configuration

Variable	Purpose
BOT_TOKEN	Token from BotFather
BOT_DEV_ID	Developer / admin Telegram ID
BOT_GROUP_ID	Support group ID with topics (-100…)
BOT_EMOJI_ID	Custom emoji ID for topics
REDIS_HOST / REDIS_PORT / REDIS_DB	Redis connection
REDIS_PASSWORD	Redis password (optional)
SHOP_API_BASE_URL	Shop admin API base URL
SHOP_ADMIN_KEY / ADMIN_API_KEY	Integration keys
SUPPORT_SLA_MINUTES	SLA alert threshold (default 30)
SUPPORT_AUTO_CLOSE_HOURS	Auto-close after idle hours (default 24)

BOT_GROUP_ID must be negative. Config validates this on startup.

⌨️ Commands

Private: /start /source /language Group: /ban /silent /information Admin: /newsletter

📊 Monitoring

See MONITORING.md. Healthcheck: python healthcheck.py. Grafana: grafana/dashboard.json.

📄 License

MIT © A. White