SandAI Telegram Community Bot

SandAI is a Khmer-first Telegram community manager bot for the Sand AI Builder Project group.

Features

• Khmer welcome message for new members with inline buttons.
• Group rules and project information button handlers.
• Anti-spam and anti-scam link scanning with warning counts.
• Three warnings can trigger temporary mute or ban.
• Member reputation upvotes through inline buttons.
• Daily tech summary from tracked discussion topics.
• Local FAQ quick replies for common setup questions.
• OpenAI API-backed SandAI replies when members mention SandAI or reply to the bot.
• Multi-group settings isolation by Telegram group_id.
• Private-chat admin dashboard for welcome text, rules, and official URL.
• Analytics view for tracked topics and blocked spam.
• Security gatekeeper for Telegram join requests.
• Voice command transcript support through [VOICE_COMMAND].
• Guest query fallback through [GUEST_QUERY ...] frames.

Setup

1. Create and activate a virtual environment:

python -m venv .venv
.venv\Scripts\activate

2. Install dependencies:

python -m pip install -r requirements.txt

3. Copy .env.example to .env and set your values:

copy .env.example .env

Set OPENAI_API_KEY, OPENAI_MODEL, and OPENAI_MAX_OUTPUT_TOKENS to enable AI replies.

4. Run the bot:

python -m sandai_bot

Deploy To Render + UptimeRobot

Use a Web Service so Render exposes an HTTPS URL that UptimeRobot can ping. The bot still runs Telegram polling; the web service only adds a lightweight health endpoint.

This repo includes render.yaml, so Render Blueprint deploy can create the service and persistent disk automatically.

Required environment variables:

• BOT_TOKEN
• ADMIN_IDS
• OPENAI_API_KEY

Recommended environment variables:

• STATE_FILE=/data/sandai_state.json
• OFFICIAL_DOMAIN, OFFICIAL_WEBSITE, PROJECT_INFO_URL, RULES_URL, DOCS_URL
• BOT_INVITE_URL

Manual Render settings:

• Runtime: Python
• Build Command: pip install --upgrade pip && pip install -r requirements.txt
• Start Command: python -m sandai_bot
• Health Check Path: /healthz
• Disk Mount Path: /data
• Disk Size: 1 GB

Do not deploy .env; configure secrets in your hosting provider dashboard.

After Render deploys, create an UptimeRobot HTTP monitor:

• Monitor Type: HTTP(s)
• URL: https://YOUR-RENDER-SERVICE.onrender.com/healthz
• Interval: 5 minutes
• Keyword monitoring: optional, expected text is ok

Multi-Group Settings

Each Telegram group has isolated settings stored by group_id in STATE_FILE.

Group owners/admins should:

1. Add SandAI to their Telegram group.
2. Send any normal message in the group so SandAI can verify admin ownership.
3. Open a private chat with SandAI.
4. Select the group and update settings through inline buttons only.

• Welcome message
• Group rules
• Official group URL
• Security Gatekeeper
• Group analytics

The bot uses the current group's URL for link moderation. Settings from one group are never reused in another group. Configuration changes are intentionally handled in private chat, not in the public group. Navigation is strictly button-driven; public groups are reserved for moderation and service replies.

Gateway Events

• Join requests are handled by ChatJoinRequestHandler. Enable Gatekeeper in the private dashboard to require DM verification.
• Voice transcripts prefixed with [VOICE_COMMAND] can update settings when the owner manages exactly one group.
• Guest frames prefixed with [GUEST_QUERY ...] get a one-message Khmer answer plus an add-bot button.