Add README.md
This commit is contained in:
parent
48b6ea0da0
commit
f1efc1d937
1 changed files with 301 additions and 0 deletions
301
README.md
Normal file
301
README.md
Normal file
|
|
@ -0,0 +1,301 @@
|
|||
# Telegram Join Approval Bot
|
||||
|
||||
A Telegram bot for managing and approving join requests to private groups with approval workflows, canned responses, and admin controls.
|
||||
|
||||
## Overview
|
||||
|
||||
This bot automates the process of approving new members joining a private Telegram group. When a user requests to join, the bot:
|
||||
1. Sends them a prompt to explain why they want to join
|
||||
2. Forwards their request to the admin chat with approve/decline/ban buttons
|
||||
3. Allows admins to manage requests with customizable decline reasons
|
||||
4. Notifies users of the approval decision
|
||||
|
||||
## Features
|
||||
|
||||
- **Automated Join Requests**: Intercepts and manages join requests to your target group
|
||||
- **Admin Approval Workflow**: Approve, decline, or ban users with a single click
|
||||
- **Join Reason Collection**: Users must provide a reason before their request reaches admins
|
||||
- **Canned Responses**: Pre-configured decline messages for common rejection reasons
|
||||
- **Flexible Admin Interface**:
|
||||
- Approve, decline, or ban users
|
||||
- Add custom decline reasons
|
||||
- Configure bot messages and settings
|
||||
- Organize requests in topic threads
|
||||
- **Approval Notifications**: Optional message sent to approved users
|
||||
- **Configurable Messages**: Customize entry and approval messages
|
||||
- **User Banning**: Ban users for 24 hours with a single action
|
||||
|
||||
## How It Works
|
||||
|
||||
### Join Request Flow
|
||||
|
||||
```
|
||||
User requests to join group
|
||||
↓
|
||||
Bot sends entry prompt to user
|
||||
↓
|
||||
Bot notifies admins with join request
|
||||
(showing user info and join reason placeholder)
|
||||
↓
|
||||
User sends their join reason
|
||||
(message to bot in private chat)
|
||||
↓
|
||||
Bot updates admin message with user's reason
|
||||
↓
|
||||
Admin clicks Approve/Decline/Ban
|
||||
↓
|
||||
User notified of decision (if configured)
|
||||
↓
|
||||
User added/rejected/banned from group
|
||||
```
|
||||
|
||||
### Architecture
|
||||
|
||||
The bot consists of several key components:
|
||||
|
||||
#### Main Entry Point (`main.go`)
|
||||
- Initializes the bot with config from `config.yaml`
|
||||
- Starts the long polling update loop
|
||||
- Routes updates to appropriate handlers
|
||||
|
||||
#### Configuration (`config/config.go`)
|
||||
- Loads settings from `config.yaml`
|
||||
- Auto-generates template config if missing
|
||||
- Supports hot-reloading configuration changes
|
||||
|
||||
#### Handlers
|
||||
- **`join.go`**: Manages join request flow and user responses
|
||||
- **`callbacks.go`**: Handles inline button actions (approve/decline/ban)
|
||||
- **`admin.go`**: Processes admin commands for configuration
|
||||
- **`handlers.go`**: Shared types and utilities
|
||||
|
||||
#### Key Data Structures
|
||||
|
||||
```go
|
||||
// ExtendedChatJoinRequest tracks a user's approval request
|
||||
type ExtendedChatJoinRequest struct {
|
||||
*ChatJoinRequest // Telegram join request
|
||||
JoinReason string // User's explanation
|
||||
JoinRequestMessageID int // Admin notification message ID
|
||||
}
|
||||
|
||||
// Bot maintains runtime state
|
||||
type Bot struct {
|
||||
API BotAPI // Telegram API client
|
||||
Config Config // Configuration
|
||||
WaitingForApproval map // In-memory user request tracking
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The bot reads from `config.yaml` in its working directory. On first run, it creates a template:
|
||||
|
||||
```yaml
|
||||
bot_token: "YOUR_BOT_TOKEN_HERE" # @BotFather token
|
||||
admin_chat_id: 0 # Chat ID where admins review requests
|
||||
admin_chat_topic_id: 0 # Optional: Topic ID in admin chat (0 = main)
|
||||
target_chat_id: 0 # Private group to protect
|
||||
entry_message: "Please explain why..." # Prompt shown to joining users
|
||||
approval_message: "" # Message sent after approval (optional)
|
||||
send_approval_message: false # Whether to send approval message
|
||||
delete_request_after_decision: false # Auto-delete admin messages after decision
|
||||
canned_decline_responses: # Pre-configured decline reasons
|
||||
- "Your profile doesn't meet our criteria"
|
||||
- "We're at capacity"
|
||||
```
|
||||
|
||||
### Getting Required IDs
|
||||
|
||||
**Bot Token**: Create a bot with [@BotFather](https://t.me/botfather)
|
||||
|
||||
**Chat IDs**:
|
||||
```bash
|
||||
# Forward a message from the chat to @getidsbot
|
||||
# It will show you the chat ID
|
||||
```
|
||||
|
||||
## Admin Commands
|
||||
|
||||
Admins can use these commands in the admin chat:
|
||||
|
||||
### `/setentrymessage <message>`
|
||||
Change the message shown when users request to join.
|
||||
|
||||
```
|
||||
/setentrymessage Tell us about yourself and why you want to join!
|
||||
```
|
||||
|
||||
### `/setapprovalmessage <message>`
|
||||
Set a message sent to approved users. Must be set before enabling approval notifications.
|
||||
|
||||
```
|
||||
/setapprovalmessage Welcome to our group! We're excited to have you.
|
||||
```
|
||||
|
||||
### `/togglesendapproval`
|
||||
Enable/disable sending the approval message to approved users.
|
||||
|
||||
### `/setadmintopic <topic_id>`
|
||||
Direct admin messages to a specific topic thread (0 = main chat).
|
||||
|
||||
```
|
||||
/setadmintopic 42
|
||||
```
|
||||
|
||||
### `/info`
|
||||
Display current bot configuration.
|
||||
|
||||
### `/edit <new_text>`
|
||||
Reply to a message and use this to edit it. Useful for correcting admin notifications.
|
||||
|
||||
```
|
||||
/edit User was banned incorrectly
|
||||
```
|
||||
|
||||
## Approval Workflow
|
||||
|
||||
### Admin Actions
|
||||
|
||||
When a user requests to join, an admin sees:
|
||||
|
||||
```
|
||||
New join #request from @username [123456789]
|
||||
|
||||
Join reason: "I'm interested in this community"
|
||||
```
|
||||
|
||||
With inline buttons:
|
||||
- **Approve** - Add user to group, optionally send approval message
|
||||
- **Decline** - Reject request, show decline reason button panel
|
||||
- **Ban** - Ban user for 24 hours (shows confirmation)
|
||||
|
||||
### Decline Responses
|
||||
|
||||
When declining with canned responses configured:
|
||||
|
||||
1. Admin clicks **Decline**
|
||||
2. Message shows available canned responses as buttons
|
||||
3. Admin clicks a canned response
|
||||
4. User receives the selected reason
|
||||
5. Admin message updates with the reason
|
||||
|
||||
Or, admin can reply to a decline message with custom text (with or without `/` prefix):
|
||||
|
||||
```
|
||||
[Reply to decline message]
|
||||
/We can only accept members with 2+ years experience
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Docker
|
||||
|
||||
Build and run the container:
|
||||
|
||||
```bash
|
||||
docker build -t telegram-approval-bot .
|
||||
docker run -it \
|
||||
--mount type=bind,source=$PWD/config.yaml,target=/opt/config.yaml \
|
||||
telegram-approval-bot
|
||||
```
|
||||
|
||||
The Dockerfile:
|
||||
- Builds a static binary with minimal dependencies
|
||||
- Uses Alpine for small image size
|
||||
- Runs as unprivileged user (UID 65532)
|
||||
- Mounts config as a volume for persistence
|
||||
|
||||
### Compose Example
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
services:
|
||||
bot:
|
||||
build: .
|
||||
volumes:
|
||||
- ./config.yaml:/opt/config.yaml
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### State Management
|
||||
|
||||
Join requests are tracked in memory using a mutex-protected map:
|
||||
|
||||
```go
|
||||
WaitingForApproval map[int64]*ExtendedChatJoinRequest
|
||||
```
|
||||
|
||||
When a user provides their join reason, the bot:
|
||||
1. Updates the request with their reason
|
||||
2. Edits the admin message to show the reason
|
||||
3. Keeps the message indexed by message ID for button handling
|
||||
|
||||
### Update Processing
|
||||
|
||||
The bot receives Telegram updates via long polling:
|
||||
|
||||
1. **ChatJoinRequest**: User requests to join → calls `HandleJoinRequest`
|
||||
2. **CallbackQuery**: Admin clicks button → calls `HandleCallbackQuery`
|
||||
3. **Message**: User sends reason or admin command → routes accordingly
|
||||
|
||||
### Message Formatting
|
||||
|
||||
Admin notifications use HTML formatting with:
|
||||
- User display name with link
|
||||
- Numeric user ID
|
||||
- Join reason (HTML-escaped for safety)
|
||||
- Admin action history
|
||||
- Timestamp information
|
||||
|
||||
### Error Handling
|
||||
|
||||
- Failed API requests restore the original message
|
||||
- Missing user state after restart shows helpful error
|
||||
- Invalid callback data is logged without crashing
|
||||
|
||||
## Development
|
||||
|
||||
### Dependencies
|
||||
|
||||
- `github.com/OvyFlash/telegram-bot-api` - Telegram Bot API client
|
||||
- `go.yaml.in/yaml/v3` - YAML configuration parsing
|
||||
|
||||
### Go Version
|
||||
|
||||
Requires Go 1.25.3+
|
||||
|
||||
### Building Locally
|
||||
|
||||
```bash
|
||||
go build -o telegram-approval-bot ./...
|
||||
./telegram-approval-bot
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bot doesn't respond to join requests
|
||||
- Verify `target_chat_id` is correct
|
||||
- Check bot has admin rights in the target group
|
||||
- Ensure bot is configured to receive join request updates
|
||||
|
||||
### Admin messages don't appear
|
||||
- Verify `admin_chat_id` is correct
|
||||
- Check bot has message permission in admin chat
|
||||
- If using topics, verify `admin_chat_topic_id` is set
|
||||
|
||||
### Approve/Decline buttons don't work
|
||||
- Bot needs admin rights in target group
|
||||
- Join request may have expired (Telegram timeout)
|
||||
- Check logs for API errors
|
||||
|
||||
### Config changes don't apply
|
||||
- Some changes require bot restart
|
||||
- Use `/info` to verify current settings
|
||||
- Check config.yaml for syntax errors
|
||||
|
||||
## License
|
||||
|
||||
[Specify your license here]
|
||||
Loading…
Add table
Add a link
Reference in a new issue