# 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)

```sh
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

```sh
pip install -r requirements.txt
```

Copy `config.yaml.example` to `config.yaml` and fill in the values (see [Configuration](#configuration) below).

Create a bot via [@BotFather](https://t.me/BotFather), add it to your support group, and give it permission to read and send messages.

```sh
python -m supportbot -c config.yaml
```

## Configuration

```yaml
# 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.