# Telegram Private Channel Join-Request Bot

Production-ready PHP bot for **PRIVATE Telegram channels** with **Join Request** mode enabled.  
Ye bot public/open channel join ke liye nahi hai — sirf private channel + approve-new-members flow ke liye design kiya gaya hai.

---

## Bot kya karta hai?

1. User private channel par **join request** bhejta hai  
2. Bot turant user ko **private DM** bhejne ki koshish karta hai (welcome + GET BONUS button)  
3. Bot join request **auto approve** karta hai (`approveChatJoinRequest`)  
4. User funnel follow karta hai: bonus photo → READY button → timed follow-ups → `/start`  
5. Duplicate messages prevent hote hain (idempotency + DB locks)  
6. Laptop band hone ke baad bhi bot **server/cPanel cron** par chalta rahega

---

## Public join vs Private join-request

| Feature | Public Channel | Private + Join Request |
|---------|----------------|------------------------|
| Join type | Direct join / link | User request bhejta hai, admin/bot approve karta hai |
| Bot DM without /start | ❌ Usually nahi | ✅ Join-request context mein limited window |
| Approve method | N/A | `approveChatJoinRequest` |
| Ye bot | ❌ Not for this | ✅ Built for this |

---

## ⚠️ Telegram Limitations (IMPORTANT)

Telegram ke rules ke mutabik:

- Bot user ko **join request ke context** mein bina `/start` ke message kar sakta hai  
- Ye **limited time window** hoti hai — practical docs mein ~**5 minutes** mention hota hai  
- Agar cron **slow** hai ya request **late process** hoti hai, welcome DM **fail** ho sakta hai  
- Join-request window ke baad normal unlimited messaging **guaranteed nahi** hai  
- Isliye **fast polling cron** (har 1 minute) strongly recommended hai  

**Bot sequence (safest practical approach):**

```
detect join request → save state → send DM → approve request
```

Agar `approve_even_if_dm_fails = yes` (default): DM fail hone par bhi user approve ho jayega.  
Agar `no`: DM fail par request hold rahegi (manual review possible).

Follow-up messages (10s / 5s delays) tab bheje jate hain jab user ne pehle hi bot se interact kiya ho (button click), isliye ye Telegram limits ke andar safe rehte hain.

---

## Requirements

- **PHP 8.0+** (CLI + cURL + PDO MySQL)
- **MySQL 5.7+** / MariaDB
- **cPanel** ya koi bhi hosting jahan cron + PHP CLI available ho
- **Webhook NAHI** — sirf `getUpdates` polling

---

## Step 1: BotFather se token

