Telegram setup

This guide walks you through setting up the Telegram-specific components required for the Support Bot: creating your bot, setting up the operator group with Forum/Topics, and configuring permissions.

Create your bot with BotFather

BotFather is Telegram’s official bot for creating and managing bots.

Start a chat with BotFather

Open Telegram and search for @BotFather, or click the link to open a chat.Click Start or send /start to begin.

Create a new bot

Send the /newbot command to BotFather.

/newbot

BotFather will ask you for two pieces of information:

Bot name - The display name for your bot (e.g., “My Support Bot”)
Bot username - A unique username ending in “bot” (e.g., “my_support_bot”)

Save your bot token

After creation, BotFather will send you a message containing your bot token:

Done! Congratulations on your new bot.
You will find it at t.me/your_bot_username
Use this token to access the HTTP API:
123456789:ABCDEFghijklmnopQRSTUVwxyz123456789

Keep this token secret! Anyone with your token can control your bot. Never commit it to version control or share it publicly.

Copy the token and add it to your .env file:

.env

BOT_TOKEN=123456789:ABCDEFghijklmnopQRSTUVwxyz123456789

Configure bot settings (optional)

You can customize your bot’s appearance:

/setdescription - Set a description shown in the bot’s profile
/setabouttext - Set the “About” text
/setuserpic - Upload a profile picture
/setcommands - Define bot commands for the menu

Create and configure the operator group

The operator group is where your support team will handle user conversations. Each user gets their own forum topic in this group.

Create a supergroup

The bot requires a supergroup (not a regular group) with Forum/Topics enabled.

In Telegram, create a new group
Add at least one member (you can remove them later)
Go to group settings → Group Type → Convert to Supergroup

If you already have a supergroup, you can use it. Skip to the next step to enable Topics.

Enable Forum/Topics

Topics (also called Forums) allow the bot to create separate conversation threads for each user.

Open the supergroup
Tap the group name at the top to open settings
Go to Group Type or Permissions
Enable Topics (the toggle should turn blue/green)

The bot will not work without Topics enabled. Forum topics are essential for organizing user conversations.

Add your bot to the group

Open the supergroup
Tap the group name → Add Members
Search for your bot by username (e.g., @my_support_bot)
Add the bot to the group

Promote bot to administrator

The bot needs administrator permissions to manage topics and send messages.

Open the supergroup settings
Go to Administrators → tap on your bot
Enable the following permissions:
- Manage Topics (required) - Create and manage forum topics
- Delete Messages (optional) - Clean up topics
- Pin Messages (optional) - Pin important messages in topics

Manage Topics permission is critical. Without it, the bot cannot create topics for new users and will fail silently.

The required permissions are enforced by checking in main.py:39 when initializing the TopicManager:

support_bot/main.py

topics = TopicManager(db=db, operator_group_id=config.operator_group_id)

Get the group ID

You need the supergroup’s chat ID for the OPERATOR_GROUP_ID configuration variable.

Add a bot to get the ID

The easiest way to get the group ID is using a helper bot.

Method 1: Using @RawDataBot
Method 2: Using @getidsbot
Method 3: Using your bot

Add @RawDataBot to your operator group
The bot will immediately send a message with the group information
Look for "chat": {"id": -1001234567890}
Copy the negative number (including the minus sign)

Example response:

{
  "chat": {
    "id": -1001234567890,
    "type": "supergroup",
    "title": "Support Operators"
  }
}

Add @getidsbot to your operator group
The bot will send a message with IDs
Look for the group ID (starts with -100)
Copy the ID

Temporarily add a debug handler to your bot:

@router.message()
async def debug_handler(message: Message):
    print(f"Chat ID: {message.chat.id}")

Send a message to the group
Check your bot’s console output for the chat ID
Remove the debug handler after getting the ID

Add to configuration

Add the group ID to your .env file:

.env

OPERATOR_GROUP_ID=-1001234567890

The ID will always be a negative number starting with -100 for supergroups. If you see a positive number or one without -100 prefix, you might have a regular group instead of a supergroup.

Remove helper bots (optional)

