Free Telegram Anti-Spam & Welcome Bot — Self-Hosted PHP

GuardZip is a Telegram group protection bot you host yourself — one PHP file on any HTTPS shared hosting. That's the point: the popular moderation bots are third parties with admin rights inside your community; GuardZip is your own bot, on your own server, with state in flat JSON files next to the script.

What it does for your group: greets new members and puts them behind a captcha button (fail to press within 3 minutes → kicked, and only the joining user can press their own button); mutes flooders automatically (6+ messages in 10 seconds); deletes links and forwards from members in their first 24 hours; deletes banned-word messages; and runs a 3-strikes warning system that escalates to a ban. Admins moderate by replying: /warn, /unwarn, /mute [minutes], /unmute, /ban — plus /setwelcome (with a {name} placeholder), /setrules, /badword, and /guardzip to view or toggle every feature per group. Group admins are exempt from all filters.

Under the hood: Telegram webhook with a secret-token check (403 for anything else), a one-command CLI installer that registers the webhook, per-chat JSON state with file locking, a 5-minute admin-list cache, and a "lazy cron" that expires overdue captchas on the next update — no cron job needed.

1. On Telegram, message @BotFather → /newbot → copy the token into const BOT_TOKEN at the top of guardzip.php.

2. Upload guardzip.php to any HTTPS site of yours.

3. Run once: php guardzip.php install https://yoursite.com/guardzip.php — this registers the webhook with a random secret token (stored next to the script; requests without it get a 403).

4. Add the bot to your group and promote it to admin with "delete messages", "ban users" and "restrict members". Send /guardzip in the group to see and tune the settings.

Per-group state lives in guardzip-data/*.json (auto-created with a deny-all .htaccess).

Paste this prompt into Claude to build this exact product:

Build a self-hosted Telegram group-protection bot called GuardZip as a SINGLE PHP file (PHP 8+, curl only, no Composer, no database). It must work on cheap shared hosting via webhooks.

Plumbing: a CONFIG block (BOT_TOKEN + tunables); a CLI entry (php guardzip.php install <https-url>) that generates a random secret, saves it beside the script, and calls setWebhook with secret_token and allowed_updates (plus an uninstall command); the webhook entry verifies the X-Telegram-Bot-Api-Secret-Token header with hash_equals and 403s otherwise. Per-chat state in guardzip-data/chat_<id>.json with flock-guarded read-modify-write and a deny-all .htaccess; a helper wraps every state mutation. Cache getChatAdministrators for 5 minutes per chat. All outgoing text HTML-escaped, members referenced with tg://user?id= mentions.

Join flow: on new_chat_members (skip bots), record the join time, restrict the member (no sending), and post a captcha message with an inline "✅ I'm human" button whose callback_data carries the user id. Only that user's press counts (anyone else gets a toast); on success: unrestrict, delete the captcha message, send the welcome text with a {name} placeholder. Overdue captchas (3 minutes) are handled by a "lazy cron" that runs on every update: kick (short ban) + delete the captcha message. If captcha is disabled, just welcome.

Filters (group admins exempt): anti-flood — more than 6 messages in a sliding 10-second window mutes the member for 10 minutes; banned words — case-insensitive substring list, delete + warn; link filter — members in their first 24h cannot post http(s)/t.me/@mention links or forwards (delete + warn). Warnings escalate: 3 warnings → ban, with the counter announced each time ("warning 2/3").

Commands: everyone gets /rules. Admin-only (checked live): /warn /unwarn /ban /mute [minutes] /unmute as replies to the offender; /setwelcome, /setrules, /badword <word>; and /guardzip which prints the group's settings summary or toggles features (/guardzip captcha|links|flood on|off). In DMs the bot politely says it only guards groups.

Testability: honor a GUARDZIP_TEST env var that makes the API wrapper append {method, params} JSON lines to a log file and return a canned success — so the whole bot can be integration-tested by POSTing fake Telegram updates at it locally.

Deliver the single PHP file with a proper header comment and MIT license.

What happened when we ran it: Claude produced the bot in one file — 360 lines. We integration-tested it exactly as the spec suggests: a local server received fake Telegram updates while the test hook logged every outgoing API call. Verified end-to-end: join → restrict + captcha; the wrong user pressing the button gets rejected while the right one gets unrestricted and welcomed; a new member's link is deleted with "warning 1/3" and the third violation triggers banChatMember; seven rapid messages earn a 10-minute flood mute; /guardzip prints settings and toggles captcha off; /badword makes "CASINO" (case-insensitive) vanish with a warning; and an admin posting a link is left untouched. One revision: the test hook's canned API response crashed the admin-list parser until it validated the response shape — a robustness fix that also protects against odd real-world API replies.

Note: the download is the full, unrestricted bot. The prompt is for reproducing (or remixing) the build yourself with your own Claude subscription.