TelegramBotAdmin/LOCAL_SETUP.md

Local setup

This fork adds a local Ant Design Pro admin panel, Telegram private management, Mongo-backed giveaways, per-chat points, and a cross-Bot teacher directory to WilliamButcherBot.

Requirements

• Python 3.12 and uv
• Node.js 20 or newer
• MongoDB 7, or Docker with Docker Compose
• One or more Telegram bot tokens, an API ID/API hash, and a test group

Bot credentials are managed in the web panel. Sensitive values are stored in runtime/bot_profiles.json with mode 0600 and are never returned by the API. Each enabled Bot runs in its own process and uses an isolated MongoDB database; the Web administrator account and sessions remain in the shared control database.

Configure

cp config.env.template config.env

The environment file now contains only process-level settings. Set at least:

• MONGO_URL
• Optional admin bind, session, and upload settings

After login, open System settings and configure the shared Telegram API ID and API Hash. Add any number of Bot profiles; every profile has its own Token, SUDOERS, log groups, media relay group, Pyrogram session, and worker process. Enabled profiles start automatically as soon as the shared API credentials are complete. Token testing uses Telegram's official getMe endpoint.

Telegram Business intelligent reception

For each Bot that should handle account chats:

1. Open BotFather, choose the Bot, enter Bot Settings, and enable Business Mode. Test the Token again in System settings; the result must report Business Connection support.
2. Assign the built-in Intelligent reception specialist role, or grant business_assistant.manage through a custom role.
3. Open Intelligent reception, configure an OpenAI-compatible Base URL ending at the API root (for example https://models.example.com/v1), API Key, model, timeout, and output limit. Saving this configuration restarts only the selected Bot worker.
4. On the Telegram account that will be represented, open Settings → Telegram Business / Chat Automation → Chatbots, connect the Bot, and select the chats it may access. This account-side authorization cannot be automated by the server.
5. Return to Intelligent reception, select the connection, create its FAQ entries, choose notification destinations, and enable automatic reception.

The account must be eligible for Telegram Business/Chatbots in the official client. Each connection has independent settings, FAQ entries, conversations, daily limits, timezone, and digest schedule. Default limits are 200 AI calls per connection per day and 20 per customer per day. Original messages expire after 30 days; summaries and follow-up state remain until an administrator clears the conversation.

The runtime refuses to poll when a webhook is configured, ignores Telegram's native greeting/away messages and messages sent by the Business Bot itself, and never sends outside the official 24-hour reply window. A manual reply by the connected account pauses automation for 24 hours by default. Explicit handoffs remain paused until an authorized owner, operations-group admin, or Web administrator resumes them.

The admin panel defaults are:

• Address: http://127.0.0.1:8088/admin
• Username: admin
• Initial password: qwe0.123456

The initial password is only used to create the first admin record. The first login must change it. Later changes to the environment value do not overwrite an existing password hash.

Run with Docker Compose

docker compose up --build

The container listens on 0.0.0.0:8088, while Compose publishes it only at 127.0.0.1:8088. MongoDB is not exposed to the host. Bot profiles persist in the bind-mounted runtime/ directory.

Run from the workspace

uv sync --python 3.12
cd admin-web
npm ci
npm run build
cd ..
uv run python launcher.py

For frontend development, keep the bot/API on port 8088 and run:

cd admin-web
npm run dev

Umi runs on port 8090 and proxies /api/admin/* to the Python service. The launcher keeps the control panel on port 8088 and starts one internal worker per enabled Bot. The Bot selector in the header routes group operations to the selected worker.

Telegram commands

User points commands:

/points
/checkin
/points_rank
/points_history

Administrator points commands:

/points_add <user> <amount> <reason>
/points_deduct <user> <amount> <reason>
/points_set <user> <balance> <reason>
/points_toggle <enable|disable>

Giveaway commands:

/giveaway 1h | First:1:50, Second:3:10 | Launch | Description | 20 | 5 | 2
/gjoin <id>
/glist
/gparticipants <id>
/gend <id>
/gcancel <id>
/greroll <id> [tier]
/gremove <id> <user_id> [no-refund]
/gban <user> [reason]
/gunban <user>

Private administration:

/manage [chat_id]
/cancel

Private menu flows expire after ten minutes. Every action rechecks the operator's current Telegram permissions; SUDOERS can manage all known groups.

Teacher directory:

/directory
/nearby
/teacher_rank
/teacher_apply
/teacher_list
/teacher_unlist
/teacher_online
/teacher_offline

Assign the Teacher directory manager role to every Bot that should expose these commands. Teacher identity, location, listing, and presence are global across all configured Bots. A user must first run /directory in a managed group so the supervisor can perform a live membership check.

Open Teacher directory in the Web panel to review applications and configure OpenStreetMap Nominatim. Public Nominatim reverse geocoding remains disabled until a contact email or URL is configured. It is globally limited to one request per second, cached, and only receives coordinates after the user accepts the Telegram privacy prompt. Distance search continues to work when Nominatim is disabled or unavailable.

Verification

uv run ruff check wbb tests sample_config.py
uv run python -m compileall -q wbb
uv run pytest
cd admin-web
npm ci
npm run typecheck
npm test
npm run build
cd ..
docker compose config

Ruff is scoped in pyproject.toml to this fork's new and modified feature modules; the untouched upstream bot still has its pre-existing lint backlog.

Real Telegram group acceptance still requires API ID/API Hash and a disposable test group. Do not use a production group for the first run.