telegram-ugc-bot

telegram-ugc-bot is a self-hosted Telegram bot for running UGC (User Generated Content) campaigns inside a community. Admins manage campaign lifecycle; users submit content via an inline keyboard — no external broker or web dashboard required.

---

Features

• Campaign management — Create, update, and delete campaigns with name, description, and start/end dates
• User submissions — Members submit content to active campaigns; duplicate submissions blocked per campaign
• Admin review — Admins see all submissions grouped by campaign
• Excel export — Export submissions per campaign (or all) as .xlsx files
• Group notifications — New submissions forwarded to a configured Telegram group topic
• Role-based access — Admin-only actions hidden from regular users
• Async SQLite — Lightweight persistent storage via SQLAlchemy + aiosqlite
• Rate limiting — Built-in AIORateLimiter from python-telegram-bot
• Hot config reload — Admins can reload config.json without restarting

---

How It Compares

Feature	telegram-ugc-bot	Chainfuel PRO	TeleGroupBot
Self-hosted	✅	❌ SaaS	❌ SaaS
Campaign lifecycle	✅	✅	⚠ Limited
Excel export	✅	⚠ CSV only	❌
Custom campaign logic	✅ Full control	❌	❌
No broker / Redis	✅	❌	❌
Open source	✅ MIT	❌	❌

---

Architecture

main.py                     # Single-file bot — all logic here
config.json                 # Runtime config (token, admin list, group IDs)
<BOT_NAME>.db               # SQLite database (auto-created on first run)
<BOT_NAME>.log              # Log file (auto-created)

Stack:

• python-telegram-bot 22.6 — Telegram Bot API wrapper
• SQLAlchemy 2.0 async + aiosqlite — async SQLite ORM
• openpyxl — Excel export
• python-dateutil — flexible date parsing for campaign periods

---

Installation

git clone https://github.com/sungurerdim/telegram-ugc-bot.git
cd telegram-ugc-bot
pip install -r requirements.txt

---

Configuration

Copy the template and fill in your values:

{
    "TG_BOT_NAME": "my_campaign_bot",
    "TG_BOT_TOKEN": "123456:ABC-your-token-here",
    "GROUP_ID": -100123456789,
    "TOPIC_ID": 42,
    "ENV": "prod",
    "ADMINS": [
        "your_telegram_handle"
    ]
}

Field	Description
TG_BOT_NAME	Used as the filename prefix for .db and .log
TG_BOT_TOKEN	Get from @BotFather
GROUP_ID	Telegram group ID (negative integer) for submission notifications
TOPIC_ID	Topic/thread ID within the group (set null if not using topics)
ENV	dev = INFO logging, prod = ERROR logging only
ADMINS	List of Telegram usernames (without @) with admin access

Security note: Username-based allowlisting carries a risk — Telegram usernames can be changed and re-registered. For higher-security deployments, consider migrating ADMINS to numeric user IDs.

---

Running

python main.py

The bot creates the SQLite database and starts polling on first run.

---

Bot Commands

Command	Description
/start	Show main menu
/menu	Show main menu
/help	Show main menu

All actions use inline keyboard buttons — no slash commands beyond the menu entry points.

---

Admin Actions

Action	Description
Create Campaign	Name + description + duration in days
Update Campaign	Change name, description, start or end date
Delete Campaign	Exports submissions first, then deletes
All Submissions	View all submissions grouped by campaign
Export Submissions	Download .xlsx file per campaign or all
Reload Configuration	Hot-reload config.json without restart

---

License

MIT