中文说明 | English
A configurable Telegram public-group verification bot running on Google Cloud Run. New members can join the public group immediately, but are muted until they join a required channel. They have three minutes to verify; otherwise Cloud Tasks removes them from the group without permanently banning them.
- Public group remains searchable and directly joinable.
- New members are muted immediately.
- Required channel, group name, channel name, timeout, and welcome message are configurable.
- Verification buttons are bound to the target user.
- Successful verification restores the group's default permissions.
- Users who joined the channel but forgot to click are accepted by the deadline check.
- Expired users are removed but may rejoin later.
- Welcome message supports up to eight configurable HTTPS buttons, two per row.
- Firestore stores pending verification state.
- Cloud Tasks provides reliable delayed expiry even when Cloud Run scales to zero.
- Telegram webhook and task endpoint use independent secrets.
- A user joins the public supergroup.
- The bot receives
chat_memberand mutes the user. - Existing channel members are restored and welcomed immediately.
- Other users see Join Official Channel and I joined, verify now buttons.
- A successful button check restores permissions, removes the prompt, and sends the custom welcome message.
- At three minutes, Cloud Tasks checks once more. Channel members pass; others are removed.
Set WELCOME_TEXT to any Telegram HTML message up to 3,500 characters. The following placeholders are replaced at runtime:
| Placeholder | Value |
|---|---|
{user} |
Clickable Telegram user mention |
{group} |
Escaped GROUP_NAME |
{channel} |
Escaped CHANNEL_NAME |
Example:
🎉 Welcome {user} to <b>{group}</b>!
Please read the rules and join {channel}. Be respectful and do not post spam.
The operator controls this trusted template. Use only Telegram-supported HTML tags.
- Node.js 22 or newer for local tests.
- A billed Google Cloud project.
- Google Cloud CLI.
- A Telegram bot.
- A public Telegram supergroup with Approve New Members disabled.
- The bot must be a group administrator with Delete messages and Restrict/Ban users.
- The bot must be an administrator of the required channel.
See the English beginner deployment guide for all steps.
Set-ExecutionPolicy -Scope Process Bypass -Force
$welcome = @'
🎉 Welcome {user} to <b>{group}</b>!
Please read and follow the community rules. Be respectful and do not post spam, scams, or illegal content.
'@
.\tools\deploy-cloud-run.ps1 `
-ProjectId "your-google-cloud-project-id" `
-Region "us-central1" `
-GroupChatId "-1001234567890" `
-RequiredChannelId "@your_channel" `
-RequiredChannelUrl "https://t.me/your_channel" `
-GroupName "Your Community" `
-ChannelName "Official Channel" `
-WelcomeText $welcome `
-Link1Label "Channel" -Link1Url "https://t.me/your_channel" `
-Link2Label "Website" -Link2Url "https://example.com"The script creates or configures Cloud Run, Firestore, Cloud Tasks, Secret Manager, a least-privilege service account, and the Telegram webhook. Link pairs 1 through 8 are supported; omit unused pairs.
| Variable | Required | Purpose |
|---|---|---|
BOT_TOKEN |
Yes | Telegram bot token; use Secret Manager |
WEBHOOK_SECRET |
Yes | Telegram webhook header secret |
TASK_SECRET |
Yes | Cloud Tasks endpoint secret |
GROUP_CHAT_ID |
Yes | Target supergroup ID (-100...) |
GROUP_NAME |
No | {group} value; defaults to Community Group |
REQUIRED_CHANNEL_ID |
Yes | Channel @username or numeric ID |
REQUIRED_CHANNEL_URL |
Yes | HTTPS channel URL |
CHANNEL_NAME |
No | {channel} value; defaults to Official Channel |
WELCOME_TEXT |
No | Custom HTML template |
VERIFY_TIMEOUT_SECONDS |
No | 60–900; defaults to 180 |
GCP_PROJECT_ID |
Yes | Google Cloud project ID |
TASKS_LOCATION |
Yes | Cloud Tasks region |
TASKS_QUEUE |
No | Queue name |
TASK_TARGET_URL |
Production | Cloud Run URL; deployment script fills it |
FIRESTORE_COLLECTION |
No | Pending-state collection |
LINK_1_LABEL ... LINK_8_LABEL |
No | Welcome button labels |
LINK_1_URL ... LINK_8_URL |
No | Matching HTTPS URLs |
npm ci
npm test
npm run checkTests use in-memory fakes and do not contact Telegram or Google Cloud.
- A direct-join public group has a short race between Telegram accepting the member and the webhook muting them. Enable Telegram's native aggressive anti-spam feature as an additional layer.
- Channel membership raises the cost of generic spam automation but is not an unbreakable human CAPTCHA. A targeted userbot may still join the channel and press the button.
- Google Cloud free tiers have limits and a billing account can incur overage. Configure budget alerts.
MIT