Telegram Groups Indexer Bot

Telegram Groups Indexer Bot (TGroupsIndexerBot) is a Telegram bot for organizing groups into browsable categories and making them easier to discover.

The project was originally created for the former Sapienza Students organization and is now used by Sapienza Students Network to help university students find Telegram groups related to degree programmes, courses, and subjects.

Features

Browse indexed groups through a hierarchy of categories and subcategories
Add the bot to a group and request indexing in an appropriate category
Move or remove indexed groups, subject to the requesting user's permissions
Create, rename, hide, show, and delete categories through the bot interface
Add reusable custom links to categories through the bot-administration interface
Keep group metadata, administrators, ownership, invite links, and permissions synchronized
Hide groups from indexing when moderation is required
Manage bot administrators and per-user restrictions
Display user and group status information
Use localized interfaces in English and Italian
Store persistent data in PostgreSQL
Log exceptions and administrative actions to optional Telegram chats

Demo

A live instance of Telegram Groups Indexer Bot is available at @SapienzaStudentsBot

You can use it to explore the bot's interface and see how categories and subcategories make Telegram groups for degree programmes, courses, and individual subjects easier to discover. The guided menus let students browse the available directories, find a relevant community, and join it without having to search through scattered invite links.

The demo also shows the group-indexing workflow from an administrator's point of view: after adding the bot to a group and granting the required permissions, an authorized administrator can choose the most appropriate category and submit or move the group directly through the bot interface.

The public instance is managed by Sapienza Students Network. Its categories, moderation policies, available features, and configuration may differ from those of a self-hosted instance.

Project status

The core indexing workflow is implemented: authorized group administrators can add the bot to a group, grant the required permissions, and index or move the group through the category browser.

The project is actively usable, but APIs, database migrations, commands, and deployment details may still evolve. Review the commit history before upgrading a production instance.

Repository update notifications are published on @TGroupsIndexerBotGit.

Requirements

Python 3.11
PostgreSQL
A Telegram bot token created with @BotFather
pipenv

The main Python dependencies are declared in Pipfile and locked in Pipfile.lock, including:

python-telegram-bot with job queue support
psycopg2-binary
pytz

Create a Telegram bot

Open @BotFather
Send /newbot
Choose the bot's display name and username
Save the token returned by BotFather. It will be used as the TOKEN environment variable
Open a direct chat with the new bot and send /start after deployment

Keep the token secret. If it is exposed, revoke it with BotFather and generate a new one.

Set up PostgreSQL

Create a PostgreSQL database using a local server or any compatible managed provider. Obtain a connection URI in this format:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE

The application creates and updates the tables it needs at startup. The configured database user must therefore be able to create and alter tables, functions, and triggers in the selected database.

Configuration

Create a .env file in the repository root. Pipenv loads it automatically when you use pipenv run or pipenv shell.

TOKEN=123456789:replace_with_your_bot_token
DATABASE_URL=postgresql://user:password@localhost:5432/tgroupsindexerbot
OWNER_CHAT_ID=123456789
CONTACT_USERNAME=your_telegram_username
EXCEPTION_LOG_CHAT_ID=-1001234567890
ADMIN_ACTIONS_LOG_CHAT_ID=-1001234567890

Environment variables

Variable	Required	Description
`TOKEN`	Yes	Telegram bot token generated by BotFather.
`DATABASE_URL`	Yes	PostgreSQL connection URI. Both `postgres://` and `postgresql://`-style URIs are accepted by the current parser.
`OWNER_CHAT_ID`	Recommended	Numeric Telegram user ID of the instance owner. Owner-only commands depend on this value.
`CONTACT_USERNAME`	Recommended	Telegram username shown by contact buttons, without the leading `@`. If omitted, the application falls back to `username`.
`EXCEPTION_LOG_CHAT_ID`	No	Chat, group, or channel ID used for exception logs. The bot must be able to post there.
`ADMIN_ACTIONS_LOG_CHAT_ID`	No	Chat, group, or channel ID used for administrative-action logs. The bot must be able to post there.

