# Bot Telegram — verifica videobolla

Bot PHP (MAMP-ready) che limita i nuovi membri del gruppo finché non inviano una **videobolla**.  
Pannello admin **solo in Telegram** (`/settings`). Approvazione **manuale / automatica / ibrida**.  
**Multilingua** (IT/EN/ES/DE/FR/RU): `/lang` per gli utenti, 🌐 Lingua bot in `/settings` per il default.

## Setup rapido (anteprima in locale)

### 1. Crea il bot
1. Apri [@BotFather](https://t.me/BotFather) → `/newbot`
2. Copia il **token**
3. Il tuo user id numerico: [@userinfobot](https://t.me/userinfobot)

### 2. Config
```bash
cp config.example.php config.php
```
Modifica `config.php`:
- `bot_token`
- `bot_username` (senza `@`)
- `admin_ids` → il tuo id numerico

### 3. Avvia in polling (anteprima)
Non serve MAMP acceso per testare il bot: basta PHP.

```bash
cd /Applications/MAMP/htdocs/bot
php poll.php
```

**Multi-bot** (token dalla piattaforma, tutti i prodotti):

```bash
php poll_multi.php          # tutti
php poll_multi.php verify   # uno solo
```

Webhook produzione: `php set_webhook_multi.php` → endpoint  
`/platform/public/hooks/bot.php?slug={slug}`

Lascia il terminale aperto. **Telegram stesso è l’anteprima**: scrivi al bot.

### 4. Collega il gruppo
1. Aggiungi il bot al **supergruppo**
2. Rendilo **amministratore** con permesso *Limita membri* (Ban users / Restrict)
3. Nel gruppo scrivi: `/setgroup`
4. In privato col bot: `/settings` → 🏘 Gruppi (se ne hai più di uno)

Puoi ripetere `/setgroup` in altri gruppi: ogni gruppo ha impostazioni, blacklist e VIP **indipendenti**.

### 5. Prova il flusso
1. Entra nel gruppo con un account secondario (non admin)
2. Il bot ti muta e chiede la videobolla in privato (`/start` sul bot se non l’hai mai aperto)
3. Invia una **videobolla** (microfono → scorri in alto)
4. In modalità *manuale* l’admin riceve video + pulsanti Approva/Rifiuta

## Comandi

| Comando | Chi | Cosa fa |
|---------|-----|---------|
| `/start` | tutti | Avvia / riprende verifica |
| `/status` | tutti | Stato verifica e tempo rimasto |
| `/history` | tutti | Storico personale verifiche |
| `/privacy` | tutti | Info dati salvati |
| `/forget` | tutti | Pulisce riferimenti locali e preferenze |
| `/report ID motivo` | tutti | Report privato agli admin |
| `/settings` | admin | Pannello (gruppi, messaggi, ripetuti, warn, sicurezza, …) |
| `/setgroup` | admin | Registra il gruppo corrente (multi-gruppo) |
| `/unsetgroup` | super-admin | Disattiva il gruppo corrente |
| `/pending` | admin | Lista in attesa |
| `/stats` | admin | Contatori |
| `/dashboard` | admin | Statistiche avanzate |
| `/whois ID` | admin | Scheda utente |
| `/note ID testo` | admin | Nota interna |
| `/warn` `/mute` `/ban` `/unban` | admin | Moderazione rapida |
| `/export` `/backup` | super-admin | CSV verifiche e backup SQLite |
| `/help` | tutti | Aiuto |

## Modalità approvazione (`/settings` → Modalità)

- **Manuale** — admin Approva/Rifiuta
- **Automatica** — ok se durata tra min e max
- **Ibrida** — auto-approva e notifica admin (può *Revocare*)

Altre opzioni nel pannello: durata min/max, timeout, notifiche, **messaggi + immagini**, **admin aggiuntivi**, **blacklist**, **filtro link**, **azioni ban/kick**.

Extra implementati: motivi rifiuto, retry post-rifiuto, presa in carico review, approvazione con riserva, confronto con video precedente, reminder timeout, alert picchi ingressi, note interne, whois, dashboard avanzata, export CSV, backup DB, webhook eventi e pannello web read-only `admin_view.php`.

## Admin multipli e notifiche

- **Admin principale** — definito in `config.php` (`admin_ids`), accesso completo
- **Admin aggiunti** — da `/settings` → **👥 Admin** → ➕ (ID numerico o inoltra un messaggio dell'utente)
- **Notifiche videobolla** — tutti gli admin oppure solo quelli aggiunti (toggle nel menu Admin)
- Quando un admin **Approva/Rifiuta**, gli altri ricevono avviso e i pulsanti si disattivano; se provano a cliccare vedono *"Già gestito da …"*

## Messaggi e media

- `/settings` → **💬 Messaggi** — testi di benvenuto, istruzioni, approvato, rifiutato
- `/settings` → **🖼 Media** — assegna/rimuovi una **foto** a ciascun messaggio (invia la foto in privato al bot)
- **👁 Anteprima** — vede testo + immagine come li riceverà l'utente

## Blacklist e ban

- `/settings` → **⛔ Blacklist** — aggiungi/rimuovi/elenco/**svuota tutto** (svuota = solo admin principale)
- `/settings` → **🛡 Ban / azioni** — cosa fare su rifiuto o timeout: nessuna / kick / ban
- opzioni: mettere in blacklist su rifiuto/timeout; se un blacklistato rientra → ban o kick

## Filtro link

- `/settings` → **🔗 Link** — attiva il filtro
- blocca separatamente: invite `t.me/+`, link a canali/`@username`, URL esterni
- azione: elimina / avvisa / mute / kick / ban
- **whitelist** di domini o pezzi di URL ammessi (es. `youtube.com`)

## Sondaggi e parole vietate *(Pro)*

- `/settings` → **📊 Sondaggi** — crea sondaggi con opzioni predefinite/editabili e **durata** (chiusura automatica), anonimi o pubblici, a scelta singola/multipla
- `/settings` → **🚫 Parole vietate** — rimuove i messaggi con parole/frasi in lista (azione: elimina / avvisa / mute / kick / ban); parola singola = match a parola intera, frase = sottostringa

## Produzione (webhook HTTPS)

Con dominio HTTPS (o tunnel tipo ngrok):

```bash
php set_webhook.php https://TUO-DOMINIO/bot/webhook.php
```

Poi non usare `poll.php` (webhook e polling non insieme).

## Requisiti
- PHP 8.1+ con estensioni `curl`, `pdo_sqlite`, `json`
- Bot admin nel gruppo con permesso di restringere i membri

## Documentazione

| File | Per chi |
|------|---------|
| [docs/GUIDA_UTENTI.md](docs/GUIDA_UTENTI.md) | Membri del gruppo (come verificarsi, qualità video) |
| [docs/GUIDA_ADMIN.md](docs/GUIDA_ADMIN.md) | Admin (setup, pannello, go-live) |
| [docs/SICUREZZA.md](docs/SICUREZZA.md) | Super-admin (tutti i moduli 🔐) |

In Telegram: `/guida` mostra l’indice.

## Note
- Gli utenti devono aver fatto `/start` al bot per ricevere i DM; altrimenti il bot posta un link nel gruppo.
- SQLite in `storage/bot.sqlite` (zero config MySQL).
- Log: `storage/logs/bot.log`
- Il bot **non** analizza automaticamente scuro/sfocato: le note guidano la review umana.