A Telegram private-group join verification bot on Cloudflare Workers. Hono handles authenticated webhooks, grammY routes updates and calls the standard Bot API, and Drizzle + D1 persist state. Telegram Serverless access is not required. There is no public frontend.
A requester sees the full group rules and one bilingual multiple-choice question in private chat. The question can be refreshed twice at most; the answer button also explicitly accepts the rules. A correct answer approves the join request, while a wrong answer or timeout declines it and starts the default 30-minute approval cooldown. Prompts are available in cn and en.
| Path | Purpose |
|---|---|
src/index.ts |
Hono webhook (secret check, then grammY), health check and scheduled entry |
src/bot.ts |
Request-scoped grammY Bot: routes each update kind to the service |
src/lib/telegram.ts |
grammY Api setup (timeouts, 429 retry) and the redacting BotApi adapter |
src/lib/service.ts |
Verification flow, revision CAS, approval retries and scheduled cleanup |
src/timer.ts |
Per-session Durable Object timer that wakes maintenance at the due time |
src/lib/repository.ts |
Drizzle queries and revision CAS |
src/schema.ts / migrations/ |
D1 table definitions and SQL migrations |
private-content/ |
Local checkout of the private question repository (gitignored); synced with D1 |
scripts/build.mjs |
Bundles the Worker |
scripts/content-cli.mjs |
Content CLI: push, pull and list packs between a checkout and D1 |
dist/worker.js |
Generated deployment bundle |
Use Node.js 24+ and pnpm 12 (pnpm@12.11.2 in packageManager).
pnpm install --frozen-lockfile
pnpm check
pnpm db:migrate:local
pnpm content:push
cp .env.example .dev.vars
# Fill BOT_TOKEN and WEBHOOK_SECRET for a dedicated test bot.
pnpm devpnpm check runs strict TypeScript checks for source and tests, oxlint, oxfmt, schema-copy checks, Vitest, bundling and a Wrangler deploy dry-run; it never deploys remote resources. Every test is a .test.ts file. Vitest verifies SQL, CAS and query conditions against real in-memory SQLite, validates migrations and the database adapter through local Wrangler D1, and exercises the verification flow with a recording fake Bot API and the webhook with a stubbed runtime. Local mocks do not prove live Telegram behavior.
The dev server listens on http://localhost:8787 by default. GET / is a minimal health check; POST /webhook handles Telegram updates and only requests carrying a valid X-Telegram-Bot-Api-Secret-Token enter the verification flow. With --test-scheduled, http://localhost:8787/__scheduled triggers local maintenance manually; this debug route is not part of the deployed public interface. pnpm dev builds before starting; rebuild after source changes. Content changes only need pnpm content:push and take effect without a restart.
- Create an ordinary bot with BotFather and obtain its Bot API token. No Telegram Serverless access is required.
- Log in to Cloudflare and create D1:
pnpm exec wrangler login
pnpm exec wrangler d1 create nyanpasu-group-botCopy the returned database_id into the DB binding in wrangler.jsonc. Keep the database name in sync with the migration scripts.
- Deploy the code. The deploy command applies pending remote D1 migrations before publishing the Worker:
pnpm run deploypnpm run deploy applies pending remote D1 migrations without Wrangler's interactive confirmation, then deploys the Worker; run pnpm check separately when you want the full validation suite. Wrangler still captures a D1 backup and rolls back a migration that fails. D1 may be unavailable while migrations run. If a migration succeeds but Worker deployment later fails, the database stays migrated, so keep migrations compatible with the currently deployed code and use an expand-and-contract rollout for incompatible changes. Upgrading from a version before 0003_admin_targets needs no separate migration command; deploy applies it before publishing code that uses admin_targets.
- Set production secrets:
pnpm exec wrangler secret put BOT_TOKEN
pnpm exec wrangler secret put WEBHOOK_SECRETEnter values interactively. BOT_TOKEN is the ordinary BotFather Bot API token; generate WEBHOOK_SECRET as a random URL-safe string, for example with openssl rand -hex 32. Never put tokens in wrangler.jsonc, source code, command-line arguments or chat logs. .dev.vars is local-only and is not automatically deployed as production secrets.
Optionally set DELETE_JOIN_MESSAGES (true or false, default false in wrangler.jsonc vars) to delete "joined the group" service messages in every group that has not chosen its own deleteJoinMessages setting. The SPAM_* variables set spam filter defaults the same way; see Spam filter. It is not a secret; edit wrangler.jsonc and redeploy, or override it locally in .dev.vars.
- Put the same two values in the ignored
.dev.varsand register the webhook:
pnpm webhook:set https://nyanpasu-group-bot.<your-subdomain>.workers.dev
pnpm webhook:infoThe helper registers /webhook, the four required update types (message, edited_message, callback_query and chat_join_request) and the secret header without dropping pending updates. Rerun pnpm webhook:set after upgrading from a version that did not subscribe to edited_message. A custom HTTPS domain also works. Do not put interactive Cloudflare Access in front of the Telegram webhook.
Then run pnpm commands:set once after deploying. Like pnpm webhook:set, it reads BOT_TOKEN from .dev.vars, and it registers the "/" command menus in English and Chinese (zh) from the descriptions in src/lib/commands.ts. It changes only what Telegram displays, so no webhook change is needed; rerun it when the descriptions change. The menus are not access control: every command still checks the caller's rights.
- Import the question bank into the production D1. The checkout is a normal clone of the private question repository (for example
git clone git@github.com:libnyanpasu/nyanpasu-verify-question.git private-content); it is not part of this repository:
pnpm content:push --remoteContent changes take effect on the next join request without redeploying the Worker. See Content management for push, pull and prune options.
- Complete the group setup below in a dedicated private test group and verify both languages, correct/incorrect answers, the two refreshes, stale buttons, timeout, cooldown, recovery and scheduled cleanup before enabling production groups.
- Add the bot to the private group and promote it to an administrator with the invite-user permission.
- Send
/verify_statusin the group to confirm the content versions and permissions. The reply has a Manage in private chat button that opens the group in a private chat with the bot. - In a private chat with the bot, send
/verify_groupsand tap Choose a group. Telegram offers only groups where you are an administrator with invite-user permission and the bot is a member; the bot checks your rights again before it remembers the group. The selection lasts 24 hours without any command, and each command renews it./verify_groups clearforgets it. - Configure and enable the selected group in the same private chat. No group ID is needed:
/verify_config language=en timeoutSeconds=300 cooldownSeconds=1800
/verify_enable
Sending /verify_config with no options opens a settings panel with buttons for these settings. /verify_status shows the group ID and the active content/rules versions.
- In the private chat, send
/verify_invite(or tap Get invite link in the panel) to obtain an approval-required invite link. The link is returned only in the private chat, never in the group. - Optionally send
/verify_config deleteJoinMessages=onto delete Telegram's "joined the group" service messages. This works independently of/verify_enableand requires the bot's delete-messages permission; the bot warns when that permission is missing.deleteJoinMessages=offkeeps them again, anddeleteJoinMessages=defaultfollows the Worker-wideDELETE_JOIN_MESSAGESvariable (see Deployment). - Optionally enable the spam filter, for example
/verify_config spamMode=new spamFirstMessages=3 spamBan=on spamCas=on. See Spam filter. - Share the approval link and revoke old links that admit users without approval. Other administrators can still bypass verification by direct invitation or manual approval; agree on a process for that.
No public group or group username is required. Admin commands are /verify_help, /verify_status, /verify_config, /verify_enable, /verify_disable and /verify_invite, plus /verify_groups to choose a group in a private chat. In a private chat they act on the selected group, so no group ID is needed; an explicit ID after the command (for example /verify_status -100…) also works and becomes the selection. Inside the group no ID is needed. Every command re-checks administrator rights, and shared IDs and button data are never trusted. Questions and rules are managed through private content, not commands. See Private group setup for details.
The verification deadline runs from the join request; refreshing and /start do not extend it. Answers, rule acceptance and approval intentions are persisted through D1 revision CAS before any Telegram call. Short leases reduce duplicate concurrent work and retry_after drives retries, but no transaction spans D1 and the Bot API, so an ambiguous network outcome cannot guarantee exactly-once external effects.
A per-session Durable Object alarm declines overdue requests, retries unfinished decisions and deletes verification messages after their original deadline, close to the moment each is due. A per-minute Cron Trigger processes a small batch as a backstop for anything a timer missed. API retries can still delay cleanup, and cron changes need time to propagate. The approval cooldown is a bot-side gate, not a Telegram group ban.
The webhook returns 2xx only after processing completes and returns a retryable error when processing fails. Telegram may still deliver updates more than once. Existing sessions keep their private question and rules snapshots across deployments, and /verify_disable only stops new sessions: existing verification and maintenance continue.
D1 stores the group configuration, session snapshots, the content bank, spam blocklists and per-group message counts for the spam filter. The admin_targets table holds only each administrator's user ID, selected group ID and update time; a selection is ignored after 24 hours without a command, and cron maintenance prunes expired rows. Session payloads keep their own question and rules snapshots, so content updates never change in-flight verifications. There is no automatic session-retention cleanup yet, and Workers and D1 free-plan call, CPU and query limits apply; maintenance runs in bounded batches, so consider a queue or a paid plan for busier deployments. See Platform notes.
The filter deletes spam (advertising, scams, funnelling and topics our groups do not host, such as politics) that matches the private blocklist, and can ban senders. It is independent of join verification. Each group configures it with /verify_config; options a group has not set follow Worker-wide defaults from wrangler.jsonc vars:
| Group option | Worker variable | Built-in default | Meaning |
|---|---|---|---|
spamMode=off|new|all |
SPAM_MODE |
off |
new inspects each member's first spamFirstMessages messages; all inspects every message |
spamFirstMessages=N |
SPAM_FIRST_MESSAGES |
3 |
Messages inspected per member in new mode, 1–100. Counts restart when a member rejoins |
spamBan=on|off |
SPAM_BAN |
true |
Ban senders on ban-tier matches and CAS hits; off only deletes, useful for trying out a list |
spamCas=on|off |
SPAM_CAS |
true |
Check a sender's first message against the CAS ban list |
Every group option also accepts default, which clears the group's own value so the Worker variable applies again; /verify_config marks inherited values with "(global default)". Worker variables take true/false (or 1/0); missing or malformed values fall back to the built-in defaults. They are not secrets: edit wrangler.jsonc and redeploy, or override them locally in .dev.vars. Setting SPAM_MODE=all makes every group without its own setting inspect all messages, including deleting political discussion.
A message is checked together with its caption, hidden link targets, inline button labels and URLs, quoted text, forward origin and the sender's names and username. Edited messages are checked again. Before matching, text and blocklist entries are folded the same way: NFKC (full-width, circled and styled characters), lower case, Cyrillic/Greek look-alikes of Latin letters, and removal of everything except letters and digits, so spacing, punctuation, emoji and zero-width characters cannot split a keyword. Traditional Chinese is not converted; list both forms when needed. Messages whose Han characters are mostly separated by spaces (加 微 信 领 钱) are deleted as keyword evasion.
- Ban tier (
ban): delete and ban (banChatMember, orbanChatSenderChatfor channel identities). - Delete tier (
delete) and the spacing rule: delete only. - Administrators, anonymous administrators and automatic forwards from the linked channel are exempt. Admin status is looked up only after a match.
- The bot needs the delete-messages permission, plus ban-users when
spamBan=on;/verify_configwarns about missing rights. Permanent Telegram refusals are ignored, while rate limits and server errors fail the webhook so Telegram retries. newmode starts counting when the filter first sees a member, so existing members are inspected for their next N messages after enabling it.
The blocklist is generated by pnpm blocklist:build (see Blocklist sources) into the content checkout as blocklists/default.json, and synced to D1 with pnpm content:push. It is never part of the Worker bundle, and each Worker isolate caches it for up to a minute.
{
"$schema": "../schemas/blocklist.schema.json",
"version": "2026-10",
"ban": ["example ban phrase", "=example whole message"],
"delete": ["example suspicious phrase"]
}Entries match as substrings after normalization and must keep at least two letters or digits; an entry starting with = must equal a whole text. Keep the ban tier to phrases that do not occur in normal chat. The detection code is our own; its approach draws on tg-spam, xiaomaoJT/TgBot and bayes_spam_sniper.
pnpm blocklist:build fetches the upstream word lists pinned in blocklist/sources.json, applies our curation in blocklist/overrides.json, then normalizes, deduplicates and merges them into <content checkout>/blocklists/default.json. Both files are public so the result can be reviewed and reproduced. Review the generated file, then run pnpm content:push.
pnpm blocklist:build --dry-run # print the merge report only
pnpm blocklist:build # write private-content/blocklists/default.json
pnpm blocklist:build --dir <path> --version 2026-10- Duplicates are merged after normalization, and the stronger tier wins.
- An entry is dropped when a shorter entry of the same or a stronger tier already contains it.
dropremoves entries by reason: insults, common words with a high false-positive risk, and upstream in-jokes. Political terms are kept in the delete tier because our groups do not encourage political discussion. They come from upstream at build time and are never stored in this repository.deletedemotes risky ban-tier entries.addholds our own entries, grouped by category: proxy airport promotion and reseller recruitment, group funnelling, and crypto scams.- Every entry is tested against
safeSamples, normal messages from our groups. An entry that would match one is dropped and reported. Add a sample whenever a false positive shows up.
The merged list currently uses these projects. We thank their authors:
| Project | URL | License | What we use |
|---|---|---|---|
| tg-spam | https://github.com/umputun/tg-spam | MIT | data/stop-words.txt, ban tier |
| xiaomaoJT/TgBot | https://github.com/xiaomaoJT/TgBot | None declared | sensitive_words sheet of XiaoMaoBot_DB.xlsx: column A ban tier, column B delete tier, after curation |
If you are an author of one of these projects and do not want your list used here, please open an issue or contact the maintainers. We will remove your source from blocklist/sources.json and stop distributing the derived entries. The same applies if you would like different attribution.
Questions, rules and pack manifests live in D1 (packs, rules and questions tables) and are edited in a local checkout of the private question repository. The checkout keeps the JSON layout the schemas describe: packs/<id>.json, rules/<id>.json and questions/<type>/<id>.json, plus optional blocklists/<id>.json spam blocklists; a default pack is required. JSON Schemas provide editor completion, and the CLI validates fields, references, unique IDs, answer indexes and bilingual message lengths with the same validator the Worker uses. Rules text is never truncated.
pnpm content:list # show the packs, question types, rules and blocklists in local D1
pnpm content:push # import the checkout into local D1 (upsert)
pnpm content:push --prune # also delete D1 rows that are absent from the checkout
pnpm content:push --remote # import into the production D1 (requires wrangler login)
pnpm content:pull --dir <path> # export D1 content into a directory
pnpm content:pull --dir <path> --force # overwrite existing files in the target directoryLocal D1 is the default target; --remote is required for production. Blocklists are pushed and pulled with the packs, except when push is given explicit pack ids. push upserts only, so pass --prune to mirror deletions, and --dir selects another checkout. pull refuses to overwrite an existing checkout without --force, restores the $schema markers and runs oxfmt so exported files match the checkout format. Invalid banks are rejected before anything is written.
The schemas are kept in sync with the checkout:
pnpm content:schemas
pnpm content:schemas:checkThere is no public content endpoint or static asset binding, and the Worker bundle never contains question content. Never commit content JSON, database dumps or exported banks to this repository.
After table-definition changes, run pnpm db:generate, review the generated migration and apply the remote migration separately.