tgsupportbot

A Telegram support bot that forwards messages from users to a group chat, allowing a support team to respond privately.

How it works

Users message the bot directly. The bot forwards each message to a configured support group (optionally into a specific topic thread). Support staff reply in the group by replying to the forwarded message; the bot delivers the reply back to the user.

If a message goes unanswered, the bot sends a reminder to the group every 6 hours until the conversation is marked finished.

Setup

Docker (recommended)

docker build -t tgsupportbot .
docker run -d \
  -v /path/to/config.yaml:/config.yaml \
  -v /path/to/data:/data \
  tgsupportbot

Set database: "/data/instance.db" in your config so the database persists outside the container.

Manual

Requirements: Python 3, pip

pip install -r requirements.txt

Copy config.yaml.example to config.yaml and fill in the values (see Configuration below).

Create a bot via @BotFather, add it to your support group, and give it permission to read and send messages.

python -m supportbot -c config.yaml

Configuration

# Telegram bot token from @BotFather
bot_token: "BOT_TOKEN_HERE"

# Path to the database file
database: "./instance.db"

# ID of the support group where messages are forwarded
target_group: -12345678

# Optional: topic thread ID to use within the group
message_thread_id: 1

# Message shown to users on /start (HTML)
welcome_text: |
  <b>Welcome</b>. Please describe your issue.

# Message shown after a user sends a message (HTML)
reply_text: |
  Thanks, we'll get back to you shortly.

# Optional: link template shown in the group alongside user info.
# %d is replaced with the user's Telegram ID.
integration_fmt: "https://example.com/users/%d"

# Optional: how often to send reminders for unanswered messages, in minutes (default: 360)
reminder_interval_minutes: 360

Group commands

All commands are issued in the support group by replying to a forwarded message.

Command	Description
/status	Show the user's info, reply status, and ban state
/ban	Ban the user permanently
/ban 7d	Ban the user for a duration (s, m, h, d, w)
/unban	Unban the user
/finished	Mark the conversation as resolved and stop reminders

Reminders

When a user sends a message, the bot starts a reminder timer. If /finished has not been used before the interval elapses, a reminder is posted to the group. Reminders repeat at the same interval until /finished is used. The timer resets if the user sends another message.