Skip to main content
Get your Telegram support bot operational in just a few steps. This guide will take you from zero to a fully functional support system using forum topics.
1

Check prerequisites

Before you begin, ensure you have:
  • Python 3.10 or higher installed (Python 3.11+ recommended)
  • A Telegram account
  • Basic familiarity with terminal commands
Verify your Python version:
python --version
2

Create your bot with BotFather

Open Telegram and start a chat with @BotFather:
  1. Send /newbot to BotFather
  2. Follow the prompts to choose a name and username for your bot
  3. Copy the bot token (format: 123456:ABCDEF_your_token_here)
Keep your bot token secure. Anyone with this token can control your bot.
3

Create an operator group

Your operators need a dedicated supergroup with forum topics enabled:
  1. Create a new supergroup in Telegram
  2. Go to Group Settings → Group Type → Enable Topics
  3. Add your bot to the group as an administrator
  4. Grant the bot these permissions:
    • Manage Topics (required)
    • Send Messages
  5. Get the group’s chat ID (usually starts with -100...)
The bot will not work without the “Manage Topics” permission. Make sure this is enabled.
To get your group’s chat ID, forward a message from the group to @userinfobot or use a bot like @RawDataBot.
4

Clone and set up the project

Clone the repository and create a virtual environment:
git clone https://github.com/apkuzmin/telegram-support-bot.git
cd telegram-support-bot
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
5

Install dependencies

The bot requires three core packages:
pip install -r requirements.txt
This installs:
requirements.txt
aiogram==3.13.1
aiosqlite==0.20.0
python-dotenv==1.0.1
  • aiogram - Modern Telegram Bot API framework
  • aiosqlite - Async SQLite database for message routing
  • python-dotenv - Environment variable management
6

Configure environment variables

Create a .env file in the project root:
cp .env.example .env
Edit .env with your actual values:
.env
BOT_TOKEN=123456:ABCDEF_your_token_here
# Supergroup chat id (usually starts with -100...)
OPERATOR_GROUP_ID=-1001234567890
# Path to SQLite DB file
DB_PATH=./support_bot.sqlite3
LOG_LEVEL=INFO
# Store messages history in SQLite (set to 0 to disable)
LOG_MESSAGES=1
​
BOT_TOKEN
string
required
Your bot token from BotFather
​
OPERATOR_GROUP_ID
integer
required
The supergroup chat ID where operators will work (must start with -100)
​
DB_PATH
string
default:"./support_bot.sqlite3"
Path to the SQLite database file for routing and reply mapping
​
LOG_LEVEL
string
default:"INFO"
Logging verbosity level (DEBUG, INFO, WARNING, ERROR)
​
LOG_MESSAGES
boolean
default:"1"
Set to 1 to store message history in SQLite, or 0 to disable history logging
7

Run the bot

Start the bot with:
python -m support_bot
You should see output similar to:
INFO:support_bot:Started as @your_bot_username (id=123456789)
The bot is now running and ready to handle support requests!
8

Test with a message

Verify everything is working:
  1. Open a private chat with your bot in Telegram
  2. Send a test message: “Hello, I need support!”
  3. Check your operator group - a new forum topic should appear with your user’s name
  4. The topic will contain your message
  5. Reply to the message in the topic
  6. Check your private chat with the bot - you should receive the operator’s reply
The bot automatically creates one forum topic per user. All future messages from that user will appear in their dedicated topic.

​
What happens under the hood

When a user sends a message to your bot:
  1. The bot receives the message in the private chat (handled in support_bot/handlers/user.py)
  2. The TopicManager checks if a forum topic exists for this user
  3. If no topic exists, one is created automatically with the user’s name
  4. The message is mirrored to the operator group topic
  5. SQLite stores the routing information and reply mapping
When an operator replies in the topic:
  1. The bot detects the reply in the operator group (handled in support_bot/handlers/operator.py)
  2. It looks up which user the topic belongs to
  3. The reply is sent back to the user’s private chat
  4. The reply mapping is stored for future reference

​
What’s next?

Configuration

Learn about all configuration options and advanced settings

Architecture

Understand how the bot routes messages and manages topics

Deployment

Deploy your bot to production with systemd or Docker

Troubleshooting

Common issues and how to resolve them

Build docs developers (and LLMs) love

Get started for freeTalk to us