1. Telegram mein [@BotFather](https://t.me/BotFather) open karo  
2. `/newbot` → name + username do  
3. Token copy karo (example: `123456789:AAH...`)  
4. Bot username note karo  

---

## Step 2: Private channel banana

1. Telegram → New Channel → **Private** select karo  
2. Channel name set karo  
3. Channel link/username note karo (`@your_channel` ya `-100xxxxxxxxxx`)

---

## Step 3: Join Request mode enable

1. Channel → Edit → **Channel Type**  
2. **Approve New Members** ON karo  
3. Ab users direct join nahi kar sakte — request bhejenge  

---

## Step 4: Bot ko admin banana

1. Channel → Administrators → Add Administrator  
2. Apna bot select karo  
3. Required permissions:
   - ✅ **Invite Users** / Manage join requests  
   - ✅ Post messages (optional, funnel ke liye zaruri nahi)  

Bot ko admin hone ke bina `approveChatJoinRequest` kaam nahi karega.

---

## Step 5: Files upload (cPanel)

1. cPanel → **File Manager**  
2. Folder banao: `public_html/bot/` (ya apna path)  
3. Upload karo:
   - `mybot.php`
   - `install.php`
   - `readme.md`
   - `cron.txt`
4. Folder permission **755**, files **644**  

---

## Step 6: install.php run karo

Browser mein open karo:

```
https://yourdomain.com/bot/install.php
```

Form fill karo:
- Database details (cPanel → MySQL Databases se banao)
- Bot token, username
- Private channel ID/username
- Admin contact: `Anita_Desai_here`
- Timezone: `Asia/Kolkata`
- `approve_even_if_dm_fails`: **Yes** (recommended)

Install success ke baad `config.php` auto-generate hoga.

**Security:** `install.php` delete kar do ya `.htaccess` se protect karo.

---

## Step 7: Cron Jobs setup (cPanel)

cPanel → **Advanced** → **Cron Jobs**

### Recommended (fast polling):

```
* * * * * /usr/local/bin/php -q /home/USERNAME/public_html/bot/mybot.php poll >/dev/null 2>&1
* * * * * /usr/local/bin/php -q /home/USERNAME/public_html/bot/mybot.php queue >/dev/null 2>&1
*/10 * * * * /usr/local/bin/php -q /home/USERNAME/public_html/bot/mybot.php cleanup >/dev/null 2>&1
```

`USERNAME` aur path apne account ke hisaab se change karo. Full examples: `cron.txt`

### PHP path kaise pata karein?

cPanel → **Select PHP Version** → "PHP CLI" path dekho, ya SSH par:

```bash
which php
```

Alternate paths:
- `/usr/local/bin/php`
- `/usr/bin/php`
- `/opt/cpanel/ea-php81/root/usr/bin/php` (ea-php81 = PHP 8.1)

### Cron email spam avoid

Output redirect use karo: `>/dev/null 2>&1`

---

## Step 8: Test karna

### Manual poll test (SSH / cPanel Terminal):

```bash
cd /home/USERNAME/public_html/bot
php mybot.php poll
php mybot.php queue
```

### Live test flow:

1. Test account se private channel par **join request** bhejo  
2. 1-2 minute wait karo (cron interval)  
3. Check karo:
   - Welcome DM aaya?
   - Request approve hui?
   - GET BONUS button kaam karta hai?
   - READY BELOW click → contact message
   - No click → 10s reminder → 5s baad 4 images
   - `/start` → contact message + funnel band

### Debug logs:

`debug_mode = yes` set karo install time par, phir dekho:

```
bot/logs/bot.log
```

---

## Bot commands (CLI)

| Command | Kaam |
|---------|------|
| `php mybot.php poll` | Telegram updates fetch + process |
| `php mybot.php queue` | Scheduled follow-up messages |
| `php mybot.php cleanup` | Stale locks + old logs clean |

---

## Funnel flow summary

```
Join Request
    ↓
Welcome DM + 🎁 GET BONUS
    ↓
Approve join request
    ↓
User clicks GET BONUS → Bonus photo + READY BELOW
    ↓
┌─ READY BELOW clicked → Contact message → DONE
└─ Not clicked (10s) → Reminder photo
         ↓ (5s later)
    4 images + /START prompt
         ↓
    User sends /START → Contact message → DONE
```

---

## Database tables

Installer auto-create karta hai:

- `users` — Telegram users
- `join_requests` — join request tracking
- `user_states` — funnel state machine
- `message_queue` — delayed messages (10s, 5s)
- `sent_logs` — duplicate prevention (unique user+step)
- `bot_settings` — editable messages/settings
- `bot_updates_log` — processed update_id tracking
- `process_locks` — cron overlap prevention
- `failed_jobs` — failed queue jobs

---

## Messages edit kaise karein?

`bot_settings` table mein values update karo (phpMyAdmin):

| Key | Description |
|-----|-------------|
| `welcome_text` | Welcome DM text |
| `btn_get_bonus` | GET BONUS button text |
| `bonus_image_url` | Step 2 image |
| `bonus_photo_caption` | Step 2 caption |
| `btn_ready_below` | READY button text |
| `contact_message_text` | Use `{contact}` placeholder |
| `admin_contact_username` | e.g. Anita_Desai_here |
| `reminder_image_url` | Step 3B image |
| `reminder_caption` | Step 3B caption |
| `final_offer_text` | Step 4 text (first image caption) |
| `final_offer_images` | JSON array of 4 image URLs |
| `delay_reminder_seconds` | Default: 10 |
| `delay_final_offer_seconds` | Default: 5 |
| `approve_even_if_dm_fails` | true / false |

---

## Common issues & fixes

### User ko DM nahi gaya

- Cron slow hai → har 1 minute poll set karo  
- Join request 5+ minute purani ho gayi → window expire  
- Bot token galat hai → install.php dubara check karo  
- User ne bot block kiya ho  

### Request approve nahi hui

- Bot channel admin nahi hai  
- `Invite Users` / join request permission missing  
- `approve_even_if_dm_fails = no` aur DM fail hua  

### Duplicate messages

- Same cron do baar overlap → locks handle karte hain  
- Agar duplicate dikhe: `sent_logs` check karo, `process_locks` stale to nahi  
- `cleanup` cron chalao  

### Callback button kaam nahi kar raha

- `poll` cron running hona chahiye  
- Bot blocked/unstarted ho to join-request context ke baad issue ho sakta hai  
- `bot_updates_log` mein callback update process hua ya nahi dekho  

### Cron run nahi ho raha

- PHP path galat → `which php` se sahi path lo  
- File path galat → absolute path use karo  
- cPanel cron email check karo errors ke liye (phir redirect lagao)  

### getUpdates offset issue

- Kabhi manually webhook set na karo (conflict)  
- `bot_settings.last_update_id` reset mat karo unless necessary  
- Agar updates atke: BotFather `/deleteWebhook` (webhook use nahi kar rahe, par safe)  

---

## Laptop band hone par bot chalega?

**Haan** — jab tak:

- Hosting/server **active** hai  
- **Cron jobs** sahi configured hain  
- Database accessible hai  

Cron **server par** chalta hai, aapke laptop par nahi. Laptop band = koi problem nahi.

---

## Hosting recommendation

- **Best:** VPS (fast cron, full control)  
- **Workable:** cPanel shared hosting (1-minute cron, slight DM delay risk)  
- Shared hosting par **per-second cron guaranteed nahi** — join-request DM success cron timing par depend karta hai  

---

## Security notes

- `config.php` mein token hai — public access block karo  
- `install.php` install ke baad hata do  
- `logs/` folder web se protect karo  
- Prepared statements use hote hain (SQL injection safe)  

---

## File list

| File | Purpose |
|------|---------|
| `mybot.php` | Main bot logic (poll/queue/cleanup) |
| `install.php` | Browser installer + DB setup |
| `config.php` | Auto-generated (install ke baad) |
| `readme.md` | Documentation |
| `cron.txt` | Cron examples |

---

Made for private channel join-request automation · PHP 8+ · No webhook · Cron polling