A Telegram bot that manages group join requests with voting workflows.

• Vote-based join approval with timeout, minimum-voter threshold, and admin override actions.
• Two voting modes:
  • Normal Telegram poll mode.
  • Advanced button mode (Yes/No + live result query).
• Multi-language support (en_US, zh_CN, zh_TW) with per-group language setting.
• Group settings panel with inline controls and /setting command arguments.
• Optional log channel updates (Pending -> Approved/Denied edit-in-place).
• PostgreSQL storage for group settings and join request lifecycle.

• Python 3.12+
• PostgreSQL 14+ (recommended 15/16)
• Telegram Bot token

1. Prepare config files.
2. Install dependencies with uv or pdm.
3. Start the bot.

uv sync
uv run python main.py

Or with PDM:

pdm install
pdm run python main.py

Copy .env.exp to .env and fill your token:

TELEGRAM_BOT_TOKEN=123456:ABC...
# TELEGRAM_BOT_PROXY_ADDRESS=socks5://127.0.0.1:7890

Copy conf_dir/.secrets.toml.exp to conf_dir/.secrets.toml and edit values:

[botapi]
enable = false
api_server = "http://127.0.0.1:8081"

[database]
host = "127.0.0.1"
port = 5432
user = "postgres"
password = "postgres"
dbname = "postgres"

[logchannel]
enable = false
channel_id = -1001234567890
message_thread_id = 0

message_thread_id = 0 means "do not use thread id".

[app]
debug = false

python main.py

On startup, the bot connects to PostgreSQL and creates required tables if missing.

• /help - Show help information.
• /setting - Open group settings panel.
• /setting time <seconds|10m30s> - Set vote duration (30-3600 seconds).
• /setting voter <count> - Set minimum voters (1-500).
• /setting mini_voters <count> - Alias for voter.

docker build -t approvebypoll-v2:local .

1. Copy and edit config files:
   • .env.exp -> .env
   • conf_dir/.secrets.toml.exp -> conf_dir/.secrets.toml
2. Start:

docker compose up -d --build

3. Logs:

docker compose logs -f bot

4. Stop:

docker compose down

This repo provides a ready-to-use unit file: approvebypoll.service.

1. Prepare runtime files first:
   • .env
   • conf_dir/.secrets.toml
   • conf_dir/settings.toml
2. Create a dedicated Linux user (recommended).
3. Put the project at /opt/ApproveByPoll-V2 (or adjust paths in the unit file).
4. Ensure virtualenv exists at /opt/ApproveByPoll-V2/.venv.

Install and enable:

sudo cp approvebypoll.service /etc/systemd/system/approvebypoll.service
sudo systemctl daemon-reload
sudo systemctl enable --now approvebypoll

Manage service:

sudo systemctl status approvebypoll
sudo systemctl restart approvebypoll
sudo journalctl -u approvebypoll -f

If your deployment path or Python path differs, edit WorkingDirectory and ExecStart in approvebypoll.service.

This repo includes a workflow to auto-build and push Docker images to GHCR.

• Workflow file: .github/workflows/docker-ghcr.yml
• Trigger:
  • Push to main
  • Tag pushes v*
  • Manual dispatch

Published image path format:

ghcr.io/<owner>/<repo>:<tag>

Examples:

• ghcr.io/kimmyxyc/approvebypoll-v2:main
• ghcr.io/kimmyxyc/approvebypoll-v2:latest
• ghcr.io/kimmyxyc/approvebypoll-v2:v2.0.0

• Keep .env and conf_dir/.secrets.toml out of Git.
• For production, give the bot only required admin permissions.
• If poll sending fails in your Telegram environment, the bot can fallback to advanced button voting mode.

MIT