Svogliati
✈️

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.

↓
01 / 15

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.

💡 Prima di Telegram, VKontakte

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.

Agosto 2013

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.

2014

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.

Giugno 2015

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.

Settembre 2015

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.

2016

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.

2018 – 2020

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.

Novembre 2020

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.

2022 – 2024

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".

2025

Un miliardo di utenti

E un numero imprecisato di bot che ti avvisano che il backup è fallito. Il nostro preferito.

02 / 15

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.

🧠 Il vero motivoLa Bot API è una delle API più semplici che esistano: URL, parametri, risposta JSON. Se sai usare curl, sai già usare un bot Telegram. Il resto della guida serve a non farti male.
03 / 15

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
StrumentoProContro
Bot TelegramGratis, istantaneo, pulsanti, gruppi e canali, API semplicissimaServer di terzi, niente end-to-end per i bot, serve un account con numero di telefono
EmailUniversale, archiviabile, la ricevono tuttiLenta da leggere, finisce nello spam, inviarla bene (SPF/DKIM) è un mestiere
ntfy / GotifySelf-hosted, semplice come un curl, nessun accountUn server in più da tenere vivo; senza Google su Android la notifica push dipende dal tuo server
MatrixFederato, 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 veraNessuna API ufficiale per i bot, serve un numero dedicato, fragile
Slack / Discord webhookComodi se il team vive già lìServer di terzi pure loro, limiti sui piani gratuiti
SMSArriva anche senza datiCosta, è lento, e lo legge anche l'operatore
⚠️ La regola del secondo canalePer gli allarmi che contano davvero, Telegram è il primo avviso, non l'unico. Una mail o un altro sistema di riserva non costa niente e ti salva il giorno in cui Telegram è irraggiungibile, o il tuo server non riesce più a uscire su internet. Che è spesso proprio il guasto di cui volevi essere avvisato.
04 / 15

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.

📮 L'ufficio postale

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.

il giro di un messaggio
  📱 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
REGOLA 1

È 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.

REGOLA 2

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.

REGOLA 3

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.
🤖 Bot API e "userbot" non sono la stessa cosaLibrerie come Telethon o Pyrogram parlano direttamente MTProto e possono comandare un account normale, il tuo numero di telefono. Fanno cose che un bot non può fare, ma se le usi male l'account viene limitato o bannato. Per notifiche e comandi la Bot API basta e avanza: questa guida parla solo di quella.
05 / 15

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

  1. Apri Telegram e cerca @BotFather, quello con la spunta blu. Diffida delle imitazioni.
  2. Scrivi /newbot.
  3. Dagli un nome visibile, che puoi cambiare quando vuoi (es. "Allarmi Casa").
  4. Dagli uno username: unico, deve finire con bot (es. allarmi_casa_bot). Questo invece resta quello.
  5. BotFather ti risponde con il token. Copialo subito in un file con permessi stretti, non in una chat e non nel codice.
com'è fatto un token (finto)
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 BotFatherA cosa serve
/mybotsIl menu con tutti i tuoi bot e le impostazioni. Quasi tutto il resto si fa da qui, coi pulsanti
/setdescriptionIl testo che vede chi apre il bot prima di premere "Avvia"
/setabouttextLa riga corta nel profilo del bot
/setuserpicL'immagine del profilo. Quadrata, viene ritagliata a cerchio
/setcommandsIl menu dei comandi che compare scrivendo /. Formato: stato - Stato dei servizi, una riga per comando
/setjoingroupsDisable se il bot è solo per te: nessuno potrà aggiungerlo ai suoi gruppi
/setprivacyPrivacy mode nei gruppi: Enable (default) vede solo comandi e risposte, Disable vede tutto
/revokeGenera un token nuovo e rende inutile quello vecchio. Da usare appena sospetti una fuga
/deletebotElimina il bot, token compreso
🔎 Il bot si trova con la ricercaQualunque bot è pubblico: chiunque può cercarlo per username e premere "Avvia". Non esiste un bot privato. La riservatezza la fai tu nel codice, rispondendo solo a chi conosci (sezione 11). Un username anonimo aiuta a non attirare curiosi, ma non è una protezione.
06 / 15

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.

Tipochat_idCosa fa il bot
Chat privataPositivo, es. 123456789. È l'id dell'utentePuò scrivere solo se l'utente ha premuto "Avvia" almeno una volta
Gruppo sempliceNegativo, es. -987654321Riceve comandi e risposte (privacy mode) o tutto (se admin o privacy disattivata)
SupergruppoNegativo con -100 davanti, es. -1001234567890Come il gruppo. Un gruppo diventa supergruppo da solo quando cresce o cambi certe impostazioni, e il chat_id cambia
CanaleAnche lui -100…. Se è pubblico puoi usare @nomecanalePubblica solo se è amministratore con il diritto "Pubblica messaggi"