Never commit .env, bot tokens, database credentials, or private chat IDs to the repository.

To obtain a numeric Telegram ID, you can start the bot and use /id in the relevant chat. For log channels or groups, add the bot and grant it permission to send messages.

Local installation

1. Clone the repository

git clone https://github.com/matypist/tgroupsindexerbot.git
cd tgroupsindexerbot

Alternatively, download and extract the main branch archive.

2. Install Python and Pipenv

The project targets Python 3.11. Installation commands vary by operating system and package manager.

Windows

Download Python 3.11 from the official Python website
Run the installer and enable the option to add Python to PATH
Open PowerShell or Command Prompt and verify the installation

python --version
python -m pip --version

Install Pipenv

python -m pip install --user pipenv

Windows has not been tested.

Debian and Ubuntu-based distributions

Update the package lists and install Python, pip, and the tools commonly required to create virtual environments.

sudo apt update
sudo apt install python3 python3-pip python3-venv
python3 --version
python3 -m pip --version
python3 -m pip install --user pipenv

If your distribution does not provide Python 3.11 as its default python3, install a suitable Python 3.11 package for your release or use a Python version manager.

Arch Linux and derivatives

Update the system and install Python and pip.

sudo pacman -Syu
sudo pacman -S python python-pip
python --version
python -m pip --version
python -m pip install --user pipenv

On Arch Linux, python normally refers to Python 3. Use python in place of python3 in the following commands if appropriate for your installation.

Other operating systems

Install Python 3.11 and pip using your operating system's supported package manager or the official Python downloads, then install Pipenv with the corresponding Python executable.

3. Install dependencies

pipenv install --deploy

If you intentionally need to refresh the lock file, use pipenv install without --deploy and review the resulting dependency changes before committing them.

4. Add the configuration

Create .env in the repository root using the example in the Configuration section.

5. Run the bot

pipenv run python main.py

The bot uses long polling, so no public HTTP endpoint or webhook is required.

First-run checklist

Confirm that PostgreSQL is reachable from the host running the bot
Start the application and check that database initialization completes
Send /start to the bot in a direct chat
Set OWNER_CHAT_ID to your numeric Telegram user ID
Optionally configure the exception and administrative-action log destinations
Add the bot to a test group as an administrator
Grant the permissions required to create or manage invite links and add members
Run /reload in the group if its information does not appear immediately
Use the bot's category browser to index the group

Commands

The following commands are registered by the current application. Availability depends on whether the command is used in a private chat or group and on the user's role.

General

/start — open or refresh the bot interface
/groups — browse indexed groups
/id — display the current chat ID
/dont — send a “don't ask to ask” reminder
/userstatus [user_id] — display known roles and restrictions

Group administration

/reload — refresh the current group's metadata and indexing status

Bot administration

/hide <chat_id> [chat_id ...] — hide one or more groups from indexing
/unhide <chat_id> [chat_id ...] — allow hidden groups to be indexed again
/move <chat_id> [chat_id ...] <directory_id> — index or move groups to a category
/unindex <chat_id> [chat_id ...] — remove groups from their categories
/restrict <user_id> <restriction> — apply a user restriction
/unrestrict <user_id> <restriction> — remove a user restriction

Custom-link administration

Bot administrators can create localized custom links, add them to one or more categories, and choose whether they appear in the groups list or as category buttons. A link may point to a fixed HTTP/HTTPS URL or follow the current custom or invite link of an indexed Telegram group. Links can be removed from individual categories or deleted globally through the Manage custom links interface.

Instance owner

/addadmin <user_id> — grant bot-administrator privileges
/rmadmin <user_id> — revoke bot-administrator privileges
/listadmins — list bot administrators

The code also accepts several aliases, including /index, /deindex, /bangroup, /unbangroup, /setadmin, /unsetadmin, and /removeadmin.

Group permissions

To index a group successfully:

