aqil-claude-code

Superteammy Guardian

Telegram onboarding bot for Superteam Malaysia. New members must introduce themselves in a dedicated intro channel before they can chat in the main group.

How It Works

1. User joins the main group — bot sends a welcome message with intro format and a link to the intro channel
2. User posts in the intro channel — bot validates the intro and marks them as introduced
3. User posts in the main group — if not introduced, message is deleted and a temporary reminder is sent
4. Group admins can manually approve, reset, or check user status via commands
5. Any message containing a suspicious link (URL shorteners, bare IP addresses, IDN homograph domains, or Telegram invite links) in the main group is deleted and the sender receives a warning — admins are exempt

Screenshots

Initial setup — registering the main group and intro channel:

Welcome message sent when a new member joins, and the gatekeeper reminder when they try to post before introducing themselves	Member posts a valid intro and the bot accepts it — they can now chat freely in the main group
Bot deletes the message and warns the sender when a suspicious link is detected in the main group

Quick Start

1. Create a Bot

Message @BotFather on Telegram, send /newbot, and copy the token.

2. Install and Configure

cp .env.example .env

Add your bot token to .env:

BOT_TOKEN=your-bot-token

That's the only config needed. The bot uses Telegram's group admin roles automatically.

3. Run

npm install
npm run dev

Or with Docker:

docker compose up -d

Running Tests

npm test                 # run all tests
npm run test:watch       # watch mode
npm run test:coverage    # with coverage report

4. Register Your Chats

1. Add the bot as admin to your main group (needs "Delete Messages" permission)
2. Add the bot to your intro channel (needs "Post Messages" permission)
3. Send /setgroup in the main group
4. Send /setintro in the intro channel

Done. The bot saves these settings to the database — you only need to do this once.

Admin Commands

Any Telegram group admin can use these commands — no separate config needed.

Setup (run once, in each chat)

Command	Description
/setgroup	Register the current chat as the main group
/setintro	Register the current chat as the intro channel

Management (main group only)

Command	Description
/approve <user_id or @username>	Manually mark a user as introduced
/reset <user_id or @username>	Reset intro status (forces re-introduction)
/status <user_id or @username>	Check a user's current status
/pending	List all users who haven't introduced yet

All management commands support a user ID, an @username, or replying to a message.

Intro Validation

The bot uses a soft heuristic — not a strict template:

• Message must be at least 50 characters
• Accepted if it contains 2+ keywords (who are you, what do you do, where are you based, fun fact, contribute)
• Messages 80+ characters are accepted regardless of keywords
• Messages over 4000 characters are rejected

Prefers false positives over false negatives — a borderline intro is better than blocking a real member.

Project Structure