🔢 Trovare il tuo id (senza bot di terzi)

  1. Apri il tuo bot e scrivi qualcosa, anche solo /start.
  2. Chiedi la posta a Telegram con getUpdates.
  3. 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.

bash
$ curl -s "https://api.telegram.org/bot$TOKEN/getUpdates" | python3 -m json.tool
risposta (accorciata)
{
  "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.

📛 Gli username cambiano, gli id noNel codice salva sempre l'id numerico, mai l'username. Un utente può cambiare @nome quando vuole, e qualcun altro può prendersi quello vecchio.
07 / 15

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".

MetodoCosa fa
getMe"Chi sono?" Verifica che il token funzioni. Il primo test da fare
getUpdatesRitira la posta (polling). Con offset confermi quella già letta
sendMessageManda un testo a un chat_id
sendPhoto, sendDocumentManda un'immagine o un file: per URL, per file_id o caricandolo
editMessageTextModifica un messaggio già inviato dal bot. Ottimo per uno "stato" che si aggiorna
deleteMessageCancella un messaggio
answerCallbackQueryRisponde al tocco di un pulsante (sezione 10)
setMyCommandsImposta il menu dei comandi dal codice, invece che da BotFather
setWebhook, deleteWebhook, getWebhookInfoGestione del webhook (sezione 8)
bash · le prime tre chiamate
# 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.

/etc/tgbot/curl.conf (chmod 600)
url = "https://api.telegram.org/bot7123456789:AAF3x_finto/sendMessage"
/usr/local/bin/tg-notify
#!/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"
usi tipici
# 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
08 / 15

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.

VoceLong pollingWebhook
Porte in ingressoNessunaUna, raggiungibile da internet (443, 80, 88 o 8443)
ServeSolo uscita sulla 443Dominio, certificato TLS valido, reverse proxy
Dietro NAT/CGNATFunzionaServe un tunnel o un server pubblico
LatenzaIstantaneaIstantanea
Quando convieneBot personali, notifiche, casa, quasi sempreBot con molto traffico, serverless, quando hai già un server web esposto
IstanzeUna sola per token (altrimenti errore 409)Quante vuoi dietro il bilanciatore
bash · impostare un webhook
$ 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
🔏 Il webhook va protettoIl tuo URL è pubblico: chiunque lo scopra può mandarci finti aggiornamenti. Con 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.
nginx · solo con il segreto giusto
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;
}
09 / 15

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.

/etc/tgbot/config.toml (root:tgbot, chmod 640)
token = "7123456789:AAF3x_finto-finto-finto_kQ9zVb2LmN0pQr"
owner_id = 123456789
/opt/tgbot/bot.py
#!/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 di handle, 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=60 su urlopen è più lungo del timeout=50 del 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 libreriaLinguaggioNote
python-telegram-botPythonLa più usata, documentazione ottima, asincrona
aiogramPythonAsincrona, moderna, ottima per bot grandi
grammY, TelegrafTypeScript / JavaScriptgrammY gira anche su Cloudflare Workers e Deno
teloxideRustTipizzata fino al midollo, un binario e via
curl + jqShellPer notifiche bastano e avanzano
10 / 15

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.

python · chiedere una conferma
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"},
     ]]})
python · gestire il tocco
# 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": []})
📏 callback_data è piccoloAl massimo 64 byte. Dentro ci metti un'azione e un id, non l'oggetto intero: i dati veri restano nel tuo database (SQLite basta e avanza). E siccome a toccare il pulsante può essere chiunque veda il messaggio, per esempio in un gruppo, il controllo su chi l'ha toccato va rifatto qui.

⌨️ 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.

11 / 15

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.

TOKEN

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.

PADRONE

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.

COMANDI

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_token se 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 requests o httpx: 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
🕵️ Il token nei log: la fuga più comuneIl token è dentro l'URL di ogni chiamata. Finisce nei messaggi d'errore delle librerie HTTP, nella cronologia della shell, nei log di un proxy che ispeziona il TLS, negli argomenti dei processi. Prima di mettere un bot in produzione, cerca un pezzo del token nei log: 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.

12 / 15

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.

