TeleWatchdog

TeleWatchdog is a Cloudflare Workers Telegram join-request watchdog for private groups.

It reviews join requests with a simple pipeline:

1. Check whether the applicant has an avatar.
2. Check whether the applicant has a bio.
3. If either is missing, require verification.
4. If both exist, ask an AI model for a binary decision.
5. If the AI returns approve, accept the join request immediately.
6. Otherwise, send a verification message with a Telegram Web App button.

Users who need verification can choose either:

• Cloudflare Turnstile
• Telegram WebApp BiometricManager

If verification is not completed within 10 minutes, a scheduled task declines the request and cleans up the stored state.

Features

• Telegram chat_join_request webhook support
• Cloudflare Worker deployment model
• Telegram Web App verification page
• Turnstile verification
• Telegram biometric verification via BiometricManager
• AI-based binary profile review
• Automatic cleanup of expired verification records
• Automatic deletion of verification messages after success or timeout

Stack

• Cloudflare Workers
• Cloudflare KV
• Telegram Bot API
• Cloudflare Turnstile
• OpenAI-compatible chat completion API

Project Structure

src/index.ts           Main Worker implementation
package.json           Project metadata and scripts
tsconfig.json          TypeScript config
wrangler.toml.example  Example Wrangler config

Required Secrets

Set these with wrangler secret put:

• BOT_TOKEN
• TG_WEBHOOK_SECRET
• AI_BASE_URL
• AI_API_KEY
• TURNSTILE_SECRET

Required Variables

Set these in wrangler.toml:

• AI_MODEL
• TURNSTILE_SITE_KEY
• VERIFICATION_ORIGIN

KV Setup

Create a KV namespace:

npx wrangler kv namespace create PENDING_JOINS

Copy the returned namespace id into your wrangler.toml.

Local Setup

npm install
copy wrangler.toml.example wrangler.toml

Then edit wrangler.toml and add your real values.

Deploy

npx wrangler deploy

Telegram Webhook

After deployment, configure the webhook to point to:

https://your-worker-domain/telegram/webhook

Example PowerShell:

$botToken = "YOUR_BOT_TOKEN"
$secret = "YOUR_TG_WEBHOOK_SECRET"
$body = @{
  url = "https://your-worker-domain/telegram/webhook"
  secret_token = $secret
  allowed_updates = @("chat_join_request")
} | ConvertTo-Json -Compress

Invoke-RestMethod -Method Post -Uri "https://api.telegram.org/bot$botToken/setWebhook" -ContentType "application/json" -Body $body

Telegram Permissions

The bot must:

• be added to the target group
• be an administrator
• have permission to approve join requests

The group must be configured to require approval for join requests.

Verification Flow

Auto-approve path

• user has avatar
• user has bio
• AI returns approve
• request is approved immediately
• no message is sent to the user

Verification path

• avatar missing, or
• bio missing, or
• AI returns challenge, or
• AI request fails

Then:

• a single verification message is sent
• user opens the Telegram Web App
• user completes Turnstile or biometric verification
• the bot approves the request
• the verification message is deleted
• KV records are deleted

Timeout path

• request stays pending for 10 minutes
• scheduled Worker declines the join request
• verification message is deleted
• KV records are deleted

Notes

• Telegram biometric verification here uses Telegram.WebApp.BiometricManager, not WebAuthn.
• Telegram Web App initData is verified server-side before accepting either verification method.
• Public repository users should create their own Worker domain, Turnstile site, KV namespace, and AI credentials.

License

Add your preferred license before publishing if needed.