Helpdesk Bot

A Telegram bot that provides private, one-on-one support sessions between users and agents — all through a single shared support channel.

How it works

1. A user joins the support channel
2. The bot greets them privately via DM and asks for their question
3. Their question is relayed to a staff-only agent group as a support ticket
4. An agent claims the ticket and the conversation continues — user in DMs, agent in the group
5. When resolved, the user is automatically removed from the support channel and can rejoin anytime

No user ever sees another user's conversation. The support channel itself is locked — members cannot send messages in it.

Features

• Private by design — all support conversation happens in DMs and a staff-only group
• Session-based — users are added on join, removed on resolution, and can return as needed
• Ticket tracking — every conversation is logged to PostgreSQL with full message history
• Role-based access — users, agents, and admins each have distinct capabilities
• No setup needed for users — just join the channel and the bot handles the rest

Requirements

• Python 3.11+ (or Docker)
• PostgreSQL 14+
• A Telegram bot token from @BotFather
• Two Telegram supergroups (support channel + agent group)

Quick start (Docker)

cp .env.example .env
# Edit .env with your values
docker compose run --rm migrate
docker compose up -d bot db

Quick start (local)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your values
alembic upgrade head
python -m bot.main

Configuration

Copy .env.example to .env and fill in:

Variable	Description
TELEGRAM_TOKEN	Bot token from @BotFather
DATABASE_URL	PostgreSQL connection string (postgresql+asyncpg://...)
SUPPORT_GROUP_ID	Chat ID of the supergroup users join
AGENT_GROUP_ID	Chat ID of the staff-only agent group
ADMIN_IDS	Comma-separated Telegram user IDs with admin access

See docs/configuration.md for full details.

Telegram setup

Support channel

1. Create a supergroup and add the bot as admin with Delete messages and Ban users permissions
2. In Group Settings → Permissions, disable Send Messages for members
3. Set SUPPORT_GROUP_ID to the group's chat ID

Agent group

1. Create a second supergroup with only your support staff
2. Add the bot as admin with Send messages and Delete messages permissions
3. Set AGENT_GROUP_ID to the group's chat ID

Tip: Forward any message from a group to @userinfobot to get its chat ID.

Documentation

• Installation
• Configuration
• Architecture
• Administration

Tech stack

Concern	Choice
Bot framework	python-telegram-bot v20+
ORM	SQLAlchemy 2.0 async
DB driver	asyncpg
Migrations	Alembic
Settings	pydantic-settings