Telegram Confessions Bot

Built for Community, Moderation, and Control

Step-by-Step Setup Guide

1. Gather Your Credentials

Before you begin, you need to collect a few key pieces of information. This is the most important step!

Telegram Bot Token: Get this from @BotFather on Telegram by creating a new bot.
Admin Telegram ID: This is your personal user ID. Get it from a bot like @userinfobot.
Channel ID: The ID of the public channel where confessions will be posted. The bot must be an admin in this channel. The ID usually starts with -100.
PostgreSQL Database URL: A connection string to your database. Free tiers are available from services like Aiven or Supabase.
Python 3.9+ Installed: Make sure you have a modern version of Python on your system.

2. Get the Bot's Code

Next, download the code from GitHub and install the necessary Python packages.

1. Clone the Repository

This command downloads the bot's source code into a new folder named confessions-bot.

git clone https://github.com/addisuderrese/confessions-bot.git

2. Navigate into the Directory

Move your terminal session into the newly created folder.

cd confessions-bot

3. Install Required Packages

This command installs all the libraries the bot depends on to function.

pip install -r requirements.txt

3. Configure Your Bot

You'll store your credentials in a secure .env file. Create this file in the main directory of the bot.

BOT_TOKEN

This is the unique key for your bot. Get it from @BotFather after creating your bot.

BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

ADMIN_ID

This is your personal Telegram User ID, which grants you admin privileges. Get it from @userinfobot.

ADMIN_ID="987654321"

CHANNEL_ID

The unique identifier for your public channel. Make sure the bot is an administrator in this channel. The ID should start with -100.

CHANNEL_ID="-1001234567890"

DATABASE_URL

The full connection string for your PostgreSQL database. You can get this from your database provider (e.g., Aiven, Supabase).

DATABASE_URL="postgres://user:password@host:port/dbname?sslmode=require"

Once your .env file is saved with all four values, you're ready for the final step!

4. Launch the Bot

With the configuration complete, you're ready to start the bot.

1. Run the Main Script

Execute the following command in your terminal. The bot will start up, connect to the database, and begin listening for commands.

python main.py

2. Check the Logs

On its first run, the bot will automatically create all the necessary tables in your database. You should see log messages in your terminal indicating a successful database connection and table setup.

Your bot is now live! Try sending it a /start command on Telegram to verify it's working.

Commands & Usage

User Commands

/start

Shows the welcome message or views a confession.

/confess

Starts the anonymous confession submission process.

/profile

View your Aura points and submission history.

/help

Displays the help message with all commands.

Admin Commands

/id <user_id>

Gets a detailed profile of a user.

/warn <user_id> <reason>

Sends a formal warning to a specific user.

/block <user_id> <duration>

Temporarily blocks a user (e.g., `7d`, `2w`).

/pblock <user_id>

Permanently blocks a user from the bot.

Build Your Community, Anonymously.