Bot Telegramper Svogliati
Un programma che ti scrive quando il disco è pieno, ti chiede conferma prima di fare qualcosa e risponde ai comandi dal telefono. Senza aprire una porta, senza app da pubblicare, con una sola chiamata HTTPS.
"Il token è nel codice, ma tanto il repo è privato." — ultime parole famose, poco prima di un bot che manda spam in tre lingue.
Come è nato (due fratelli e un social network)
Un'app di messaggi nata per non farsi leggere le chat, che dopo due anni ha aperto la porta ai programmi. E i sistemisti l'hanno trasformata in un cercapersone.
Pavel Durov nel 2006 fonda VKontakte, il "Facebook russo". Quando le pressioni per consegnare i dati degli utenti diventano troppe, lui e il fratello Nikolai, matematico, decidono di costruire un sistema di messaggi che non debba fidarsi di nessuno. Nikolai scrive il protocollo, MTProto; Pavel mette i soldi e la faccia. Il risultato è un'app veloce, con le chat salvate nel cloud e sincronizzate su tutti i dispositivi. E con un dettaglio che a noi interessa più di tutto: un'API per i bot semplice come una pagina web.
Esce Telegram
Prima su iPhone, poi Android. Le chat normali sono cifrate tra app e server (non da un capo all'altro); per la cifratura end-to-end ci sono le chat segrete, solo uno a uno e solo sul dispositivo dove le apri.
Durov lascia la Russia
Perde il controllo di VKontakte e se ne va. Telegram negli anni cambia sede più volte e oggi sta a Dubai.
Arrivano i bot
Nasce la Bot API e con lei @BotFather, il bot che crea i bot. Basta una richiesta HTTPS con un token: niente librerie, niente protocollo proprietario.
I canali
Chat a senso unico: chi amministra scrive, gli iscritti leggono. Un bot amministratore può pubblicare al posto tuo. Il canale automatico è nato qui.
Bot inline e pulsanti
Si può chiamare un bot da qualunque chat scrivendo @nomebot, e i messaggi possono avere pulsanti sotto. Da qui nascono i bot che chiedono "confermi?" e aspettano il tuo tocco.
Il blocco russo e i proxy
La Russia prova a bloccare Telegram, bloccando milioni di indirizzi IP (e mezzo internet con loro). Telegram risponde con il supporto ai proxy nelle app, compreso MTProxy. Nel 2020 il blocco viene tolto: non aveva mai funzionato davvero.
Il server Bot API diventa open source
Con la Bot API 5.0 si può far girare telegram-bot-api sul proprio server: file fino a 2 GB e niente limiti di download. Ne parliamo nella sezione 12.
Mini app, Stars e l'arresto
Nel 2022 i bot possono aprire vere pagine web dentro l'app (Mini App); nel 2024 arrivano le Stars per i pagamenti. Ad agosto 2024 Durov viene fermato in Francia; poco dopo Telegram aggiorna l'informativa: su richiesta valida delle autorità può consegnare indirizzo IP e numero di telefono. Tienilo a mente quando leggi "privacy".
Un miliardo di utenti
E un numero imprecisato di bot che ti avvisano che il backup è fallito. Il nostro preferito.
Perché un sistemista vuole un bot
Perché il telefono ce l'hai sempre in tasca, l'email la leggi il lunedì e la console di monitoraggio non la apri mai.
Notifiche
Disco pieno, certificato in scadenza, servizio caduto, backup fallito, login SSH strano. Una riga di curl e arriva sul telefono in un secondo.
Comandi a distanza
/stato, /uptime, /riavvia_nginx. Senza VPN, senza SSH dal telefono, senza aprire porte. Con tutte le cautele della sezione 11.
Approvazioni
Il bot prepara qualcosa e ti chiede "pubblico?" con due pulsanti. Tu tocchi ✅ o ❌ dal divano. Automazione sì, ma con il freno a mano.
Canali automatici
Il bot pubblica da solo in un canale: offerte, stato dei servizi, nuove versioni, avvisi a un gruppo di utenti.
Casa
Allarme, sensori, la caldaia, il Raspberry che controlla la rete. Il bot è il telecomando di tutto quello che non ha un'app decente.
Costa zero
Nessun abbonamento, nessun SMS a pagamento, nessun server di notifiche da mantenere. Ti serve solo un'uscita su internet sulla porta 443.
curl, sai già usare un bot Telegram. Il resto della guida serve a non farti male.
Quando sì, quando no
Telegram è comodissimo. Non è cifrato end-to-end per i bot, non è tuo e può non esserci. Tre cose da sapere prima di affidargli qualcosa.
Un bot Telegram va bene per
- Notifiche di servizio: allarmi, report, scadenze
- Comandi semplici e ben delimitati verso i tuoi server
- Conferme umane prima di un'azione automatica
- Canali e gruppi con contenuti pubblici
- Progetti personali e piccoli team
- Quando non vuoi gestire un server di notifiche tuo
Meglio di no per
- Password, chiavi, dati personali o sanitari: Telegram li vede in chiaro
- L'unico canale di allarme per cose critiche: se Telegram è giù o bloccato, sei al buio
- Shell remota "che esegue quello che scrivo": prima o poi la esegue per qualcun altro
- Aziende con obblighi di conformità sui dati (GDPR, settori regolati)
- Quando ti serve la prova di consegna e lettura
| Strumento | Pro | Contro |
|---|---|---|
| Bot Telegram | Gratis, istantaneo, pulsanti, gruppi e canali, API semplicissima | Server di terzi, niente end-to-end per i bot, serve un account con numero di telefono |
| Universale, archiviabile, la ricevono tutti | Lenta da leggere, finisce nello spam, inviarla bene (SPF/DKIM) è un mestiere | |
| ntfy / Gotify | Self-hosted, semplice come un curl, nessun account | Un server in più da tenere vivo; senza Google su Android la notifica push dipende dal tuo server |
| Matrix | Federato, self-hosted, end-to-end anche per i bot (con fatica) | Server pesante, bot più complicati, cifratura che a volte si rompe |
| Signal (signal-cli) | Cifratura end-to-end vera | Nessuna API ufficiale per i bot, serve un numero dedicato, fragile |
| Slack / Discord webhook | Comodi se il team vive già lì | Server di terzi pure loro, limiti sui piani gratuiti |
| SMS | Arriva anche senza dati | Costa, è lento, e lo legge anche l'operatore |
Come funziona davvero
Il tuo bot non parla con le persone. Parla con un server di Telegram, che fa da ufficio postale. Capito questo, il resto è burocrazia.
Il bot ha una casella postale presso l'ufficio postale di Telegram (api.telegram.org). Quando qualcuno scrive al bot, il messaggio finisce nella casella, non sul tuo server. Tu hai due scelte: andare tu a ritirare la posta ogni tanto (polling: "ci sono lettere per me?") oppure lasciare l'indirizzo di casa e farti portare la posta dal postino (webhook: Telegram chiama un tuo URL). Per spedire, invece, vai sempre tu allo sportello: "mandate questo messaggio a questa chat". Il token è il documento che mostri allo sportello: chi ce l'ha, ritira e spedisce a nome tuo.
📱 Tu (app Telegram)
│ MTProto, cifrato fino ai server di Telegram
▼
☁️ Data center Telegram ── conservano le chat (cloud)
│
▼
🏤 Bot API server (api.telegram.org)
▲ │
│ HTTPS │ HTTPS (solo se usi il webhook)
│ JSON ▼
🖥️ Il tuo bot, sul tuo server
• polling: "getUpdates?" → riceve la posta
• webhook: Telegram fa POST su https://tuoserver/...
• invio: "sendMessage" → Telegram consegna
È il bot che chiama
Con il polling il tuo server apre solo connessioni in uscita verso la porta 443. Nessuna porta aperta, nessun IP pubblico, funziona anche dietro NAT, dietro CGNAT, su un Raspberry in cantina.
Il token è il bot
Non esiste una password in più. Chi ha il token legge i messaggi in arrivo, scrive a nome del bot e pubblica nei tuoi canali. Trattalo come una chiave privata SSH.
Il bot vede solo quello che gli arriva
Non legge la tua rubrica, non vede le altre chat, non può scrivere per primo a chi non lo ha mai avviato. Nei gruppi, di default, vede solo i comandi e le risposte ai suoi messaggi.
🔐 Chi vede cosa
- Tra app e Telegram il traffico è cifrato con MTProto. Tra Telegram e il tuo bot è HTTPS normale.
- Telegram vede tutto in chiaro: i messaggi a un bot, come quelli dei gruppi e delle chat normali, sono salvati sui suoi server. I bot non possono usare le chat segrete.
- Il tuo server vede solo i messaggi indirizzati al bot, più il nome, l'username e l'id numerico di chi scrive. Niente numero di telefono, a meno che l'utente non lo condivida apposta.
Creare il bot con @BotFather
Un bot che crea i bot. Due minuti di chat e hai un token. Poi altri cinque per sistemare quello che hai dimenticato.
🧔 I passi
- Apri Telegram e cerca @BotFather, quello con la spunta blu. Diffida delle imitazioni.
- Scrivi
/newbot. - Dagli un nome visibile, che puoi cambiare quando vuoi (es. "Allarmi Casa").
- Dagli uno username: unico, deve finire con
bot(es.allarmi_casa_bot). Questo invece resta quello. - BotFather ti risponde con il token. Copialo subito in un file con permessi stretti, non in una chat e non nel codice.
7123456789:AAF3x_finto-finto-finto_kQ9zVb2LmN0pQr
└── id del bot ┘ └──────── la parte segreta ────────┘
# la prima parte è pubblica (è l'id del bot), la seconda è la password
| Comando BotFather | A cosa serve |
|---|---|
/mybots | Il menu con tutti i tuoi bot e le impostazioni. Quasi tutto il resto si fa da qui, coi pulsanti |
/setdescription | Il testo che vede chi apre il bot prima di premere "Avvia" |
/setabouttext | La riga corta nel profilo del bot |
/setuserpic | L'immagine del profilo. Quadrata, viene ritagliata a cerchio |
/setcommands | Il menu dei comandi che compare scrivendo /. Formato: stato - Stato dei servizi, una riga per comando |
/setjoingroups | Disable se il bot è solo per te: nessuno potrà aggiungerlo ai suoi gruppi |
/setprivacy | Privacy mode nei gruppi: Enable (default) vede solo comandi e risposte, Disable vede tutto |
/revoke | Genera un token nuovo e rende inutile quello vecchio. Da usare appena sospetti una fuga |
/deletebot | Elimina il bot, token compreso |
Chat, gruppi, canali e il misterioso chat_id
Per mandare un messaggio serve sapere dove. Telegram non usa nomi: usa numeri, e qualcuno di questi è negativo.
| Tipo | chat_id | Cosa fa il bot |
|---|---|---|
| Chat privata | Positivo, es. 123456789. È l'id dell'utente | Può scrivere solo se l'utente ha premuto "Avvia" almeno una volta |
| Gruppo semplice | Negativo, es. -987654321 | Riceve comandi e risposte (privacy mode) o tutto (se admin o privacy disattivata) |
| Supergruppo | Negativo con -100 davanti, es. -1001234567890 | Come il gruppo. Un gruppo diventa supergruppo da solo quando cresce o cambi certe impostazioni, e il chat_id cambia |
| Canale | Anche lui -100…. Se è pubblico puoi usare @nomecanale | Pubblica solo se è amministratore con il diritto "Pubblica messaggi" |
🔢 Trovare il tuo id (senza bot di terzi)
- Apri il tuo bot e scrivi qualcosa, anche solo
/start. - Chiedi la posta a Telegram con
getUpdates. - Nel JSON cerca
message.from.id: quello è il tuo id utente, ed è anche il chat_id della vostra chat privata.
Per un canale: aggiungi il bot come amministratore, pubblica un messaggio nel canale e richiama getUpdates. Troverai un channel_post con chat.id che inizia per -100.
$ curl -s "https://api.telegram.org/bot$TOKEN/getUpdates" | python3 -m json.tool
{
"ok": true,
"result": [{
"update_id": 815002113,
"message": {
"message_id": 1,
"from": { "id": 123456789, "is_bot": false, "first_name": "Renzo", "username": "renzo_panocia" },
"chat": { "id": 123456789, "type": "private" },
"date": 1760180000,
"text": "/start"
}
}]
}
🛡️ Che diritti dare al bot in un canale
Il minimo indispensabile. Per un bot che pubblica basta "Pubblica messaggi", più eventualmente "Modifica messaggi altrui" e "Elimina messaggi" se deve correggere o togliere i suoi post. Mai "Aggiungi amministratori": se il token esce, il ladro si nomina admin da solo e il canale non è più tuo.
@nome quando vuole, e qualcun altro può prendersi quello vecchio.
Le chiamate: è solo HTTPS
Ogni azione è un URL: https://api.telegram.org/bot<TOKEN>/<metodo>. Parametri in GET, in form o in JSON. Risposta sempre JSON con "ok".
| Metodo | Cosa fa |
|---|---|
getMe | "Chi sono?" Verifica che il token funzioni. Il primo test da fare |
getUpdates | Ritira la posta (polling). Con offset confermi quella già letta |
sendMessage | Manda un testo a un chat_id |
sendPhoto, sendDocument | Manda un'immagine o un file: per URL, per file_id o caricandolo |
editMessageText | Modifica un messaggio già inviato dal bot. Ottimo per uno "stato" che si aggiorna |
deleteMessage | Cancella un messaggio |
answerCallbackQuery | Risponde al tocco di un pulsante (sezione 10) |
setMyCommands | Imposta il menu dei comandi dal codice, invece che da BotFather |
setWebhook, deleteWebhook, getWebhookInfo | Gestione del webhook (sezione 8) |
# il token in una variabile, letta da file: non scriverlo nella cronologia
$ TOKEN=$(cat ~/.config/tgbot/token)
# 1. il token funziona?
$ curl -s "https://api.telegram.org/bot$TOKEN/getMe"
# 2. manda un messaggio (--data-urlencode sistema spazi e accenti)
$ curl -s "https://api.telegram.org/bot$TOKEN/sendMessage" \
-d chat_id=123456789 \
--data-urlencode "text=Backup finito su $(hostname) ✅"
# 3. con un po' di formattazione HTML
$ curl -s "https://api.telegram.org/bot$TOKEN/sendMessage" \
-d chat_id=123456789 -d parse_mode=HTML \
--data-urlencode "text=<b>Disco pieno</b> su <code>/var</code>: 97%"
✍️ HTML o Markdown?
HTML. Il MarkdownV2 di Telegram vuole l'escape di _ * [ ] ( ) ~ ` > # + - = | { } . !: basta un punto in un nome di file e il messaggio non parte. Con HTML devi solo sostituire &, < e > nel testo variabile (in Python: html.escape()).
Tag ammessi: <b>, <i>, <u>, <s>, <a href>, <code>, <pre>, <blockquote>, <tg-spoiler>. Nient'altro: niente <br>, si va a capo con un a capo vero.
Altri parametri utili: disable_notification=true (arriva senza suono, per i report notturni) e link_preview_options={"is_disabled":true} (niente anteprima dei link).
📟 La ricetta: un comando di notifica per tutto il server
C'è un problema nascosto nei comandi sopra: il token sta nell'URL, e l'URL sta negli argomenti di curl. Su un server con più utenti, chiunque lancia ps aux nel momento giusto lo legge. La soluzione: l'URL in un file di configurazione di curl.
url = "https://api.telegram.org/bot7123456789:AAF3x_finto/sendMessage"
#!/bin/sh
# uso: tg-notify "testo del messaggio"
exec curl -fsS -o /dev/null --max-time 20 -K /etc/tgbot/curl.conf \
-d chat_id=123456789 --data-urlencode "text=$1"
# in cron: avvisa se il disco supera il 90%
*/15 * * * * df --output=pcent / | tail -1 | tr -dc '0-9' | \
{ read p; [ "$p" -gt 90 ] && tg-notify "⚠️ $(hostname): / al $p\%"; }
# (in crontab il % va scritto \%, altrimenti cron lo legge come "a capo")
# in systemd: avvisa quando un servizio fallisce
# /etc/systemd/system/notify@.service
[Unit]
Description=Notifica Telegram per %i
[Service]
Type=oneshot
ExecStart=/usr/local/bin/tg-notify "🔥 %i è fallito su %H"
# poi, nel servizio da sorvegliare (sezione [Unit]):
OnFailure=notify@%n.service
Polling o webhook
Vai tu a ritirare la posta, o ti fai portare la posta a casa. Per un sistemista svogliato la risposta è quasi sempre la prima.
⏳ Il long polling, spiegato
Il bot chiama getUpdates?timeout=50. Se non c'è posta, Telegram tiene la connessione aperta fino a 50 secondi e risponde appena arriva un messaggio. Quindi non è un "chiedi ogni 5 secondi": la risposta è istantanea e le richieste sono pochissime.
Ogni aggiornamento ha un update_id crescente. Alla chiamata successiva passi offset = ultimo update_id + 1: così Telegram sa che quelli li hai già letti e li butta. Se ti dimentichi l'offset, ricevi sempre gli stessi messaggi. Telegram tiene la posta non ritirata per 24 ore, poi la cancella.
| Voce | Long polling | Webhook |
|---|---|---|
| Porte in ingresso | Nessuna | Una, raggiungibile da internet (443, 80, 88 o 8443) |
| Serve | Solo uscita sulla 443 | Dominio, certificato TLS valido, reverse proxy |
| Dietro NAT/CGNAT | Funziona | Serve un tunnel o un server pubblico |
| Latenza | Istantanea | Istantanea |
| Quando conviene | Bot personali, notifiche, casa, quasi sempre | Bot con molto traffico, serverless, quando hai già un server web esposto |
| Istanze | Una sola per token (altrimenti errore 409) | Quante vuoi dietro il bilanciatore |
$ curl -s "https://api.telegram.org/bot$TOKEN/setWebhook" \
-d url=https://bot.esempio.it/tg/hook-a8f3c1 \
-d secret_token=una-stringa-lunga-e-casuale_9fK2 \
-d 'allowed_updates=["message","callback_query"]'
$ curl -s "https://api.telegram.org/bot$TOKEN/getWebhookInfo" # errori recenti e posta in coda
$ curl -s "https://api.telegram.org/bot$TOKEN/deleteWebhook" # per tornare al polling
secret_token Telegram aggiunge a ogni chiamata l'intestazione X-Telegram-Bot-Api-Secret-Token: se manca o è diversa, rispondi 403 e scarta. In più puoi accettare solo gli indirizzi di Telegram (l'elenco ufficiale è su core.telegram.org/resources/cidr.txt). E rispondi in fretta con un 200: se il tuo server ci mette troppo o dà errore, Telegram riprova e ti ritrovi i messaggi doppi.
location = /tg/hook-a8f3c1 {
if ($http_x_telegram_bot_api_secret_token != "una-stringa-lunga-e-casuale_9fK2") {
return 403;
}
proxy_pass http://127.0.0.1:8080;
}
Un bot in Python, con la sola libreria standard
Niente pip, niente venv, niente dipendenze da aggiornare. Una cinquantina di righe che girano su qualsiasi Debian con Python 3.11 o più nuovo.
token = "7123456789:AAF3x_finto-finto-finto_kQ9zVb2LmN0pQr"
owner_id = 123456789
#!/usr/bin/env python3
"""Bot minimo: risponde solo al proprietario. Solo libreria standard."""
import json, time, tomllib, urllib.request
with open("/etc/tgbot/config.toml", "rb") as f:
CFG = tomllib.load(f)
API = f"https://api.telegram.org/bot{CFG['token']}/"
OWNER = CFG["owner_id"]
def call(method, **params):
"""Chiama un metodo della Bot API e restituisce il campo result."""
req = urllib.request.Request(
API + method, data=json.dumps(params).encode(),
headers={"Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=60) as r:
return json.load(r)["result"]
def uptime():
with open("/proc/uptime") as f:
ore = float(f.read().split()[0]) / 3600
return f"Acceso da {ore:.1f} ore"
COMANDI = {"/uptime": uptime} # lista chiusa: niente comandi liberi
def handle(msg):
if msg.get("from", {}).get("id") != OWNER:
return # agli sconosciuti nemmeno un "no"
cmd = msg.get("text", "").split("@")[0] # /uptime@nomebot nei gruppi
fn = COMANDI.get(cmd)
testo = fn() if fn else "Comandi: " + " ".join(COMANDI)
call("sendMessage", chat_id=msg["chat"]["id"], text=testo)
def main():
offset = 0
while True:
try:
updates = call("getUpdates", offset=offset, timeout=50,
allowed_updates=["message"])
for u in updates:
offset = u["update_id"] + 1 # confermato: non tornerà più
if "message" in u:
handle(u["message"])
except Exception as e:
# solo il tipo e il messaggio: mai stampare l'URL, contiene il token
print("errore:", type(e).__name__, e, flush=True)
time.sleep(5)
if __name__ == "__main__":
main()
🔍 Cosa guardare nel codice
- Il controllo su
owner_idè la prima riga dihandle, prima di qualunque altra cosa. Non dopo il comando, non "solo per i comandi pericolosi". - L'offset si aggiorna prima di gestire il messaggio: se un messaggio fa crashare il bot, non lo rileggi in eterno al riavvio.
- I comandi sono un dizionario chiuso: il testo dell'utente sceglie una funzione, non diventa mai un comando di shell.
timeout=60su urlopen è più lungo deltimeout=50del long polling: altrimenti tagli tu la connessione prima che Telegram risponda.- Gli errori di rete non fermano il bot: aspetta 5 secondi e riprova. Telegram ogni tanto risponde 502, la tua connessione ogni tanto cade.
| Se vuoi una libreria | Linguaggio | Note |
|---|---|---|
| python-telegram-bot | Python | La più usata, documentazione ottima, asincrona |
| aiogram | Python | Asincrona, moderna, ottima per bot grandi |
| grammY, Telegraf | TypeScript / JavaScript | grammY gira anche su Cloudflare Workers e Deno |
| teloxide | Rust | Tipizzata fino al midollo, un binario e via |
| curl + jq | Shell | Per notifiche bastano e avanzano |
Pulsanti: il bot che chiede il permesso
I pulsanti inline stanno sotto un messaggio. Quando li tocchi non scrivi niente in chat: il bot riceve un callback_query con il dato che avevi nascosto nel pulsante.
call("sendMessage", chat_id=OWNER,
text="Nuova offerta trovata. Pubblico nel canale?",
reply_markup={"inline_keyboard": [[
{"text": "✅ Pubblica", "callback_data": "ok:42"},
{"text": "❌ Scarta", "callback_data": "no:42"},
]]})
# in main: allowed_updates=["message", "callback_query"]
# e nel ciclo: if "callback_query" in u: handle_button(u["callback_query"])
def handle_button(cq):
if cq["from"]["id"] != OWNER: # sì, anche qui
return
azione, id_ = cq["data"].split(":", 1)
if azione == "ok":
pubblica(int(id_))
# toglie la rotellina di caricamento sul telefono
call("answerCallbackQuery", callback_query_id=cq["id"],
text="Pubblicata" if azione == "ok" else "Scartata")
# toglie i pulsanti: niente doppio tocco
m = cq["message"]
call("editMessageReplyMarkup", chat_id=m["chat"]["id"],
message_id=m["message_id"], reply_markup={"inline_keyboard": []})
⌨️ L'altra tastiera
Esiste anche la reply keyboard (keyboard invece di inline_keyboard): pulsanti che sostituiscono la tastiera del telefono e, quando li tocchi, scrivono il testo in chat. Comoda per un menu fisso tipo "Stato / Riavvia / Log", ma lascia traccia in chat. Per le conferme usa sempre quelli inline.
Sicurezza: il bot è una porta sul tuo server
Un bot che risponde ai comandi è un servizio esposto a un miliardo di persone. Che il server non abbia porte aperte non cambia niente: la porta è il bot.
Fuori da git, fuori dalla chat
In un file di configurazione con chmod 600 o 640, nel .gitignore, mai incollato in una chat, in un ticket o in uno screenshot. Se esce: /revoke su BotFather, subito.
Risponde solo a te
Controllo sull'id numerico di chi scrive, su ogni messaggio e su ogni pulsante. Gli sconosciuti non ricevono risposta: nemmeno "accesso negato", che conferma che lì c'è qualcosa.
Lista chiusa
Ogni comando è una funzione scritta da te. Il testo che arriva da Telegram non finisce mai in subprocess con shell=True, in eval o in una query SQL costruita a mano.
Da fare
/setjoingroups→ Disable per i bot personali- Utente di sistema dedicato, senza shell e senza sudo
- Comandi distruttivi solo con conferma a pulsante
- Log di chi ha chiesto cosa (id, comando, ora)
- Un bot diverso per ogni progetto: se ne perdi uno, gli altri restano al sicuro
- Diritti minimi nei canali, mai "aggiungi amministratori"
secret_tokense usi il webhook
Da non fare
- Token nel codice "tanto il repo è privato"
- Token negli argomenti di un comando (si vede con
ps) - Stampare le eccezioni di
requestsohttpx: contengono l'URL, e quindi il token - Mandare password o chiavi via bot: Telegram le conserva in chiaro
- Controllare l'utente con l'
@username, che si può cambiare - Un bot che esegue qualunque comando di shell gli scrivi
- Far girare il bot come root
grep -r "AAF3x" /var/log/ ~/.bash_history (con i caratteri del tuo, ovvio). Se c'è, rigeneralo.
🔐 E la privacy di chi scrive?
Il bot riceve id, nome e username di chiunque gli scriva. Se lo apri al pubblico, quello che salvi diventa un trattamento di dati personali: salva il minimo, cancella quello che non serve, e scrivi nella descrizione cosa fa il bot. Per un bot che usi solo tu il problema non si pone: l'unico id che salvi è il tuo.
Sul server: systemd, firewall e proxy
Il bot è un servizio come un altro: un utente suo, un'unità systemd, un file di configurazione e un'uscita controllata.
# useradd --system --home-dir /var/lib/tgbot --create-home --shell /usr/sbin/nologin tgbot
# install -d -m 750 -o root -g tgbot /etc/tgbot
# install -m 640 -o root -g tgbot config.toml /etc/tgbot/config.toml
# install -D -m 755 bot.py /opt/tgbot/bot.py
[Unit]
Description=Bot Telegram
After=network-online.target
Wants=network-online.target
[Service]
User=tgbot
Group=tgbot
ExecStart=/usr/bin/python3 /opt/tgbot/bot.py
Restart=always
RestartSec=10
# se passi da un proxy (vedi sotto)
#Environment=https_proxy=http://proxy.lan:3128
# la gabbia: il bot non può toccare quasi niente
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
ReadWritePaths=/var/lib/tgbot
[Install]
WantedBy=multi-user.target
# systemctl daemon-reload
# systemctl enable --now tgbot
# journalctl -u tgbot -f # i print() finiscono qui
🧱 Firewall in uscita
Se il server ha un firewall anche in uscita (e dovrebbe), al bot basta la 443 verso Telegram, più il DNS. Telegram pubblica i suoi blocchi di indirizzi in core.telegram.org/resources/cidr.txt, IPv4 e IPv6: tra questi c'è 149.154.160.0/20, dove risponde api.telegram.org. Prendi l'elenco da lì e aggiornalo ogni tanto: gli indirizzi cambiano raramente, ma cambiano.
Se il server ha IPv6 ma la rete IPv6 è rotta, Python prova prima IPv6 e resta appeso fino al timeout prima di provare IPv4: il sintomo è un bot che risponde con un minuto di ritardo. Sistema IPv6 o, nel frattempo, bloccalo in modo pulito (rifiuto, non scarto silenzioso), così il programma passa subito a IPv4.
🌐 Proxy: tre cose diverse con lo stesso nome
| Cosa | A chi serve | Come |
|---|---|---|
| Proxy HTTP (CONNECT) | Al bot, se il server esce solo da un proxy aziendale o da Squid | La Bot API è HTTPS normale. urllib legge da solo la variabile https_proxy; con curl -x http://proxy:3128. Il proxy vede solo api.telegram.org:443, non il token |
| Proxy SOCKS5 | Al bot, per uscire da un'altra rete (es. un tunnel SSH -D) | Non c'è nella libreria standard: httpx[socks] o requests[socks]. Usa socks5h:// per risolvere anche il DNS dall'altra parte |
| MTProxy | Alle app Telegram, dove Telegram è bloccato | Parla MTProto, non HTTPS: il tuo bot non lo può usare. Nato per il blocco russo del 2018 |
Attenzione ai proxy che ispezionano il TLS (Squid con ssl-bump, i firewall "next generation" aziendali): decifrano il traffico, vedono l'URL completo e lo scrivono nei log. Con lui, il tuo token.
🏗️ Il server Bot API in casa
telegram-bot-api è lo stesso programma che risponde su api.telegram.org, open source. Lo compili, lo avvii con l'api_id e l'api_hash presi da my.telegram.org e il bot chiama http://127.0.0.1:8081/bot<TOKEN>/… invece di Telegram. Lui parla MTProto con i data center al posto tuo.
- Pro: file caricati fino a 2000 MB invece di 50, download senza limite, webhook anche in HTTP locale.
- Contro: un servizio in più da compilare e aggiornare. Prima di spostare il bot devi chiamare
logOutsul server ufficiale. - Serve? Solo se il bot manda file grossi: backup, video. Per notifiche e comandi, no.
I limiti (che scopri sempre il giorno sbagliato)
Telegram non pubblica una tabella ufficiale completa. Questi sono i numeri della documentazione e quelli che tutti incontrano.
| Cosa | Limite | Cosa fare |
|---|---|---|
| Messaggi nella stessa chat | Circa 1 al secondo | Raggruppa: un messaggio con 10 righe invece di 10 messaggi |
| Messaggi nello stesso gruppo | 20 al minuto | Coda con pausa tra un invio e l'altro |
| Messaggi in totale | Circa 30 al secondo | Per gli invii di massa, una coda che rispetta il ritmo |
| Lunghezza del testo | 4096 caratteri | Spezza, o manda un file con sendDocument |
| Didascalia di foto e file | 1024 caratteri | Testo lungo in un messaggio a parte |
| callback_data | 64 byte | Solo azione e id, i dati nel database |
| File inviati dal bot | 50 MB (2000 MB col server locale) | Comprimi, o server Bot API locale |
| File scaricati dal bot | 20 MB (nessun limite col server locale) | Come sopra |
| Posta non ritirata | 24 ore | Un bot spento per due giorni perde i messaggi vecchi |
| Messaggi di altri bot | Mai ricevuti | Due bot non possono parlarsi in un gruppo: scelta voluta, contro i loop infiniti |
| Scrivere per primo | Vietato | L'utente deve aver premuto "Avvia" almeno una volta |
{
"ok": false,
"error_code": 429,
"description": "Too Many Requests: retry after 35",
"parameters": { "retry_after": 35 }
}
# aspetta ESATTAMENTE retry_after secondi, poi riprova. Non prima:
# chi insiste si prende pause sempre più lunghe.
Errori tipici, tradotti
Telegram risponde sempre con "ok": false e una description. Ecco cosa vuole dire davvero.
| Errore | Traduzione | Rimedio |
|---|---|---|
401 Unauthorized | Il token è sbagliato o è stato revocato | Ricopia il token, attento a spazi e a capo finali nel file |
400 Bad Request: chat not found | Il chat_id non esiste, oppure il bot non ci è mai entrato | Controlla segno e -100; fai premere "Avvia"; aggiungi il bot al gruppo o al canale |
403 Forbidden: bot can't initiate conversation with a user | L'utente non ha mai avviato il bot | Deve aprire il bot e premere "Avvia" |
403 Forbidden: bot was blocked by the user | Ti hanno bloccato | Smetti di scrivergli e toglilo dalla lista |
400 Bad Request: need administrator rights in the channel chat | Il bot è nel canale ma non è admin, o non può pubblicare | Rendilo admin con "Pubblica messaggi" |
400 Bad Request: can't parse entities | Il tuo HTML o Markdown è rotto | Un tag non chiuso o un < nel testo: usa html.escape() sulle parti variabili |
400 Bad Request: message is too long | Oltre 4096 caratteri | Spezza o manda un file |
400 Bad Request: message is not modified | Hai chiesto di modificare un messaggio con lo stesso testo | Innocuo: ignoralo, o confronta prima |
400 Bad Request: group chat was upgraded to a supergroup chat | Il gruppo è diventato supergruppo e ha cambiato id | Il nuovo id è in parameters.migrate_to_chat_id: aggiorna la configurazione |
400 Bad Request: query is too old and response timeout expired | Hai risposto a un pulsante troppo tardi | Chiama answerCallbackQuery subito, poi fai il lavoro lento |
409 Conflict: terminated by other getUpdates request | Stanno girando due copie del bot con lo stesso token | Cerca l'altra: un vecchio tmux, il portatile, un container dimenticato. Oppure qualcuno ha il tuo token |
409 Conflict: can't use getUpdates method while webhook is active | C'è ancora un webhook impostato | deleteWebhook, poi torni al polling |
429 Too Many Requests: retry after N | Stai mandando troppo | Aspetta N secondi (sezione 13) |
502 Bad Gateway | Telegram ha un momento no | Riprova fra qualche secondo. Succede |
systemctl status tgbot: gira? 2. journalctl -u tgbot: errori? 3. getMe da curl: il token va? 4. getWebhookInfo: c'è un webhook dimenticato? 5. curl -v https://api.telegram.org dal server: esce, o il firewall lo blocca? Il 90% dei casi finisce entro il punto 3.
Da dove continuare
La documentazione di Telegram è una delle poche che si legge volentieri. Lunga, ma chiara.
🗺️ Un percorso in quattro tappe
- Oggi: crea un bot, fai
getMe,getUpdatesesendMessagecon curl. Quindici minuti. - Questa settimana:
tg-notifysul server, collegato a cron e aOnFailuredi systemd. Da qui in poi saprai dei guasti prima degli utenti. - Poi: il bot Python della sezione 9 con due o tre comandi di sola lettura e il controllo su
owner_id, sotto systemd con un utente dedicato. - Dopo: pulsanti per le conferme, un database SQLite per lo stato, un canale pubblicato dal bot.
| Risorsa | Cos'è |
|---|---|
| Bot API (core.telegram.org/bots/api) | Il riferimento completo di tutti i metodi e tipi. Una pagina sola, si cerca con Ctrl+F |
| Bots: An introduction for developers (core.telegram.org/bots) | L'introduzione ufficiale: cosa possono fare i bot e cosa no |
| Bot FAQ (core.telegram.org/bots/faq) | Limiti, privacy mode, webhook: le risposte alle domande che ti farai |
| Webhook guide (core.telegram.org/bots/webhooks) | Certificati, porte, errori del webhook |
| telegram-bot-api (github.com/tdlib/telegram-bot-api) | Il server Bot API da far girare in casa |
| python-telegram-bot (docs.python-telegram-bot.org) | Quando il bot cresce oltre le 200 righe |
| Bot API changelog (core.telegram.org/bots/api-changelog) | Esce una versione nuova ogni pochi mesi: cose nuove, quasi mai rotture |