the bot must be a member of the group;
the bot must be promoted to administrator;
the bot must be able to create or manage an invite link/add members, as supported by the group type and Telegram API;
the requesting user must have the appropriate group permissions;
the group must not be hidden by a bot administrator

If the group is not listed for indexing, run /reload inside the group, refresh the list, and check the bot's permissions.

Internationalization

Translations are stored in:

tgib/i18n/en.json
tgib/i18n/it.json

Locale loading and selection are implemented in tgib/i18n/locales.py. When adding a user-facing string, add the same key to every supported locale and preserve placeholders such as [user], [chat_id], and [category].

Repository structure

.
├── main.py                         # Application entry point
├── tgib/
│   ├── data/database.py            # PostgreSQL access and schema setup
│   ├── handlers/                   # Commands, messages, callbacks, status changes
│   ├── i18n/                       # Locale loader and translation files
│   ├── ui/menus.py                 # Telegram menus and keyboards
│   ├── global_vars.py              # Runtime-wide references and counters
│   └── logs.py                     # Local and Telegram logging
├── _scripts/                       # Repository maintenance scripts
├── .github/workflows/              # GitHub Actions workflows
├── Pipfile                         # Dependency declarations
├── Pipfile.lock                    # Locked dependency versions
├── Procfile                        # Worker process declaration
└── LICENSE                         # GNU AGPL v3 license text

Deployment notes

The included Procfile declares a worker process:

worker: python3 main.py

It can be used on platforms that support Procfile-based workers. Regardless of the platform, configure all required environment variables in the provider's secret/configuration interface and use persistent PostgreSQL storage.

Because the application uses polling, run only the intended number of bot worker instances for a given token. Multiple polling processes using the same token can conflict.

Commit notifications for maintainers

The workflow in .github/workflows/notify-commits-to-telegram.yml sends notifications for pushes to the main branch. To enable it in a fork, configure these GitHub Actions repository secrets:

TELEGRAM_BOT_TOKEN
TELEGRAM_CHAT_ID
TELEGRAM_THREAD_ID (when posting to a specific topic in a Telegram group with topics enabled)

This automation is separate from the bot runtime and is not required for a self-hosted instance.

Troubleshooting

The bot does not start

Verify TOKEN and DATABASE_URL
Confirm that dependencies were installed from Pipfile.lock
Confirm that the runtime uses Python 3.11
Check PostgreSQL network access, credentials, and permissions

A group is missing from the indexing list

Ensure both the bot and the requesting user are administrators of the group
Check the bot's invite-link/member permissions
Run /reload in the group
Refresh the list in the bot interface
Confirm that the group has not been hidden by a bot administrator

Logging to Telegram fails

Verify the destination chat ID, including the -100 prefix typically used by channels and supergroups
Ensure the bot is present and allowed to send messages
Leave the optional log variable unset if that log destination is not needed

Security and privacy

A deployed instance stores Telegram identifiers and group metadata in PostgreSQL. Instance operators are responsible for:

protecting bot tokens, credentials, backups, and log destinations;
limiting database and administrator access;
informing users about applicable data handling and retention practices;
complying with Telegram's terms and applicable privacy law;
reviewing logs before sharing them, as they may contain user or chat identifiers

Please report security-sensitive issues privately to the repository maintainer rather than publishing credentials or exploitable details in a public issue.

Contributing

Issues and pull requests are welcome.

Before submitting a change:

Create a branch from main
Keep changes focused and document any new environment variables or database changes
Update both English and Italian locale files for user-facing text
Test startup against a disposable PostgreSQL database and a test Telegram bot
Do not commit secrets, .env files, database dumps, or personal data

License

TGroupsIndexerBot is free software distributed under the GNU Affero General Public License, version 3 or later. If you modify and provide the software to users over a network, review the source-availability obligations in the AGPL.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
_scripts		_scripts
tgib		tgib
LICENSE		LICENSE
Pipfile		Pipfile
Pipfile.lock		Pipfile.lock
Procfile		Procfile
README.md		README.md
main.py		main.py

Latest commit

History

Folders and files

Repository files navigation