installazione
# 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
/etc/systemd/system/tgbot.service
[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
bash
# 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

CosaA chi serveCome
Proxy HTTP (CONNECT)Al bot, se il server esce solo da un proxy aziendale o da SquidLa 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 SOCKS5Al 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
MTProxyAlle app Telegram, dove Telegram è bloccatoParla 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 logOut sul server ufficiale.
  • Serve? Solo se il bot manda file grossi: backup, video. Per notifiche e comandi, no.
13 / 15

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.

CosaLimiteCosa fare
Messaggi nella stessa chatCirca 1 al secondoRaggruppa: un messaggio con 10 righe invece di 10 messaggi
Messaggi nello stesso gruppo20 al minutoCoda con pausa tra un invio e l'altro
Messaggi in totaleCirca 30 al secondoPer gli invii di massa, una coda che rispetta il ritmo
Lunghezza del testo4096 caratteriSpezza, o manda un file con sendDocument
Didascalia di foto e file1024 caratteriTesto lungo in un messaggio a parte
callback_data64 byteSolo azione e id, i dati nel database
File inviati dal bot50 MB (2000 MB col server locale)Comprimi, o server Bot API locale
File scaricati dal bot20 MB (nessun limite col server locale)Come sopra
Posta non ritirata24 oreUn bot spento per due giorni perde i messaggi vecchi
Messaggi di altri botMai ricevutiDue bot non possono parlarsi in un gruppo: scelta voluta, contro i loop infiniti
Scrivere per primoVietatoL'utente deve aver premuto "Avvia" almeno una volta
la risposta quando esageri
{
  "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.
14 / 15

Errori tipici, tradotti

Telegram risponde sempre con "ok": false e una description. Ecco cosa vuole dire davvero.

ErroreTraduzioneRimedio
401 UnauthorizedIl token è sbagliato o è stato revocatoRicopia il token, attento a spazi e a capo finali nel file
400 Bad Request: chat not foundIl chat_id non esiste, oppure il bot non ci è mai entratoControlla segno e -100; fai premere "Avvia"; aggiungi il bot al gruppo o al canale
403 Forbidden: bot can't initiate conversation with a userL'utente non ha mai avviato il botDeve aprire il bot e premere "Avvia"
403 Forbidden: bot was blocked by the userTi hanno bloccatoSmetti di scrivergli e toglilo dalla lista
400 Bad Request: need administrator rights in the channel chatIl bot è nel canale ma non è admin, o non può pubblicareRendilo admin con "Pubblica messaggi"
400 Bad Request: can't parse entitiesIl tuo HTML o Markdown è rottoUn tag non chiuso o un < nel testo: usa html.escape() sulle parti variabili
400 Bad Request: message is too longOltre 4096 caratteriSpezza o manda un file
400 Bad Request: message is not modifiedHai chiesto di modificare un messaggio con lo stesso testoInnocuo: ignoralo, o confronta prima
400 Bad Request: group chat was upgraded to a supergroup chatIl gruppo è diventato supergruppo e ha cambiato idIl nuovo id è in parameters.migrate_to_chat_id: aggiorna la configurazione
400 Bad Request: query is too old and response timeout expiredHai risposto a un pulsante troppo tardiChiama answerCallbackQuery subito, poi fai il lavoro lento
409 Conflict: terminated by other getUpdates requestStanno girando due copie del bot con lo stesso tokenCerca 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 activeC'è ancora un webhook impostatodeleteWebhook, poi torni al polling
429 Too Many Requests: retry after NStai mandando troppoAspetta N secondi (sezione 13)
502 Bad GatewayTelegram ha un momento noRiprova fra qualche secondo. Succede
🩺 Il bot non risponde? In ordine1. 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.
15 / 15

Da dove continuare

La documentazione di Telegram è una delle poche che si legge volentieri. Lunga, ma chiara.

🗺️ Un percorso in quattro tappe

  1. Oggi: crea un bot, fai getMe, getUpdates e sendMessage con curl. Quindici minuti.
  2. Questa settimana: tg-notify sul server, collegato a cron e a OnFailure di systemd. Da qui in poi saprai dei guasti prima degli utenti.
  3. 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.
  4. Dopo: pulsanti per le conferme, un database SQLite per lo stato, un canale pubblicato dal bot.
RisorsaCos'è
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
✈️ L'ultimo consiglio da svogliatoIl bot migliore è quello che ti scrive poco. Se ogni notte ti manda venti messaggi "tutto ok", in una settimana smetti di leggerli e il ventunesimo, quello vero, lo perdi. Silenzio quando va tutto bene, una riga chiara quando va male. E il token, sempre, fuori dal codice.