After getting the group ID, you can remove the helper bot from your operator group if desired.

Test your setup

Verify that everything is configured correctly before running the bot.

Verify group settings

Confirm your operator group has:

Verify configuration file

Check your .env file has all required values:

.env

BOT_TOKEN=123456789:ABCDEFghijklmnopQRSTUVwxyz123456789
OPERATOR_GROUP_ID=-1001234567890
DB_PATH=./support_bot.sqlite3
LOG_LEVEL=INFO
LOG_MESSAGES=1

Start the bot

Run the bot to test the configuration:

python -m support_bot

You should see:

INFO:support_bot:Started as @your_bot_username (id=123456789)

Send a test message

Open a private chat with your bot
Send /start or any message
Check your operator group - a new topic should be created
The user’s message should appear in that topic

The topic title will be the user’s name or username. All messages from that user will appear in this topic.

Test operator replies

In the operator group, open the user’s topic
Reply to the user’s message in the topic
Check your private chat with the bot - your reply should appear there

The bot mirrors conversations bidirectionally. Users see operator replies as if they’re chatting directly with the bot.

Troubleshooting

Bot doesn't respond to messages

Possible causes:

Bot token is incorrect or invalid
Bot is not running (check console for errors)
Bot was blocked or stopped by the user

Solutions:

Verify BOT_TOKEN in .env matches the token from @BotFather
Check the bot process is running with LOG_LEVEL=DEBUG
Try sending /start to restart the conversation

Topics are not being created

Possible causes:

Topics/Forum is not enabled on the group
Bot doesn’t have “Manage Topics” permission
The group is not a supergroup
Wrong OPERATOR_GROUP_ID in configuration

Solutions:

Verify Topics are enabled in group settings
Check bot has administrator rights with “Manage Topics” permission
Ensure the group is converted to a supergroup
Verify OPERATOR_GROUP_ID matches your group’s ID

Operator replies don't reach users

Possible causes:

Replying outside of a topic (replies must be in the user’s topic)
The original message was not mirrored by the bot
User blocked the bot

Solutions:

Always reply within the user’s specific topic
Check that user messages are appearing in topics first
Verify the bot can send messages to the user

Can't get the group ID

Possible causes:

Helper bot doesn’t have permission to send messages
Using a regular group instead of a supergroup

Solutions:

Ensure the helper bot can send messages in the group
Convert your group to a supergroup first
Try Method 3 (using your own bot) from the “Get the group ID” section

Permission denied errors

Error in logs:

aiogram.exceptions.TelegramForbiddenError: Forbidden: bot is not a member of the supergroup

aiogram.exceptions.TelegramBadRequest: Bad Request: not enough rights to manage topics

Solutions:

Ensure bot is added to the operator group
Promote bot to administrator
Grant “Manage Topics” permission explicitly

Requirements summary

For quick reference, here are the Telegram requirements from the source code:

Python Requirements

From README.md:18-24:

Python 3.10+ (recommended 3.11+)
Bot permissions:
- Manage Topics
- Permission to send messages

Group Requirements

Supergroup (not regular group)
Forum/Topics enabled
Bot added as administrator
Correct group ID in configuration

As stated in README.md:53-55: “The bot works only with supergroups that have Topics (Forum) enabled. If topics are not being created, check that the bot has the Manage Topics permission.”

Next steps

After completing the Telegram setup:

Get Started

Setup & Configuration

Core Concepts

Guides

API Reference

Create your bot with BotFather

Create and configure the operator group

Get the group ID

Test your setup

Troubleshooting

Requirements summary

Python Requirements

Group Requirements

Next steps

Build docs developers (and LLMs) love

Get Started

Setup & Configuration

Core Concepts

Guides

API Reference

​Create your bot with BotFather

​Create and configure the operator group

​Get the group ID

​Test your setup

​Troubleshooting

​Requirements summary

Python Requirements

Group Requirements

​Next steps

Build docs developers (and LLMs) love

Create your bot with BotFather

Create and configure the operator group

Get the group ID

Test your setup

Troubleshooting

Requirements summary

Next steps