中文 README

Designed for better Telegram message forwarding.

Forward private messages to topics in a group—one user per topic—so multiple admins can collaborate without exposing personal accounts.

• Privacy & teamwork: User messages appear in group topics; admins reply from the group.
• Multi-language: English, Chinese, and Japanese (en_US / zh_CN / ja_JP).
• Auto reply: Keyword-based replies with regex support and scheduled active hours.
• Human verification: Button, math, or TGuard advanced verification.
• Spam filtering: Keyword-based detection with automatic routing to a dedicated spam topic.
• Permission controls: Restrict message types globally and per user; view and reset overrides.
• User management: Ban/unban, blocked-user auto-reply, terminate threads, topic notes, broadcast, and more.

Send /help in the group main topic to open the admin menu.

1. Create a bot via @BotFather and get the token.
2. Create a group with topics enabled and add the bot as admin (manage topics, delete messages).
3. Get the group ID (invite @sc_ui_bot and send /id).
4. Deploy BetterForward (see Docker below).

Messages users send to the bot are forwarded to their topic in the group.

Available languages: en_US, zh_CN, ja_JP. Contributions for more languages are welcome.

1. Download docker-compose.yml:

wget https://github.com/SideCloudGroup/BetterForward/raw/refs/heads/main/docker-compose.yml

2. Edit and replace placeholders:

   • your_bot_token_here → bot token
   • your_group_id_here → group ID
   • zh_CN → language (en_US, zh_CN, or ja_JP)
   • TG_API → custom API URL (leave empty for default)
   • WORKER → worker thread count (increase for higher traffic)

3. Start:

docker compose up -d

Replace /path/to/data with your data directory:

docker run -d --name betterforward \
    -e TOKEN=<your_bot_token> \
    -e GROUP_ID=<your_group_id> \
    -e LANGUAGE=en_US \
    -e WORKER=2 \
    -v /path/to/data:/app/data \
    --restart unless-stopped \
    ghcr.io/sidecloudgroup/betterforward:latest

Set the TG_API environment variable for a custom Telegram API endpoint. Leave empty to use the default API.

If you deploy with Docker, you can use WatchTower to update automatically (replace the container name below):

docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower -cR \
<Container Name>

Configure most features via /help in the group main topic unless noted otherwise.

• Add and manage multiple auto-reply rules
• Regex keyword matching
• Optional active time windows

Menu: Auto Reply

Set the welcome or hint message users receive when they first contact the bot.

Menu: Default Message

• Ban users to stop them from sending messages
• Optional auto-reply when a banned user tries to message

Menus: Banned Users, Blocked User Reply

Three methods (choose in Captcha Settings):

1. Button — tap to verify
2. Math — solve a simple arithmetic problem
3. TGuard — configure API URL and key under TGuard API Settings; verification opens in a Telegram Mini App

Admins can also mark a user as verified with /verify in a user topic.

• Add, view, and remove spam keywords from the admin menu
• Matched messages go to a dedicated spam topic instead of creating user threads

Menu: Spam Keywords

Under Permission Settings:

• Default Permission Settings — globally allow or deny: photos, stickers/animations, videos, voice, files (documents and audio), links, and @usernames. All are allowed by default.
• Permission Restriction Reply Message — optional reply when a user sends a blocked type ({permission} is replaced with the type name); can be disabled for silent blocking.

In a user topic, admins can adjust permissions for that user:

Valid keys: photo, sticker, video, voice, file, link, username; use all for every type (plain text is not affected).

• Broadcast Message — notify all users at once
• Time Zone Settings — affects time-based features such as auto reply

In a user topic:

• /setnote <text> — set or clear a note for the topic
• /getnote — show the note

Available in the group (some apply only inside user topics):

In private chat with the bot: /help, /delete.

• Telegram channel @betterforward

Please use issues for bug reports and feature requests.